diff options
Diffstat (limited to 'documentation/ref-manual')
57 files changed, 23037 insertions, 39 deletions
diff --git a/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb b/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb new file mode 100644 index 0000000000..aa2beb9a9b --- /dev/null +++ b/documentation/ref-manual/examples/hello-autotools/hello_2.10.bb | |||
@@ -0,0 +1,9 @@ | |||
1 | DESCRIPTION = "GNU Helloworld application" | ||
2 | SECTION = "examples" | ||
3 | LICENSE = "GPLv3" | ||
4 | LIC_FILES_CHKSUM = "file://COPYING;md5=d32239bcb673463ab874e80d47fae504" | ||
5 | |||
6 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz" | ||
7 | SRC_URI[sha256sum] = "31e066137a962676e89f69d1b65382de95a7ef7d914b8cb956f41ea72e0f516b" | ||
8 | |||
9 | inherit autotools-brokensep gettext | ||
diff --git a/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb deleted file mode 100644 index 5dfb0b30cf..0000000000 --- a/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb +++ /dev/null | |||
@@ -1,8 +0,0 @@ | |||
1 | DESCRIPTION = "GNU Helloworld application" | ||
2 | SECTION = "examples" | ||
3 | LICENSE = "GPLv3" | ||
4 | LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010" | ||
5 | |||
6 | SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2" | ||
7 | |||
8 | inherit autotools | ||
diff --git a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb index b58d4d7bd1..c0c8986405 100644 --- a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb +++ b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb | |||
@@ -1,4 +1,4 @@ | |||
1 | require xorg-lib-common.inc | 1 | require recipes-graphics/xorg-lib/xorg-lib-common.inc |
2 | 2 | ||
3 | DESCRIPTION = "X11 Pixmap library" | 3 | DESCRIPTION = "X11 Pixmap library" |
4 | LICENSE = "X-BSD" | 4 | LICENSE = "X-BSD" |
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst new file mode 100644 index 0000000000..2d2aaad0a9 --- /dev/null +++ b/documentation/ref-manual/faq.rst | |||
@@ -0,0 +1,451 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | *** | ||
4 | FAQ | ||
5 | *** | ||
6 | |||
7 | **Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__? | ||
8 | |||
9 | **A:** The term ``Poky`` refers to the specific reference build | ||
10 | system that the Yocto Project provides. Poky is based on | ||
11 | :term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the | ||
12 | generic term used here for the build system is the "OpenEmbedded build | ||
13 | system." Development in the Yocto Project using Poky is closely tied to | ||
14 | OpenEmbedded, with changes always being merged to OE-Core or BitBake | ||
15 | first before being pulled back into Poky. This practice benefits both | ||
16 | projects immediately. | ||
17 | |||
18 | **Q:** My development system does not meet the required Git, tar, and | ||
19 | Python versions. In particular, I do not have Python 3.5.0 or greater. | ||
20 | Can I still use the Yocto Project? | ||
21 | |||
22 | **A:** You can get the required tools on your host development system a | ||
23 | couple different ways (i.e. building a tarball or downloading a | ||
24 | tarball). See the "`Required Git, tar, Python and gcc | ||
25 | Versions <#required-git-tar-python-and-gcc-versions>`__" section for | ||
26 | steps on how to update your build tools. | ||
27 | |||
28 | **Q:** How can you claim Poky / OpenEmbedded-Core is stable? | ||
29 | |||
30 | **A:** There are three areas that help with stability; | ||
31 | |||
32 | - The Yocto Project team keeps :term:`OpenEmbedded-Core (OE-Core)` small and | ||
33 | focused, containing around 830 recipes as opposed to the thousands | ||
34 | available in other OpenEmbedded community layers. Keeping it small | ||
35 | makes it easy to test and maintain. | ||
36 | |||
37 | - The Yocto Project team runs manual and automated tests using a small, | ||
38 | fixed set of reference hardware as well as emulated targets. | ||
39 | |||
40 | - The Yocto Project uses an autobuilder, which provides continuous | ||
41 | build and integration tests. | ||
42 | |||
43 | **Q:** How do I get support for my board added to the Yocto Project? | ||
44 | |||
45 | **A:** Support for an additional board is added by creating a Board | ||
46 | Support Package (BSP) layer for it. For more information on how to | ||
47 | create a BSP layer, see the | ||
48 | ":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`" | ||
49 | section in the Yocto Project Development Tasks Manual and the | ||
50 | :doc:`../bsp-guide/bsp-guide`. | ||
51 | |||
52 | Usually, if the board is not completely exotic, adding support in the | ||
53 | Yocto Project is fairly straightforward. | ||
54 | |||
55 | **Q:** Are there any products built using the OpenEmbedded build system? | ||
56 | |||
57 | **A:** The software running on the `Vernier | ||
58 | LabQuest <http://vernier.com/labquest/>`__ is built using the | ||
59 | OpenEmbedded build system. See the `Vernier | ||
60 | LabQuest <http://www.vernier.com/products/interfaces/labq/>`__ website | ||
61 | for more information. There are a number of pre-production devices using | ||
62 | the OpenEmbedded build system and the Yocto Project team announces them | ||
63 | as soon as they are released. | ||
64 | |||
65 | **Q:** What does the OpenEmbedded build system produce as output? | ||
66 | |||
67 | **A:** Because you can use the same set of recipes to create output of | ||
68 | various formats, the output of an OpenEmbedded build depends on how you | ||
69 | start it. Usually, the output is a flashable image ready for the target | ||
70 | device. | ||
71 | |||
72 | **Q:** How do I add my package to the Yocto Project? | ||
73 | |||
74 | **A:** To add a package, you need to create a BitBake recipe. For | ||
75 | information on how to create a BitBake recipe, see the | ||
76 | ":ref:`dev-manual/dev-manual-common-tasks:writing a new recipe`" | ||
77 | section in the Yocto Project Development Tasks Manual. | ||
78 | |||
79 | **Q:** Do I have to reflash my entire board with a new Yocto Project | ||
80 | image when recompiling a package? | ||
81 | |||
82 | **A:** The OpenEmbedded build system can build packages in various | ||
83 | formats such as IPK for OPKG, Debian package (``.deb``), or RPM. You can | ||
84 | then upgrade the packages using the package tools on the device, much | ||
85 | like on a desktop distribution such as Ubuntu or Fedora. However, | ||
86 | package management on the target is entirely optional. | ||
87 | |||
88 | **Q:** I see the error | ||
89 | '``chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x``'. What is | ||
90 | wrong? | ||
91 | |||
92 | **A:** You are probably running the build on an NTFS filesystem. Use | ||
93 | ``ext2``, ``ext3``, or ``ext4`` instead. | ||
94 | |||
95 | **Q:** I see lots of 404 responses for files when the OpenEmbedded build | ||
96 | system is trying to download sources. Is something wrong? | ||
97 | |||
98 | **A:** Nothing is wrong. The OpenEmbedded build system checks any | ||
99 | configured source mirrors before downloading from the upstream sources. | ||
100 | The build system does this searching for both source archives and | ||
101 | pre-checked out versions of SCM-managed software. These checks help in | ||
102 | large installations because it can reduce load on the SCM servers | ||
103 | themselves. The address above is one of the default mirrors configured | ||
104 | into the build system. Consequently, if an upstream source disappears, | ||
105 | the team can place sources there so builds continue to work. | ||
106 | |||
107 | **Q:** I have machine-specific data in a package for one machine only | ||
108 | but the package is being marked as machine-specific in all cases, how do | ||
109 | I prevent this? | ||
110 | |||
111 | **A:** Set ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` = "0" in the ``.bb`` file | ||
112 | but make sure the package is manually marked as machine-specific for the | ||
113 | case that needs it. The code that handles | ||
114 | ``SRC_URI_OVERRIDES_PACKAGE_ARCH`` is in the | ||
115 | ``meta/classes/base.bbclass`` file. | ||
116 | |||
117 | **Q:** I'm behind a firewall and need to use a proxy server. How do I do | ||
118 | that? | ||
119 | |||
120 | **A:** Most source fetching by the OpenEmbedded build system is done by | ||
121 | ``wget`` and you therefore need to specify the proxy settings in a | ||
122 | ``.wgetrc`` file, which can be in your home directory if you are a | ||
123 | single user or can be in ``/usr/local/etc/wgetrc`` as a global user | ||
124 | file. | ||
125 | |||
126 | Following is the applicable code for setting various proxy types in the | ||
127 | ``.wgetrc`` file. By default, these settings are disabled with comments. | ||
128 | To use them, remove the comments: :: | ||
129 | |||
130 | # You can set the default proxies for Wget to use for http, https, and ftp. | ||
131 | # They will override the value in the environment. | ||
132 | #https_proxy = http://proxy.yoyodyne.com:18023/ | ||
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 | |||
139 | The Yocto Project also includes a | ||
140 | ``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS | ||
141 | and Git proxy servers if needed. For more information on setting up | ||
142 | various proxy types and configuring proxy servers, see the | ||
143 | ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" | ||
144 | Wiki page. | ||
145 | |||
146 | **Q:** What's the difference between target and target\ ``-native``? | ||
147 | |||
148 | **A:** The ``*-native`` targets are designed to run on the system being | ||
149 | used for the build. These are usually tools that are needed to assist | ||
150 | the build in some way such as ``quilt-native``, which is used to apply | ||
151 | patches. The non-native version is the one that runs on the target | ||
152 | device. | ||
153 | |||
154 | **Q:** I'm seeing random build failures. Help?! | ||
155 | |||
156 | **A:** If the same build is failing in totally different and random | ||
157 | ways, the most likely explanation is: | ||
158 | |||
159 | - The hardware you are running the build on has some problem. | ||
160 | |||
161 | - You are running the build under virtualization, in which case the | ||
162 | virtualization probably has bugs. | ||
163 | |||
164 | The OpenEmbedded build system processes a massive amount of data that | ||
165 | causes lots of network, disk and CPU activity and is sensitive to even | ||
166 | single-bit failures in any of these areas. True random failures have | ||
167 | always been traced back to hardware or virtualization issues. | ||
168 | |||
169 | **Q:** When I try to build a native recipe, the build fails with | ||
170 | ``iconv.h`` problems. | ||
171 | |||
172 | **A:** If you get an error message that indicates GNU ``libiconv`` is | ||
173 | not in use but ``iconv.h`` has been included from ``libiconv``, you need | ||
174 | to check to see if you have a previously installed version of the header | ||
175 | file in ``/usr/local/include``. | ||
176 | :: | ||
177 | |||
178 | #error GNU libiconv not in use but included iconv.h is from libiconv | ||
179 | |||
180 | If you find a previously installed | ||
181 | file, you should either uninstall it or temporarily rename it and try | ||
182 | the build again. | ||
183 | |||
184 | This issue is just a single manifestation of "system leakage" issues | ||
185 | caused when the OpenEmbedded build system finds and uses previously | ||
186 | installed files during a native build. This type of issue might not be | ||
187 | limited to ``iconv.h``. Be sure that leakage cannot occur from | ||
188 | ``/usr/local/include`` and ``/opt`` locations. | ||
189 | |||
190 | **Q:** What do we need to ship for license compliance? | ||
191 | |||
192 | **A:** This is a difficult question and you need to consult your lawyer | ||
193 | for the answer for your specific case. It is worth bearing in mind that | ||
194 | for GPL compliance, there needs to be enough information shipped to | ||
195 | allow someone else to rebuild and produce the same end result you are | ||
196 | shipping. This means sharing the source code, any patches applied to it, | ||
197 | and also any configuration information about how that package was | ||
198 | configured and built. | ||
199 | |||
200 | You can find more information on licensing in the | ||
201 | ":ref:`overview-manual/overview-manual-development-environment:licensing`" | ||
202 | section in the Yocto | ||
203 | Project Overview and Concepts Manual and also in the | ||
204 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
205 | section in the Yocto Project Development Tasks Manual. | ||
206 | |||
207 | **Q:** How do I disable the cursor on my touchscreen device? | ||
208 | |||
209 | **A:** You need to create a form factor file as described in the | ||
210 | ":ref:`bsp-filelayout-misc-recipes`" section in | ||
211 | the Yocto Project Board Support Packages (BSP) Developer's Guide. Set | ||
212 | the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: | ||
213 | :: | ||
214 | |||
215 | HAVE_TOUCHSCREEN=1 | ||
216 | |||
217 | **Q:** How do I make sure connected network interfaces are brought up by | ||
218 | default? | ||
219 | |||
220 | **A:** The default interfaces file provided by the netbase recipe does | ||
221 | not automatically bring up network interfaces. Therefore, you will need | ||
222 | to add a BSP-specific netbase that includes an interfaces file. See the | ||
223 | ":ref:`bsp-filelayout-misc-recipes`" section in | ||
224 | the Yocto Project Board Support Packages (BSP) Developer's Guide for | ||
225 | information on creating these types of miscellaneous recipe files. | ||
226 | |||
227 | For example, add the following files to your layer: :: | ||
228 | |||
229 | meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces | ||
230 | meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend | ||
231 | |||
232 | **Q:** How do I create images with more free space? | ||
233 | |||
234 | **A:** By default, the OpenEmbedded build system creates images that are | ||
235 | 1.3 times the size of the populated root filesystem. To affect the image | ||
236 | size, you need to set various configurations: | ||
237 | |||
238 | - *Image Size:* The OpenEmbedded build system uses the | ||
239 | :term:`IMAGE_ROOTFS_SIZE` variable to define | ||
240 | the size of the image in Kbytes. The build system determines the size | ||
241 | by taking into account the initial root filesystem size before any | ||
242 | modifications such as requested size for the image and any requested | ||
243 | additional free disk space to be added to the image. | ||
244 | |||
245 | - *Overhead:* Use the | ||
246 | :term:`IMAGE_OVERHEAD_FACTOR` variable | ||
247 | to define the multiplier that the build system applies to the initial | ||
248 | image size, which is 1.3 by default. | ||
249 | |||
250 | - *Additional Free Space:* Use the | ||
251 | :term:`IMAGE_ROOTFS_EXTRA_SPACE` | ||
252 | variable to add additional free space to the image. The build system | ||
253 | adds this space to the image after it determines its | ||
254 | ``IMAGE_ROOTFS_SIZE``. | ||
255 | |||
256 | **Q:** Why don't you support directories with spaces in the pathnames? | ||
257 | |||
258 | **A:** The Yocto Project team has tried to do this before but too many | ||
259 | of the tools the OpenEmbedded build system depends on, such as | ||
260 | ``autoconf``, break when they find spaces in pathnames. Until that | ||
261 | situation changes, the team will not support spaces in pathnames. | ||
262 | |||
263 | **Q:** How do I use an external toolchain? | ||
264 | |||
265 | **A:** The toolchain configuration is very flexible and customizable. It | ||
266 | is primarily controlled with the ``TCMODE`` variable. This variable | ||
267 | controls which ``tcmode-*.inc`` file to include from the | ||
268 | ``meta/conf/distro/include`` directory within the :term:`Source Directory`. | ||
269 | |||
270 | The default value of ``TCMODE`` is "default", which tells the | ||
271 | OpenEmbedded build system to use its internally built toolchain (i.e. | ||
272 | ``tcmode-default.inc``). However, other patterns are accepted. In | ||
273 | particular, "external-\*" refers to external toolchains. One example is | ||
274 | the Sourcery G++ Toolchain. The support for this toolchain resides in | ||
275 | the separate ``meta-sourcery`` layer at | ||
276 | http://github.com/MentorEmbedded/meta-sourcery/. | ||
277 | |||
278 | In addition to the toolchain configuration, you also need a | ||
279 | corresponding toolchain recipe file. This recipe file needs to package | ||
280 | up any pre-built objects in the toolchain such as ``libgcc``, | ||
281 | ``libstdcc++``, any locales, and ``libc``. | ||
282 | |||
283 | **Q:** How does the OpenEmbedded build system obtain source code and | ||
284 | will it work behind my firewall or proxy server? | ||
285 | |||
286 | **A:** The way the build system obtains source code is highly | ||
287 | configurable. You can setup the build system to get source code in most | ||
288 | environments if HTTP transport is available. | ||
289 | |||
290 | When the build system searches for source code, it first tries the local | ||
291 | download directory. If that location fails, Poky tries | ||
292 | :term:`PREMIRRORS`, the upstream source, and then | ||
293 | :term:`MIRRORS` in that order. | ||
294 | |||
295 | Assuming your distribution is "poky", the OpenEmbedded build system uses | ||
296 | the Yocto Project source ``PREMIRRORS`` by default for SCM-based | ||
297 | sources, upstreams for normal tarballs, and then falls back to a number | ||
298 | of other mirrors including the Yocto Project source mirror if those | ||
299 | fail. | ||
300 | |||
301 | As an example, you could add a specific server for the build system to | ||
302 | attempt before any others by adding something like the following to the | ||
303 | ``local.conf`` configuration file: :: | ||
304 | |||
305 | PREMIRRORS_prepend = "\ | ||
306 | git://.*/.* http://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" | ||
310 | |||
311 | These changes cause the build system to intercept Git, FTP, HTTP, and | ||
312 | HTTPS requests and direct them to the ``http://`` sources mirror. You | ||
313 | can use ``file://`` URLs to point to local directories or network shares | ||
314 | as well. | ||
315 | |||
316 | Aside from the previous technique, these options also exist: | ||
317 | :: | ||
318 | |||
319 | BB_NO_NETWORK = "1" | ||
320 | |||
321 | This statement tells BitBake to issue an error | ||
322 | instead of trying to access the Internet. This technique is useful if | ||
323 | you want to ensure code builds only from local sources. | ||
324 | |||
325 | Here is another technique: | ||
326 | :: | ||
327 | |||
328 | BB_FETCH_PREMIRRORONLY = "1" | ||
329 | |||
330 | This statement | ||
331 | limits the build system to pulling source from the ``PREMIRRORS`` only. | ||
332 | Again, this technique is useful for reproducing builds. | ||
333 | |||
334 | Here is another technique: | ||
335 | :: | ||
336 | |||
337 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
338 | |||
339 | This | ||
340 | statement tells the build system to generate mirror tarballs. This | ||
341 | technique is useful if you want to create a mirror server. If not, | ||
342 | however, the technique can simply waste time during the build. | ||
343 | |||
344 | Finally, consider an example where you are behind an HTTP-only firewall. | ||
345 | You could make the following changes to the ``local.conf`` configuration | ||
346 | file as long as the ``PREMIRRORS`` server is current: :: | ||
347 | |||
348 | PREMIRRORS_prepend = "\ | ||
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 | |||
354 | These changes would cause the build system to successfully fetch source | ||
355 | over HTTP and any network accesses to anything other than the | ||
356 | ``PREMIRRORS`` would fail. | ||
357 | |||
358 | The build system also honors the standard shell environment variables | ||
359 | ``http_proxy``, ``ftp_proxy``, ``https_proxy``, and ``all_proxy`` to | ||
360 | redirect requests through proxy servers. | ||
361 | |||
362 | .. note:: | ||
363 | |||
364 | You can find more information on the | ||
365 | ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" | ||
366 | Wiki page. | ||
367 | |||
368 | **Q:** Can I get rid of build output so I can start over? | ||
369 | |||
370 | **A:** Yes - you can easily do this. When you use BitBake to build an | ||
371 | image, all the build output goes into the directory created when you run | ||
372 | the build environment setup script (i.e. | ||
373 | ````` <#structure-core-script>`__). By default, this :term:`Build Directory` | ||
374 | is named ``build`` but can be named | ||
375 | anything you want. | ||
376 | |||
377 | Within the Build Directory, is the ``tmp`` directory. To remove all the | ||
378 | build output yet preserve any source code or downloaded files from | ||
379 | previous builds, simply remove the ``tmp`` directory. | ||
380 | |||
381 | **Q:** Why do ``${bindir}`` and ``${libdir}`` have strange values for | ||
382 | ``-native`` recipes? | ||
383 | |||
384 | **A:** Executables and libraries might need to be used from a directory | ||
385 | other than the directory into which they were initially installed. | ||
386 | Complicating this situation is the fact that sometimes these executables | ||
387 | and libraries are compiled with the expectation of being run from that | ||
388 | initial installation target directory. If this is the case, moving them | ||
389 | causes problems. | ||
390 | |||
391 | This scenario is a fundamental problem for package maintainers of | ||
392 | mainstream Linux distributions as well as for the OpenEmbedded build | ||
393 | system. As such, a well-established solution exists. Makefiles, | ||
394 | Autotools configuration scripts, and other build systems are expected to | ||
395 | respect environment variables such as ``bindir``, ``libdir``, and | ||
396 | ``sysconfdir`` that indicate where executables, libraries, and data | ||
397 | reside when a program is actually run. They are also expected to respect | ||
398 | a ``DESTDIR`` environment variable, which is prepended to all the other | ||
399 | variables when the build system actually installs the files. It is | ||
400 | understood that the program does not actually run from within | ||
401 | ``DESTDIR``. | ||
402 | |||
403 | When the OpenEmbedded build system uses a recipe to build a | ||
404 | target-architecture program (i.e. one that is intended for inclusion on | ||
405 | the image being built), that program eventually runs from the root file | ||
406 | system of that image. Thus, the build system provides a value of | ||
407 | "/usr/bin" for ``bindir``, a value of "/usr/lib" for ``libdir``, and so | ||
408 | forth. | ||
409 | |||
410 | Meanwhile, ``DESTDIR`` is a path within the :term:`Build Directory`. | ||
411 | However, when the recipe builds a | ||
412 | native program (i.e. one that is intended to run on the build machine), | ||
413 | that program is never installed directly to the build machine's root | ||
414 | file system. Consequently, the build system uses paths within the Build | ||
415 | Directory for ``DESTDIR``, ``bindir`` and related variables. To better | ||
416 | understand this, consider the following two paths where the first is | ||
417 | relatively 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 | ||
425 | |||
426 | .. note:: | ||
427 | |||
428 | Due to these lengthy examples, the paths are artificially broken | ||
429 | across lines for readability. | ||
430 | |||
431 | Even if the paths look unusual, | ||
432 | they both are correct - the first for a target and the second for a | ||
433 | native recipe. These paths are a consequence of the ``DESTDIR`` | ||
434 | mechanism and while they appear strange, they are correct and in | ||
435 | practice very effective. | ||
436 | |||
437 | **Q:** The files provided by my ``*-native`` recipe do not appear to be | ||
438 | available to other recipes. Files are missing from the native sysroot, | ||
439 | my recipe is installing to the wrong place, or I am getting permissions | ||
440 | errors during the do_install task in my recipe! What is wrong? | ||
441 | |||
442 | **A:** This situation results when a build system does not recognize the | ||
443 | environment variables supplied to it by :term:`BitBake`. The | ||
444 | incident that prompted this FAQ entry involved a Makefile that used an | ||
445 | environment variable named ``BINDIR`` instead of the more standard | ||
446 | variable ``bindir``. The makefile's hardcoded default value of | ||
447 | "/usr/bin" worked most of the time, but not for the recipe's ``-native`` | ||
448 | variant. For another example, permissions errors might be caused by a | ||
449 | Makefile that ignores ``DESTDIR`` or uses a different name for that | ||
450 | environment variable. Check the the build system to see if these kinds | ||
451 | of issues exist. | ||
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml index d94cb32a86..2f8fcf3242 100644 --- a/documentation/ref-manual/faq.xml +++ b/documentation/ref-manual/faq.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='faq'> | 6 | <chapter id='faq'> |
6 | <title>FAQ</title> | 7 | <title>FAQ</title> |
@@ -322,7 +323,7 @@ | |||
322 | <qandaentry> | 323 | <qandaentry> |
323 | <question> | 324 | <question> |
324 | <para> | 325 | <para> |
325 | What’s the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>? | 326 | What's the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>? |
326 | </para> | 327 | </para> |
327 | </question> | 328 | </question> |
328 | <answer> | 329 | <answer> |
diff --git a/documentation/ref-manual/history.rst b/documentation/ref-manual/history.rst new file mode 100644 index 0000000000..e962d92978 --- /dev/null +++ b/documentation/ref-manual/history.rst | |||
@@ -0,0 +1,74 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | *********************** | ||
4 | Manual Revision History | ||
5 | *********************** | ||
6 | |||
7 | .. list-table:: | ||
8 | :widths: 10 15 40 | ||
9 | :header-rows: 1 | ||
10 | |||
11 | * - Revision | ||
12 | - Date | ||
13 | - Note | ||
14 | * - 0.9 | ||
15 | - November 2010 | ||
16 | - The initial document released with the Yocto Project 0.9 Release | ||
17 | * - 1.0 | ||
18 | - April 2011 | ||
19 | - Released with the Yocto Project 1.0 Release. | ||
20 | * - 1.1 | ||
21 | - October 2011 | ||
22 | - Released with the Yocto Project 1.1 Release. | ||
23 | * - 1.2 | ||
24 | - April 2012 | ||
25 | - Released with the Yocto Project 1.2 Release. | ||
26 | * - 1.3 | ||
27 | - October 2012 | ||
28 | - Released with the Yocto Project 1.3 Release. | ||
29 | * - 1.4 | ||
30 | - April 2013 | ||
31 | - Released with the Yocto Project 1.4 Release. | ||
32 | * - 1.5 | ||
33 | - October 2013 | ||
34 | - Released with the Yocto Project 1.5 Release. | ||
35 | * - 1.6 | ||
36 | - April 2014 | ||
37 | - Released with the Yocto Project 1.6 Release. | ||
38 | * - 1.7 | ||
39 | - October 2014 | ||
40 | - Released with the Yocto Project 1.7 Release. | ||
41 | * - 1.8 | ||
42 | - April 2015 | ||
43 | - Released with the Yocto Project 1.8 Release. | ||
44 | * - 2.0 | ||
45 | - October 2015 | ||
46 | - Released with the Yocto Project 2.0 Release. | ||
47 | * - 2.1 | ||
48 | - April 2016 | ||
49 | - Released with the Yocto Project 2.1 Release. | ||
50 | * - 2.2 | ||
51 | - October 2016 | ||
52 | - Released with the Yocto Project 2.2 Release. | ||
53 | * - 2.3 | ||
54 | - May 2017 | ||
55 | - Released with the Yocto Project 2.3 Release. | ||
56 | * - 2.4 | ||
57 | - October 2017 | ||
58 | - Released with the Yocto Project 2.4 Release. | ||
59 | * - 2.5 | ||
60 | - May 2018 | ||
61 | - Released with the Yocto Project 2.5 Release. | ||
62 | * - 2.6 | ||
63 | - November 2018 | ||
64 | - Released with the Yocto Project 2.6 Release. | ||
65 | * - 2.7 | ||
66 | - May 2019 | ||
67 | - Released with the Yocto Project 2.7 Release. | ||
68 | * - 3.0 | ||
69 | - October 2019 | ||
70 | - Released with the Yocto Project 3.0 Release. | ||
71 | * - 3.1 | ||
72 | - April 2020 | ||
73 | - Released with the Yocto Project 3.1 Release. | ||
74 | |||
diff --git a/documentation/ref-manual/migration-1.3.rst b/documentation/ref-manual/migration-1.3.rst new file mode 100644 index 0000000000..ebbc238873 --- /dev/null +++ b/documentation/ref-manual/migration-1.3.rst | |||
@@ -0,0 +1,195 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | Moving to the Yocto Project 1.3 Release | ||
4 | ======================================= | ||
5 | |||
6 | This section provides migration information for moving to the Yocto | ||
7 | Project 1.3 Release from the prior release. | ||
8 | |||
9 | .. _1.3-local-configuration: | ||
10 | |||
11 | Local Configuration | ||
12 | ------------------- | ||
13 | |||
14 | Differences include changes for | ||
15 | :term:`SSTATE_MIRRORS` and ``bblayers.conf``. | ||
16 | |||
17 | .. _migration-1.3-sstate-mirrors: | ||
18 | |||
19 | SSTATE_MIRRORS | ||
20 | ~~~~~~~~~~~~~~ | ||
21 | |||
22 | The shared state cache (sstate-cache), as pointed to by | ||
23 | :term:`SSTATE_DIR`, by default now has two-character | ||
24 | subdirectories to prevent issues arising from too many files in the same | ||
25 | directory. Also, native sstate-cache packages, which are built to run on | ||
26 | the host system, will go into a subdirectory named using the distro ID | ||
27 | string. If you copy the newly structured sstate-cache to a mirror | ||
28 | location (either local or remote) and then point to it in | ||
29 | :term:`SSTATE_MIRRORS`, you need to append "PATH" | ||
30 | to the end of the mirror URL so that the path used by BitBake before the | ||
31 | mirror substitution is appended to the path used to access the mirror. | ||
32 | Here is an example: :: | ||
33 | |||
34 | SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" | ||
35 | |||
36 | .. _migration-1.3-bblayers-conf: | ||
37 | |||
38 | bblayers.conf | ||
39 | ~~~~~~~~~~~~~ | ||
40 | |||
41 | The ``meta-yocto`` layer consists of two parts that correspond to the | ||
42 | Poky reference distribution and the reference hardware Board Support | ||
43 | Packages (BSPs), respectively: ``meta-yocto`` and ``meta-yocto-bsp``. | ||
44 | When running BitBake for the first time after upgrading, your | ||
45 | ``conf/bblayers.conf`` file will be updated to handle this change and | ||
46 | you will be asked to re-run or restart for the changes to take effect. | ||
47 | |||
48 | .. _1.3-recipes: | ||
49 | |||
50 | Recipes | ||
51 | ------- | ||
52 | |||
53 | Differences include changes for the following: | ||
54 | |||
55 | .. _migration-1.3-python-function-whitespace: | ||
56 | |||
57 | Python Function Whitespace | ||
58 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
59 | |||
60 | All Python functions must now use four spaces for indentation. | ||
61 | Previously, an inconsistent mix of spaces and tabs existed, which made | ||
62 | extending these functions using ``_append`` or ``_prepend`` complicated | ||
63 | given that Python treats whitespace as syntactically significant. If you | ||
64 | are defining or extending any Python functions (e.g. | ||
65 | ``populate_packages``, ``do_unpack``, ``do_patch`` and so forth) in | ||
66 | custom recipes or classes, you need to ensure you are using consistent | ||
67 | four-space indentation. | ||
68 | |||
69 | .. _migration-1.3-proto=-in-src-uri: | ||
70 | |||
71 | proto= in SRC_URI | ||
72 | ~~~~~~~~~~~~~~~~~ | ||
73 | |||
74 | Any use of ``proto=`` in :term:`SRC_URI` needs to be | ||
75 | changed to ``protocol=``. In particular, this applies to the following | ||
76 | URIs: | ||
77 | |||
78 | - ``svn://`` | ||
79 | |||
80 | - ``bzr://`` | ||
81 | |||
82 | - ``hg://`` | ||
83 | |||
84 | - ``osc://`` | ||
85 | |||
86 | Other URIs were already using ``protocol=``. This change improves | ||
87 | consistency. | ||
88 | |||
89 | .. _migration-1.3-nativesdk: | ||
90 | |||
91 | nativesdk | ||
92 | ~~~~~~~~~ | ||
93 | |||
94 | The suffix ``nativesdk`` is now implemented as a prefix, which | ||
95 | simplifies a lot of the packaging code for ``nativesdk`` recipes. All | ||
96 | custom ``nativesdk`` recipes, which are relocatable packages that are | ||
97 | native to :term:`SDK_ARCH`, and any references need to | ||
98 | be updated to use ``nativesdk-*`` instead of ``*-nativesdk``. | ||
99 | |||
100 | .. _migration-1.3-task-recipes: | ||
101 | |||
102 | Task Recipes | ||
103 | ~~~~~~~~~~~~ | ||
104 | |||
105 | "Task" recipes are now known as "Package groups" and have been renamed | ||
106 | from ``task-*.bb`` to ``packagegroup-*.bb``. Existing references to the | ||
107 | previous ``task-*`` names should work in most cases as there is an | ||
108 | automatic upgrade path for most packages. However, you should update | ||
109 | references in your own recipes and configurations as they could be | ||
110 | removed in future releases. You should also rename any custom ``task-*`` | ||
111 | recipes to ``packagegroup-*``, and change them to inherit | ||
112 | ``packagegroup`` instead of ``task``, as well as taking the opportunity | ||
113 | to remove anything now handled by ``packagegroup.bbclass``, such as | ||
114 | providing ``-dev`` and ``-dbg`` packages, setting | ||
115 | :term:`LIC_FILES_CHKSUM`, and so forth. See the | ||
116 | ":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section for | ||
117 | further details. | ||
118 | |||
119 | .. _migration-1.3-image-features: | ||
120 | |||
121 | IMAGE_FEATURES | ||
122 | ~~~~~~~~~~~~~~ | ||
123 | |||
124 | Image recipes that previously included "apps-console-core" in | ||
125 | :term:`IMAGE_FEATURES` should now include "splash" | ||
126 | instead to enable the boot-up splash screen. Retaining | ||
127 | "apps-console-core" will still include the splash screen but generates a | ||
128 | warning. The "apps-x11-core" and "apps-x11-games" ``IMAGE_FEATURES`` | ||
129 | features have been removed. | ||
130 | |||
131 | .. _migration-1.3-removed-recipes: | ||
132 | |||
133 | Removed Recipes | ||
134 | ~~~~~~~~~~~~~~~ | ||
135 | |||
136 | The following recipes have been removed. For most of them, it is | ||
137 | unlikely that you would have any references to them in your own | ||
138 | :term:`Metadata`. However, you should check your metadata | ||
139 | against this list to be sure: | ||
140 | |||
141 | - ``libx11-trim``: Replaced by ``libx11``, which has a negligible | ||
142 | size difference with modern Xorg. | ||
143 | |||
144 | - ``xserver-xorg-lite``: Use ``xserver-xorg``, which has a negligible | ||
145 | size difference when DRI and GLX modules are not installed. | ||
146 | |||
147 | - ``xserver-kdrive``: Effectively unmaintained for many years. | ||
148 | |||
149 | - ``mesa-xlib``: No longer serves any purpose. | ||
150 | |||
151 | - ``galago``: Replaced by telepathy. | ||
152 | |||
153 | - ``gail``: Functionality was integrated into GTK+ 2.13. | ||
154 | |||
155 | - ``eggdbus``: No longer needed. | ||
156 | |||
157 | - ``gcc-*-intermediate``: The build has been restructured to avoid | ||
158 | the need for this step. | ||
159 | |||
160 | - ``libgsmd``: Unmaintained for many years. Functionality now | ||
161 | provided by ``ofono`` instead. | ||
162 | |||
163 | - *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM | ||
164 | application suite. It has been moved to ``meta-gnome`` in | ||
165 | ``meta-openembedded``. | ||
166 | |||
167 | In addition to the previously listed changes, the ``meta-demoapps`` | ||
168 | directory has also been removed because the recipes in it were not being | ||
169 | maintained and many had become obsolete or broken. Additionally, these | ||
170 | recipes were not parsed in the default configuration. Many of these | ||
171 | recipes are already provided in an updated and maintained form within | ||
172 | the OpenEmbedded community layers such as ``meta-oe`` and | ||
173 | ``meta-gnome``. For the remainder, you can now find them in the | ||
174 | ``meta-extras`` repository, which is in the | ||
175 | :yocto_git:`Source Repositories <>` at | ||
176 | http://git.yoctoproject.org/cgit/cgit.cgi/meta-extras/. | ||
177 | |||
178 | .. _1.3-linux-kernel-naming: | ||
179 | |||
180 | Linux Kernel Naming | ||
181 | ------------------- | ||
182 | |||
183 | The naming scheme for kernel output binaries has been changed to now | ||
184 | include :term:`PE` as part of the filename: | ||
185 | :: | ||
186 | |||
187 | KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" | ||
188 | |||
189 | Because the ``PE`` variable is not set by default, these binary files | ||
190 | could result with names that include two dash characters. Here is an | ||
191 | example: :: | ||
192 | |||
193 | bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin | ||
194 | |||
195 | |||
diff --git a/documentation/ref-manual/migration-1.4.rst b/documentation/ref-manual/migration-1.4.rst new file mode 100644 index 0000000000..a658bdff68 --- /dev/null +++ b/documentation/ref-manual/migration-1.4.rst | |||
@@ -0,0 +1,237 @@ | |||
1 | Moving to the Yocto Project 1.4 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.4 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.4-bitbake: | ||
8 | |||
9 | BitBake | ||
10 | ------- | ||
11 | |||
12 | Differences include the following: | ||
13 | |||
14 | - *Comment Continuation:* If a comment ends with a line continuation | ||
15 | (\) character, then the next line must also be a comment. Any | ||
16 | instance where this is not the case, now triggers a warning. You must | ||
17 | either remove the continuation character, or be sure the next line is | ||
18 | a comment. | ||
19 | |||
20 | - *Package Name Overrides:* The runtime package specific variables | ||
21 | :term:`RDEPENDS`, | ||
22 | :term:`RRECOMMENDS`, | ||
23 | :term:`RSUGGESTS`, | ||
24 | :term:`RPROVIDES`, | ||
25 | :term:`RCONFLICTS`, | ||
26 | :term:`RREPLACES`, :term:`FILES`, | ||
27 | :term:`ALLOW_EMPTY`, and the pre, post, install, | ||
28 | and uninstall script functions ``pkg_preinst``, ``pkg_postinst``, | ||
29 | ``pkg_prerm``, and ``pkg_postrm`` should always have a package name | ||
30 | override. For example, use ``RDEPENDS_${PN}`` for the main package | ||
31 | instead of ``RDEPENDS``. BitBake uses more strict checks when it | ||
32 | parses recipes. | ||
33 | |||
34 | .. _migration-1.4-build-behavior: | ||
35 | |||
36 | Build Behavior | ||
37 | -------------- | ||
38 | |||
39 | Differences include the following: | ||
40 | |||
41 | - *Shared State Code:* The shared state code has been optimized to | ||
42 | avoid running unnecessary tasks. For example, the following no longer | ||
43 | populates the target sysroot since that is not necessary: | ||
44 | :: | ||
45 | |||
46 | $ bitbake -c rootfs some-image | ||
47 | |||
48 | Instead, the system just needs to extract the | ||
49 | output package contents, re-create the packages, and construct the | ||
50 | root filesystem. This change is unlikely to cause any problems unless | ||
51 | you have missing declared dependencies. | ||
52 | |||
53 | - *Scanning Directory Names:* When scanning for files in | ||
54 | :term:`SRC_URI`, the build system now uses | ||
55 | :term:`FILESOVERRIDES` instead of | ||
56 | :term:`OVERRIDES` for the directory names. In | ||
57 | general, the values previously in ``OVERRIDES`` are now in | ||
58 | ``FILESOVERRIDES`` as well. However, if you relied upon an additional | ||
59 | value you previously added to ``OVERRIDES``, you might now need to | ||
60 | add it to ``FILESOVERRIDES`` unless you are already adding it through | ||
61 | the :term:`MACHINEOVERRIDES` or | ||
62 | :term:`DISTROOVERRIDES` variables, as | ||
63 | appropriate. For more related changes, see the | ||
64 | "`Variables <#migration-1.4-variables>`__" section. | ||
65 | |||
66 | .. _migration-1.4-proxies-and-fetching-source: | ||
67 | |||
68 | Proxies and Fetching Source | ||
69 | --------------------------- | ||
70 | |||
71 | A new ``oe-git-proxy`` script has been added to replace previous methods | ||
72 | of handling proxies and fetching source from Git. See the | ||
73 | ``meta-yocto/conf/site.conf.sample`` file for information on how to use | ||
74 | this script. | ||
75 | |||
76 | .. _migration-1.4-custom-interfaces-file-netbase-change: | ||
77 | |||
78 | Custom Interfaces File (netbase change) | ||
79 | --------------------------------------- | ||
80 | |||
81 | If you have created your own custom ``etc/network/interfaces`` file by | ||
82 | creating an append file for the ``netbase`` recipe, you now need to | ||
83 | create an append file for the ``init-ifupdown`` recipe instead, which | ||
84 | you can find in the :term:`Source Directory` at | ||
85 | ``meta/recipes-core/init-ifupdown``. For information on how to use | ||
86 | append files, see the | ||
87 | ":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`" | ||
88 | section in the Yocto Project Development Tasks Manual. | ||
89 | |||
90 | .. _migration-1.4-remote-debugging: | ||
91 | |||
92 | Remote Debugging | ||
93 | ---------------- | ||
94 | |||
95 | Support for remote debugging with the Eclipse IDE is now separated into | ||
96 | an image feature (``eclipse-debug``) that corresponds to the | ||
97 | ``packagegroup-core-eclipse-debug`` package group. Previously, the | ||
98 | debugging feature was included through the ``tools-debug`` image | ||
99 | feature, which corresponds to the ``packagegroup-core-tools-debug`` | ||
100 | package group. | ||
101 | |||
102 | .. _migration-1.4-variables: | ||
103 | |||
104 | Variables | ||
105 | --------- | ||
106 | |||
107 | The following variables have changed: | ||
108 | |||
109 | - ``SANITY_TESTED_DISTROS``: This variable now uses a distribution | ||
110 | ID, which is composed of the host distributor ID followed by the | ||
111 | release. Previously, | ||
112 | :term:`SANITY_TESTED_DISTROS` was | ||
113 | composed of the description field. For example, "Ubuntu 12.10" | ||
114 | becomes "Ubuntu-12.10". You do not need to worry about this change if | ||
115 | you are not specifically setting this variable, or if you are | ||
116 | specifically setting it to "". | ||
117 | |||
118 | - ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``, | ||
119 | ``${``\ :term:`PF`\ ``}``, | ||
120 | ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories | ||
121 | have been dropped from the default value of the | ||
122 | :term:`FILESPATH` variable, which is used as the | ||
123 | search path for finding files referred to in | ||
124 | :term:`SRC_URI`. If you have a recipe that relied upon | ||
125 | these directories, which would be unusual, then you will need to add | ||
126 | the appropriate paths within the recipe or, alternatively, rearrange | ||
127 | the files. The most common locations are still covered by ``${BP}``, | ||
128 | ``${BPN}``, and "files", which all remain in the default value of | ||
129 | :term:`FILESPATH`. | ||
130 | |||
131 | .. _migration-target-package-management-with-rpm: | ||
132 | |||
133 | Target Package Management with RPM | ||
134 | ---------------------------------- | ||
135 | |||
136 | If runtime package management is enabled and the RPM backend is | ||
137 | selected, Smart is now installed for package download, dependency | ||
138 | resolution, and upgrades instead of Zypper. For more information on how | ||
139 | to use Smart, run the following command on the target: | ||
140 | :: | ||
141 | |||
142 | smart --help | ||
143 | |||
144 | .. _migration-1.4-recipes-moved: | ||
145 | |||
146 | Recipes Moved | ||
147 | ------------- | ||
148 | |||
149 | The following recipes were moved from their previous locations because | ||
150 | they are no longer used by anything in the OpenEmbedded-Core: | ||
151 | |||
152 | - ``clutter-box2d``: Now resides in the ``meta-oe`` layer. | ||
153 | |||
154 | - ``evolution-data-server``: Now resides in the ``meta-gnome`` layer. | ||
155 | |||
156 | - ``gthumb``: Now resides in the ``meta-gnome`` layer. | ||
157 | |||
158 | - ``gtkhtml2``: Now resides in the ``meta-oe`` layer. | ||
159 | |||
160 | - ``gupnp``: Now resides in the ``meta-multimedia`` layer. | ||
161 | |||
162 | - ``gypsy``: Now resides in the ``meta-oe`` layer. | ||
163 | |||
164 | - ``libcanberra``: Now resides in the ``meta-gnome`` layer. | ||
165 | |||
166 | - ``libgdata``: Now resides in the ``meta-gnome`` layer. | ||
167 | |||
168 | - ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer. | ||
169 | |||
170 | - ``metacity``: Now resides in the ``meta-gnome`` layer. | ||
171 | |||
172 | - ``polkit``: Now resides in the ``meta-oe`` layer. | ||
173 | |||
174 | - ``zeroconf``: Now resides in the ``meta-networking`` layer. | ||
175 | |||
176 | .. _migration-1.4-removals-and-renames: | ||
177 | |||
178 | Removals and Renames | ||
179 | -------------------- | ||
180 | |||
181 | The following list shows what has been removed or renamed: | ||
182 | |||
183 | - ``evieext``: Removed because it has been removed from ``xserver`` | ||
184 | since 2008. | ||
185 | |||
186 | - *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer | ||
187 | supports it as of version 2.18. | ||
188 | |||
189 | - ``libxfontcache / xfontcacheproto``: Removed because they were | ||
190 | removed from the Xorg server in 2008. | ||
191 | |||
192 | - ``libxp / libxprintapputil / libxprintutil / printproto``: Removed | ||
193 | because the XPrint server was removed from Xorg in 2008. | ||
194 | |||
195 | - ``libxtrap / xtrapproto``: Removed because their functionality was | ||
196 | broken upstream. | ||
197 | |||
198 | - *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being | ||
199 | added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part | ||
200 | of the release. | ||
201 | |||
202 | - ``lsbsetup``: Removed with functionality now provided by | ||
203 | ``lsbtest``. | ||
204 | |||
205 | - ``matchbox-stroke``: Removed because it was never more than a | ||
206 | proof-of-concept. | ||
207 | |||
208 | - ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are | ||
209 | not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato`` | ||
210 | are still provided. | ||
211 | |||
212 | - ``mesa-dri``: Renamed to ``mesa``. | ||
213 | |||
214 | - ``mesa-xlib``: Removed because it was no longer useful. | ||
215 | |||
216 | - ``mutter``: Removed because nothing ever uses it and the recipe is | ||
217 | very old. | ||
218 | |||
219 | - ``orinoco-conf``: Removed because it has become obsolete. | ||
220 | |||
221 | - ``update-modules``: Removed because it is no longer used. The | ||
222 | kernel module ``postinstall`` and ``postrm`` scripts can now do the | ||
223 | same task without the use of this script. | ||
224 | |||
225 | - ``web``: Removed because it is not maintained. Superseded by | ||
226 | ``web-webkit``. | ||
227 | |||
228 | - ``xf86bigfontproto``: Removed because upstream it has been disabled | ||
229 | by default since 2007. Nothing uses ``xf86bigfontproto``. | ||
230 | |||
231 | - ``xf86rushproto``: Removed because its dependency in ``xserver`` | ||
232 | was spurious and it was removed in 2005. | ||
233 | |||
234 | - ``zypper / libzypp / sat-solver``: Removed and been functionally | ||
235 | replaced with Smart (``python-smartpm``) when RPM packaging is used | ||
236 | and package management is enabled on the target. | ||
237 | |||
diff --git a/documentation/ref-manual/migration-1.5.rst b/documentation/ref-manual/migration-1.5.rst new file mode 100644 index 0000000000..fa6ff92f10 --- /dev/null +++ b/documentation/ref-manual/migration-1.5.rst | |||
@@ -0,0 +1,355 @@ | |||
1 | Moving to the Yocto Project 1.5 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.5 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.5-host-dependency-changes: | ||
8 | |||
9 | Host Dependency Changes | ||
10 | ----------------------- | ||
11 | |||
12 | The OpenEmbedded build system now has some additional requirements on | ||
13 | the host system: | ||
14 | |||
15 | - Python 2.7.3+ | ||
16 | |||
17 | - Tar 1.24+ | ||
18 | |||
19 | - Git 1.7.8+ | ||
20 | |||
21 | - Patched version of Make if you are using 3.82. Most distributions | ||
22 | that provide Make 3.82 use the patched version. | ||
23 | |||
24 | If the Linux distribution you are using on your build host does not | ||
25 | provide packages for these, you can install and use the Buildtools | ||
26 | tarball, which provides an SDK-like environment containing them. | ||
27 | |||
28 | For more information on this requirement, see the "`Required Git, tar, | ||
29 | Python and gcc Versions <#required-git-tar-python-and-gcc-versions>`__" | ||
30 | section. | ||
31 | |||
32 | .. _migration-1.5-atom-pc-bsp: | ||
33 | |||
34 | ``atom-pc`` Board Support Package (BSP) | ||
35 | --------------------------------------- | ||
36 | |||
37 | The ``atom-pc`` hardware reference BSP has been replaced by a | ||
38 | ``genericx86`` BSP. This BSP is not necessarily guaranteed to work on | ||
39 | all x86 hardware, but it will run on a wider range of systems than the | ||
40 | ``atom-pc`` did. | ||
41 | |||
42 | .. note:: | ||
43 | |||
44 | Additionally, a | ||
45 | genericx86-64 | ||
46 | BSP has been added for 64-bit Atom systems. | ||
47 | |||
48 | .. _migration-1.5-bitbake: | ||
49 | |||
50 | BitBake | ||
51 | ------- | ||
52 | |||
53 | The following changes have been made that relate to BitBake: | ||
54 | |||
55 | - BitBake now supports a ``_remove`` operator. The addition of this | ||
56 | operator means you will have to rename any items in recipe space | ||
57 | (functions, variables) whose names currently contain ``_remove_`` or | ||
58 | end with ``_remove`` to avoid unexpected behavior. | ||
59 | |||
60 | - BitBake's global method pool has been removed. This method is not | ||
61 | particularly useful and led to clashes between recipes containing | ||
62 | functions that had the same name. | ||
63 | |||
64 | - The "none" server backend has been removed. The "process" server | ||
65 | backend has been serving well as the default for a long time now. | ||
66 | |||
67 | - The ``bitbake-runtask`` script has been removed. | ||
68 | |||
69 | - ``${``\ :term:`P`\ ``}`` and | ||
70 | ``${``\ :term:`PF`\ ``}`` are no longer added to | ||
71 | :term:`PROVIDES` by default in ``bitbake.conf``. | ||
72 | These version-specific ``PROVIDES`` items were seldom used. | ||
73 | Attempting to use them could result in two versions being built | ||
74 | simultaneously rather than just one version due to the way BitBake | ||
75 | resolves dependencies. | ||
76 | |||
77 | .. _migration-1.5-qa-warnings: | ||
78 | |||
79 | QA Warnings | ||
80 | ----------- | ||
81 | |||
82 | The following changes have been made to the package QA checks: | ||
83 | |||
84 | - If you have customized :term:`ERROR_QA` or | ||
85 | :term:`WARN_QA` values in your configuration, check | ||
86 | that they contain all of the issues that you wish to be reported. | ||
87 | Previous Yocto Project versions contained a bug that meant that any | ||
88 | item not mentioned in ``ERROR_QA`` or ``WARN_QA`` would be treated as | ||
89 | a warning. Consequently, several important items were not already in | ||
90 | the default value of ``WARN_QA``. All of the possible QA checks are | ||
91 | now documented in the ":ref:`insane.bbclass <ref-classes-insane>`" | ||
92 | section. | ||
93 | |||
94 | - An additional QA check has been added to check if | ||
95 | ``/usr/share/info/dir`` is being installed. Your recipe should delete | ||
96 | this file within :ref:`ref-tasks-install` if "make | ||
97 | install" is installing it. | ||
98 | |||
99 | - If you are using the buildhistory class, the check for the package | ||
100 | version going backwards is now controlled using a standard QA check. | ||
101 | Thus, if you have customized your ``ERROR_QA`` or ``WARN_QA`` values | ||
102 | and still wish to have this check performed, you should add | ||
103 | "version-going-backwards" to your value for one or the other | ||
104 | variables depending on how you wish it to be handled. See the | ||
105 | documented QA checks in the | ||
106 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | ||
107 | |||
108 | .. _migration-1.5-directory-layout-changes: | ||
109 | |||
110 | Directory Layout Changes | ||
111 | ------------------------ | ||
112 | |||
113 | The following directory changes exist: | ||
114 | |||
115 | - Output SDK installer files are now named to include the image name | ||
116 | and tuning architecture through the :term:`SDK_NAME` | ||
117 | variable. | ||
118 | |||
119 | - Images and related files are now installed into a directory that is | ||
120 | specific to the machine, instead of a parent directory containing | ||
121 | output files for multiple machines. The | ||
122 | :term:`DEPLOY_DIR_IMAGE` variable continues | ||
123 | to point to the directory containing images for the current | ||
124 | :term:`MACHINE` and should be used anywhere there is a | ||
125 | need to refer to this directory. The ``runqemu`` script now uses this | ||
126 | variable to find images and kernel binaries and will use BitBake to | ||
127 | determine the directory. Alternatively, you can set the | ||
128 | ``DEPLOY_DIR_IMAGE`` variable in the external environment. | ||
129 | |||
130 | - When buildhistory is enabled, its output is now written under the | ||
131 | :term:`Build Directory` rather than | ||
132 | :term:`TMPDIR`. Doing so makes it easier to delete | ||
133 | ``TMPDIR`` and preserve the build history. Additionally, data for | ||
134 | produced SDKs is now split by :term:`IMAGE_NAME`. | ||
135 | |||
136 | - The ``pkgdata`` directory produced as part of the packaging process | ||
137 | has been collapsed into a single machine-specific directory. This | ||
138 | directory is located under ``sysroots`` and uses a machine-specific | ||
139 | name (i.e. ``tmp/sysroots/machine/pkgdata``). | ||
140 | |||
141 | .. _migration-1.5-shortened-git-srcrev-values: | ||
142 | |||
143 | Shortened Git ``SRCREV`` Values | ||
144 | ------------------------------- | ||
145 | |||
146 | BitBake will now shorten revisions from Git repositories from the normal | ||
147 | 40 characters down to 10 characters within :term:`SRCPV` | ||
148 | for improved usability in path and file names. This change should be | ||
149 | safe within contexts where these revisions are used because the chances | ||
150 | of spatially close collisions is very low. Distant collisions are not a | ||
151 | major issue in the way the values are used. | ||
152 | |||
153 | .. _migration-1.5-image-features: | ||
154 | |||
155 | ``IMAGE_FEATURES`` | ||
156 | ------------------ | ||
157 | |||
158 | The following changes have been made that relate to | ||
159 | :term:`IMAGE_FEATURES`: | ||
160 | |||
161 | - The value of ``IMAGE_FEATURES`` is now validated to ensure invalid | ||
162 | feature items are not added. Some users mistakenly add package names | ||
163 | to this variable instead of using | ||
164 | :term:`IMAGE_INSTALL` in order to have the | ||
165 | package added to the image, which does not work. This change is | ||
166 | intended to catch those kinds of situations. Valid ``IMAGE_FEATURES`` | ||
167 | are drawn from ``PACKAGE_GROUP`` definitions, | ||
168 | :term:`COMPLEMENTARY_GLOB` and a new | ||
169 | "validitems" varflag on ``IMAGE_FEATURES``. The "validitems" varflag | ||
170 | change allows additional features to be added if they are not | ||
171 | provided using the previous two mechanisms. | ||
172 | |||
173 | - The previously deprecated "apps-console-core" ``IMAGE_FEATURES`` item | ||
174 | is no longer supported. Add "splash" to ``IMAGE_FEATURES`` if you | ||
175 | wish to have the splash screen enabled, since this is all that | ||
176 | apps-console-core was doing. | ||
177 | |||
178 | .. _migration-1.5-run: | ||
179 | |||
180 | ``/run`` | ||
181 | -------- | ||
182 | |||
183 | The ``/run`` directory from the Filesystem Hierarchy Standard 3.0 has | ||
184 | been introduced. You can find some of the implications for this change | ||
185 | `here <http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873>`__. | ||
186 | The change also means that recipes that install files to ``/var/run`` | ||
187 | must be changed. You can find a guide on how to make these changes | ||
188 | `here <https://www.mail-archive.com/openembedded-devel@lists.openembedded.org/msg31649.html>`__. | ||
189 | |||
190 | .. _migration-1.5-removal-of-package-manager-database-within-image-recipes: | ||
191 | |||
192 | Removal of Package Manager Database Within Image Recipes | ||
193 | -------------------------------------------------------- | ||
194 | |||
195 | The image ``core-image-minimal`` no longer adds | ||
196 | ``remove_packaging_data_files`` to | ||
197 | :term:`ROOTFS_POSTPROCESS_COMMAND`. | ||
198 | This addition is now handled automatically when "package-management" is | ||
199 | not in :term:`IMAGE_FEATURES`. If you have custom | ||
200 | image recipes that make this addition, you should remove the lines, as | ||
201 | they are not needed and might interfere with correct operation of | ||
202 | postinstall scripts. | ||
203 | |||
204 | .. _migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time: | ||
205 | |||
206 | Images Now Rebuild Only on Changes Instead of Every Time | ||
207 | -------------------------------------------------------- | ||
208 | |||
209 | The :ref:`ref-tasks-rootfs` and other related image | ||
210 | construction tasks are no longer marked as "nostamp". Consequently, they | ||
211 | will only be re-executed when their inputs have changed. Previous | ||
212 | versions of the OpenEmbedded build system always rebuilt the image when | ||
213 | requested rather when necessary. | ||
214 | |||
215 | .. _migration-1.5-task-recipes: | ||
216 | |||
217 | Task Recipes | ||
218 | ------------ | ||
219 | |||
220 | The previously deprecated ``task.bbclass`` has now been dropped. For | ||
221 | recipes that previously inherited from this class, you should rename | ||
222 | them from ``task-*`` to ``packagegroup-*`` and inherit packagegroup | ||
223 | instead. | ||
224 | |||
225 | For more information, see the | ||
226 | ":ref:`packagegroup.bbclass <ref-classes-packagegroup>`" section. | ||
227 | |||
228 | .. _migration-1.5-busybox: | ||
229 | |||
230 | BusyBox | ||
231 | ------- | ||
232 | |||
233 | By default, we now split BusyBox into two binaries: one that is suid | ||
234 | root for those components that need it, and another for the rest of the | ||
235 | components. Splitting BusyBox allows for optimization that eliminates | ||
236 | the ``tinylogin`` recipe as recommended by upstream. You can disable | ||
237 | this split by setting | ||
238 | :term:`BUSYBOX_SPLIT_SUID` to "0". | ||
239 | |||
240 | .. _migration-1.5-automated-image-testing: | ||
241 | |||
242 | Automated Image Testing | ||
243 | ----------------------- | ||
244 | |||
245 | A new automated image testing framework has been added through the | ||
246 | :ref:`testimage.bbclass <ref-classes-testimage*>` class. This | ||
247 | framework replaces the older ``imagetest-qemu`` framework. | ||
248 | |||
249 | You can learn more about performing automated image tests in the | ||
250 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
251 | section in the Yocto Project Development Tasks Manual. | ||
252 | |||
253 | .. _migration-1.5-build-history: | ||
254 | |||
255 | Build History | ||
256 | ------------- | ||
257 | |||
258 | Following are changes to Build History: | ||
259 | |||
260 | - Installed package sizes: ``installed-package-sizes.txt`` for an image | ||
261 | now records the size of the files installed by each package instead | ||
262 | of the size of each compressed package archive file. | ||
263 | |||
264 | - The dependency graphs (``depends*.dot``) now use the actual package | ||
265 | names instead of replacing dashes, dots and plus signs with | ||
266 | underscores. | ||
267 | |||
268 | - The ``buildhistory-diff`` and ``buildhistory-collect-srcrevs`` | ||
269 | utilities have improved command-line handling. Use the ``--help`` | ||
270 | option for each utility for more information on the new syntax. | ||
271 | |||
272 | For more information on Build History, see the | ||
273 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
274 | section in the Yocto Project Development Tasks Manual. | ||
275 | |||
276 | .. _migration-1.5-udev: | ||
277 | |||
278 | ``udev`` | ||
279 | -------- | ||
280 | |||
281 | Following are changes to ``udev``: | ||
282 | |||
283 | - ``udev`` no longer brings in ``udev-extraconf`` automatically through | ||
284 | :term:`RRECOMMENDS`, since this was originally | ||
285 | intended to be optional. If you need the extra rules, then add | ||
286 | ``udev-extraconf`` to your image. | ||
287 | |||
288 | - ``udev`` no longer brings in ``pciutils-ids`` or ``usbutils-ids`` | ||
289 | through ``RRECOMMENDS``. These are not needed by ``udev`` itself and | ||
290 | removing them saves around 350KB. | ||
291 | |||
292 | .. _migration-1.5-removed-renamed-recipes: | ||
293 | |||
294 | Removed and Renamed Recipes | ||
295 | --------------------------- | ||
296 | |||
297 | - The ``linux-yocto`` 3.2 kernel has been removed. | ||
298 | |||
299 | - ``libtool-nativesdk`` has been renamed to ``nativesdk-libtool``. | ||
300 | |||
301 | - ``tinylogin`` has been removed. It has been replaced by a suid | ||
302 | portion of Busybox. See the "`BusyBox <#migration-1.5-busybox>`__" | ||
303 | section for more information. | ||
304 | |||
305 | - ``external-python-tarball`` has been renamed to | ||
306 | ``buildtools-tarball``. | ||
307 | |||
308 | - ``web-webkit`` has been removed. It has been functionally replaced by | ||
309 | ``midori``. | ||
310 | |||
311 | - ``imake`` has been removed. It is no longer needed by any other | ||
312 | recipe. | ||
313 | |||
314 | - ``transfig-native`` has been removed. It is no longer needed by any | ||
315 | other recipe. | ||
316 | |||
317 | - ``anjuta-remote-run`` has been removed. Anjuta IDE integration has | ||
318 | not been officially supported for several releases. | ||
319 | |||
320 | .. _migration-1.5-other-changes: | ||
321 | |||
322 | Other Changes | ||
323 | ------------- | ||
324 | |||
325 | Following is a list of short entries describing other changes: | ||
326 | |||
327 | - ``run-postinsts``: Make this generic. | ||
328 | |||
329 | - ``base-files``: Remove the unnecessary ``media/``\ xxx directories. | ||
330 | |||
331 | - ``alsa-state``: Provide an empty ``asound.conf`` by default. | ||
332 | |||
333 | - ``classes/image``: Ensure | ||
334 | :term:`BAD_RECOMMENDATIONS` supports | ||
335 | pre-renamed package names. | ||
336 | |||
337 | - ``classes/rootfs_rpm``: Implement ``BAD_RECOMMENDATIONS`` for RPM. | ||
338 | |||
339 | - ``systemd``: Remove ``systemd_unitdir`` if ``systemd`` is not in | ||
340 | :term:`DISTRO_FEATURES`. | ||
341 | |||
342 | - ``systemd``: Remove ``init.d`` dir if ``systemd`` unit file is | ||
343 | present and ``sysvinit`` is not a distro feature. | ||
344 | |||
345 | - ``libpam``: Deny all services for the ``OTHER`` entries. | ||
346 | |||
347 | - ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict | ||
348 | with ``multilib``. See | ||
349 | `YOCTO #4993 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993>`_ | ||
350 | in Bugzilla for more information. | ||
351 | |||
352 | - ``linux-dtb``: Use kernel build system to generate the ``dtb`` files. | ||
353 | |||
354 | - ``kern-tools``: Switch from guilt to new ``kgit-s2q`` tool. | ||
355 | |||
diff --git a/documentation/ref-manual/migration-1.6.rst b/documentation/ref-manual/migration-1.6.rst new file mode 100644 index 0000000000..b55be46e55 --- /dev/null +++ b/documentation/ref-manual/migration-1.6.rst | |||
@@ -0,0 +1,417 @@ | |||
1 | Moving to the Yocto Project 1.6 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.6 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.6-archiver-class: | ||
8 | |||
9 | ``archiver`` Class | ||
10 | ------------------ | ||
11 | |||
12 | The :ref:`archiver <ref-classes-archiver>` class has been rewritten | ||
13 | and its configuration has been simplified. For more details on the | ||
14 | source archiver, see the | ||
15 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
16 | section in the Yocto Project Development Tasks Manual. | ||
17 | |||
18 | .. _migration-1.6-packaging-changes: | ||
19 | |||
20 | Packaging Changes | ||
21 | ----------------- | ||
22 | |||
23 | The following packaging changes have been made: | ||
24 | |||
25 | - The ``binutils`` recipe no longer produces a ``binutils-symlinks`` | ||
26 | package. ``update-alternatives`` is now used to handle the preferred | ||
27 | ``binutils`` variant on the target instead. | ||
28 | |||
29 | - The tc (traffic control) utilities have been split out of the main | ||
30 | ``iproute2`` package and put into the ``iproute2-tc`` package. | ||
31 | |||
32 | - The ``gtk-engines`` schemas have been moved to a dedicated | ||
33 | ``gtk-engines-schemas`` package. | ||
34 | |||
35 | - The ``armv7a`` with thumb package architecture suffix has changed. | ||
36 | The suffix for these packages with the thumb optimization enabled is | ||
37 | "t2" as it should be. Use of this suffix was not the case in the 1.5 | ||
38 | release. Architecture names will change within package feeds as a | ||
39 | result. | ||
40 | |||
41 | .. _migration-1.6-bitbake: | ||
42 | |||
43 | BitBake | ||
44 | ------- | ||
45 | |||
46 | The following changes have been made to :term:`BitBake`. | ||
47 | |||
48 | .. _migration-1.6-matching-branch-requirement-for-git-fetching: | ||
49 | |||
50 | Matching Branch Requirement for Git Fetching | ||
51 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
52 | |||
53 | When fetching source from a Git repository using | ||
54 | :term:`SRC_URI`, BitBake will now validate the | ||
55 | :term:`SRCREV` value against the branch. You can specify | ||
56 | the branch using the following form: SRC_URI = | ||
57 | "git://server.name/repository;branch=branchname" If you do not specify a | ||
58 | branch, BitBake looks in the default "master" branch. | ||
59 | |||
60 | Alternatively, if you need to bypass this check (e.g. if you are | ||
61 | fetching a revision corresponding to a tag that is not on any branch), | ||
62 | you can add ";nobranch=1" to the end of the URL within ``SRC_URI``. | ||
63 | |||
64 | .. _migration-1.6-bitbake-deps: | ||
65 | |||
66 | Python Definition substitutions | ||
67 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
68 | |||
69 | BitBake had some previously deprecated Python definitions within its | ||
70 | ``bb`` module removed. You should use their sub-module counterparts | ||
71 | instead: | ||
72 | |||
73 | - ``bb.MalformedUrl``: Use ``bb.fetch.MalformedUrl``. | ||
74 | |||
75 | - ``bb.encodeurl``: Use ``bb.fetch.encodeurl``. | ||
76 | |||
77 | - ``bb.decodeurl``: Use ``bb.fetch.decodeurl`` | ||
78 | |||
79 | - ``bb.mkdirhier``: Use ``bb.utils.mkdirhier``. | ||
80 | |||
81 | - ``bb.movefile``: Use ``bb.utils.movefile``. | ||
82 | |||
83 | - ``bb.copyfile``: Use ``bb.utils.copyfile``. | ||
84 | |||
85 | - ``bb.which``: Use ``bb.utils.which``. | ||
86 | |||
87 | - ``bb.vercmp_string``: Use ``bb.utils.vercmp_string``. | ||
88 | |||
89 | - ``bb.vercmp``: Use ``bb.utils.vercmp``. | ||
90 | |||
91 | .. _migration-1.6-bitbake-fetcher: | ||
92 | |||
93 | SVK Fetcher | ||
94 | ~~~~~~~~~~~ | ||
95 | |||
96 | The SVK fetcher has been removed from BitBake. | ||
97 | |||
98 | .. _migration-1.6-bitbake-console-output: | ||
99 | |||
100 | Console Output Error Redirection | ||
101 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
102 | |||
103 | The BitBake console UI will now output errors to ``stderr`` instead of | ||
104 | ``stdout``. Consequently, if you are piping or redirecting the output of | ||
105 | ``bitbake`` to somewhere else, and you wish to retain the errors, you | ||
106 | will need to add ``2>&1`` (or something similar) to the end of your | ||
107 | ``bitbake`` command line. | ||
108 | |||
109 | .. _migration-1.6-task-taskname-overrides: | ||
110 | |||
111 | ``task-``\ taskname Overrides | ||
112 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
113 | |||
114 | ``task-``\ taskname overrides have been adjusted so that tasks whose | ||
115 | names contain underscores have the underscores replaced by hyphens for | ||
116 | the override so that they now function properly. For example, the task | ||
117 | override for :ref:`ref-tasks-populate_sdk` is | ||
118 | ``task-populate-sdk``. | ||
119 | |||
120 | .. _migration-1.6-variable-changes: | ||
121 | |||
122 | Changes to Variables | ||
123 | -------------------- | ||
124 | |||
125 | The following variables have changed. For information on the | ||
126 | OpenEmbedded build system variables, see the "`Variables | ||
127 | Glossary <#ref-variables-glos>`__" Chapter. | ||
128 | |||
129 | .. _migration-1.6-variable-changes-TMPDIR: | ||
130 | |||
131 | ``TMPDIR`` | ||
132 | ~~~~~~~~~~ | ||
133 | |||
134 | :term:`TMPDIR` can no longer be on an NFS mount. NFS does | ||
135 | not offer full POSIX locking and inode consistency and can cause | ||
136 | unexpected issues if used to store ``TMPDIR``. | ||
137 | |||
138 | The check for this occurs on startup. If ``TMPDIR`` is detected on an | ||
139 | NFS mount, an error occurs. | ||
140 | |||
141 | .. _migration-1.6-variable-changes-PRINC: | ||
142 | |||
143 | ``PRINC`` | ||
144 | ~~~~~~~~~ | ||
145 | |||
146 | The ``PRINC`` variable has been deprecated and triggers a warning if | ||
147 | detected during a build. For :term:`PR` increments on changes, | ||
148 | use the PR service instead. You can find out more about this service in | ||
149 | the ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`" | ||
150 | section in the Yocto Project Development Tasks Manual. | ||
151 | |||
152 | .. _migration-1.6-variable-changes-IMAGE_TYPES: | ||
153 | |||
154 | ``IMAGE_TYPES`` | ||
155 | ~~~~~~~~~~~~~~~ | ||
156 | |||
157 | The "sum.jffs2" option for :term:`IMAGE_TYPES` has | ||
158 | been replaced by the "jffs2.sum" option, which fits the processing | ||
159 | order. | ||
160 | |||
161 | .. _migration-1.6-variable-changes-COPY_LIC_MANIFEST: | ||
162 | |||
163 | ``COPY_LIC_MANIFEST`` | ||
164 | ~~~~~~~~~~~~~~~~~~~~~ | ||
165 | |||
166 | The :term:`COPY_LIC_MANIFEST` variable must now | ||
167 | be set to "1" rather than any value in order to enable it. | ||
168 | |||
169 | .. _migration-1.6-variable-changes-COPY_LIC_DIRS: | ||
170 | |||
171 | ``COPY_LIC_DIRS`` | ||
172 | ~~~~~~~~~~~~~~~~~ | ||
173 | |||
174 | The :term:`COPY_LIC_DIRS` variable must now be set | ||
175 | to "1" rather than any value in order to enable it. | ||
176 | |||
177 | .. _migration-1.6-variable-changes-PACKAGE_GROUP: | ||
178 | |||
179 | ``PACKAGE_GROUP`` | ||
180 | ~~~~~~~~~~~~~~~~~ | ||
181 | |||
182 | The ``PACKAGE_GROUP`` variable has been renamed to | ||
183 | :term:`FEATURE_PACKAGES` to more accurately | ||
184 | reflect its purpose. You can still use ``PACKAGE_GROUP`` but the | ||
185 | OpenEmbedded build system produces a warning message when it encounters | ||
186 | the variable. | ||
187 | |||
188 | .. _migration-1.6-variable-changes-variable-entry-behavior: | ||
189 | |||
190 | Preprocess and Post Process Command Variable Behavior | ||
191 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
192 | |||
193 | The following variables now expect a semicolon separated list of | ||
194 | functions to call and not arbitrary shell commands: | ||
195 | |||
196 | - :term:`ROOTFS_PREPROCESS_COMMAND` | ||
197 | - :term:`ROOTFS_POSTPROCESS_COMMAND` | ||
198 | - :term:`SDK_POSTPROCESS_COMMAND` | ||
199 | - :term:`POPULATE_SDK_POST_TARGET_COMMAND` | ||
200 | - :term:`POPULATE_SDK_POST_HOST_COMMAND` | ||
201 | - :term:`IMAGE_POSTPROCESS_COMMAND` | ||
202 | - :term:`IMAGE_PREPROCESS_COMMAND` | ||
203 | - :term:`ROOTFS_POSTUNINSTALL_COMMAND` | ||
204 | - :term:`ROOTFS_POSTINSTALL_COMMAND` | ||
205 | |||
206 | For | ||
207 | migration purposes, you can simply wrap shell commands in a shell | ||
208 | function and then call the function. Here is an example: :: | ||
209 | |||
210 | my_postprocess_function() { | ||
211 | echo "hello" > ${IMAGE_ROOTFS}/hello.txt | ||
212 | } | ||
213 | ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; " | ||
214 | |||
215 | .. _migration-1.6-package-test-ptest: | ||
216 | |||
217 | Package Test (ptest) | ||
218 | -------------------- | ||
219 | |||
220 | Package Tests (ptest) are built but not installed by default. For | ||
221 | information on using Package Tests, see the | ||
222 | ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" | ||
223 | section in the Yocto Project Development Tasks Manual. For information on the | ||
224 | ``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`" | ||
225 | section. | ||
226 | |||
227 | .. _migration-1.6-build-changes: | ||
228 | |||
229 | Build Changes | ||
230 | ------------- | ||
231 | |||
232 | Separate build and source directories have been enabled by default for | ||
233 | selected recipes where it is known to work (a whitelist) and for all | ||
234 | recipes that inherit the :ref:`cmake <ref-classes-cmake>` class. In | ||
235 | future releases the :ref:`autotools <ref-classes-autotools>` class | ||
236 | will enable a separate build directory by default as well. Recipes | ||
237 | building Autotools-based software that fails to build with a separate | ||
238 | build directory should be changed to inherit from the | ||
239 | :ref:`autotools-brokensep <ref-classes-autotools>` class instead of | ||
240 | the ``autotools`` or ``autotools_stage``\ classes. | ||
241 | |||
242 | .. _migration-1.6-building-qemu-native: | ||
243 | |||
244 | ``qemu-native`` | ||
245 | --------------- | ||
246 | |||
247 | ``qemu-native`` now builds without SDL-based graphical output support by | ||
248 | default. The following additional lines are needed in your | ||
249 | ``local.conf`` to enable it: | ||
250 | :: | ||
251 | |||
252 | PACKAGECONFIG_pn-qemu-native = "sdl" | ||
253 | ASSUME_PROVIDED += "libsdl-native" | ||
254 | |||
255 | .. note:: | ||
256 | |||
257 | The default | ||
258 | local.conf | ||
259 | contains these statements. Consequently, if you are building a | ||
260 | headless system and using a default | ||
261 | local.conf | ||
262 | file, you will need comment these two lines out. | ||
263 | |||
264 | .. _migration-1.6-core-image-basic: | ||
265 | |||
266 | ``core-image-basic`` | ||
267 | -------------------- | ||
268 | |||
269 | ``core-image-basic`` has been renamed to ``core-image-full-cmdline``. | ||
270 | |||
271 | In addition to ``core-image-basic`` being renamed, | ||
272 | ``packagegroup-core-basic`` has been renamed to | ||
273 | ``packagegroup-core-full-cmdline`` to match. | ||
274 | |||
275 | .. _migration-1.6-licensing: | ||
276 | |||
277 | Licensing | ||
278 | --------- | ||
279 | |||
280 | The top-level ``LICENSE`` file has been changed to better describe the | ||
281 | license of the various components of :term:`OpenEmbedded-Core (OE-Core)`. However, | ||
282 | the licensing itself remains unchanged. | ||
283 | |||
284 | Normally, this change would not cause any side-effects. However, some | ||
285 | recipes point to this file within | ||
286 | :term:`LIC_FILES_CHKSUM` (as | ||
287 | ``${COREBASE}/LICENSE``) and thus the accompanying checksum must be | ||
288 | changed from 3f40d7994397109285ec7b81fdeb3b58 to | ||
289 | 4d92cd373abda3937c2bc47fbc49d690. A better alternative is to have | ||
290 | ``LIC_FILES_CHKSUM`` point to a file describing the license that is | ||
291 | distributed with the source that the recipe is building, if possible, | ||
292 | rather than pointing to ``${COREBASE}/LICENSE``. | ||
293 | |||
294 | .. _migration-1.6-cflags-options: | ||
295 | |||
296 | ``CFLAGS`` Options | ||
297 | ------------------ | ||
298 | |||
299 | The "-fpermissive" option has been removed from the default | ||
300 | :term:`CFLAGS` value. You need to take action on | ||
301 | individual recipes that fail when building with this option. You need to | ||
302 | either patch the recipes to fix the issues reported by the compiler, or | ||
303 | you need to add "-fpermissive" to ``CFLAGS`` in the recipes. | ||
304 | |||
305 | .. _migration-1.6-custom-images: | ||
306 | |||
307 | Custom Image Output Types | ||
308 | ------------------------- | ||
309 | |||
310 | Custom image output types, as selected using | ||
311 | :term:`IMAGE_FSTYPES`, must declare their | ||
312 | dependencies on other image types (if any) using a new | ||
313 | :term:`IMAGE_TYPEDEP` variable. | ||
314 | |||
315 | .. _migration-1.6-do-package-write-task: | ||
316 | |||
317 | Tasks | ||
318 | ----- | ||
319 | |||
320 | The ``do_package_write`` task has been removed. The task is no longer | ||
321 | needed. | ||
322 | |||
323 | .. _migration-1.6-update-alternatives-provider: | ||
324 | |||
325 | ``update-alternative`` Provider | ||
326 | ------------------------------- | ||
327 | |||
328 | The default ``update-alternatives`` provider has been changed from | ||
329 | ``opkg`` to ``opkg-utils``. This change resolves some troublesome | ||
330 | circular dependencies. The runtime package has also been renamed from | ||
331 | ``update-alternatives-cworth`` to ``update-alternatives-opkg``. | ||
332 | |||
333 | .. _migration-1.6-virtclass-overrides: | ||
334 | |||
335 | ``virtclass`` Overrides | ||
336 | ----------------------- | ||
337 | |||
338 | The ``virtclass`` overrides are now deprecated. Use the equivalent class | ||
339 | overrides instead (e.g. ``virtclass-native`` becomes ``class-native``.) | ||
340 | |||
341 | .. _migration-1.6-removed-renamed-recipes: | ||
342 | |||
343 | Removed and Renamed Recipes | ||
344 | --------------------------- | ||
345 | |||
346 | The following recipes have been removed: | ||
347 | |||
348 | - ``packagegroup-toolset-native`` - This recipe is largely unused. | ||
349 | |||
350 | - ``linux-yocto-3.8`` - Support for the Linux yocto 3.8 kernel has been | ||
351 | dropped. Support for the 3.10 and 3.14 kernels have been added with | ||
352 | the ``linux-yocto-3.10`` and ``linux-yocto-3.14`` recipes. | ||
353 | |||
354 | - ``ocf-linux`` - This recipe has been functionally replaced using | ||
355 | ``cryptodev-linux``. | ||
356 | |||
357 | - ``genext2fs`` - ``genext2fs`` is no longer used by the build system | ||
358 | and is unmaintained upstream. | ||
359 | |||
360 | - ``js`` - This provided an ancient version of Mozilla's javascript | ||
361 | engine that is no longer needed. | ||
362 | |||
363 | - ``zaurusd`` - The recipe has been moved to the ``meta-handheld`` | ||
364 | layer. | ||
365 | |||
366 | - ``eglibc 2.17`` - Replaced by the ``eglibc 2.19`` recipe. | ||
367 | |||
368 | - ``gcc 4.7.2`` - Replaced by the now stable ``gcc 4.8.2``. | ||
369 | |||
370 | - ``external-sourcery-toolchain`` - this recipe is now maintained in | ||
371 | the ``meta-sourcery`` layer. | ||
372 | |||
373 | - ``linux-libc-headers-yocto 3.4+git`` - Now using version 3.10 of the | ||
374 | ``linux-libc-headers`` by default. | ||
375 | |||
376 | - ``meta-toolchain-gmae`` - This recipe is obsolete. | ||
377 | |||
378 | - ``packagegroup-core-sdk-gmae`` - This recipe is obsolete. | ||
379 | |||
380 | - ``packagegroup-core-standalone-gmae-sdk-target`` - This recipe is | ||
381 | obsolete. | ||
382 | |||
383 | .. _migration-1.6-removed-classes: | ||
384 | |||
385 | Removed Classes | ||
386 | --------------- | ||
387 | |||
388 | The following classes have become obsolete and have been removed: | ||
389 | |||
390 | - ``module_strip`` | ||
391 | |||
392 | - ``pkg_metainfo`` | ||
393 | |||
394 | - ``pkg_distribute`` | ||
395 | |||
396 | - ``image-empty`` | ||
397 | |||
398 | .. _migration-1.6-reference-bsps: | ||
399 | |||
400 | Reference Board Support Packages (BSPs) | ||
401 | --------------------------------------- | ||
402 | |||
403 | The following reference BSPs changes occurred: | ||
404 | |||
405 | - The BeagleBoard (``beagleboard``) ARM reference hardware has been | ||
406 | replaced by the BeagleBone (``beaglebone``) hardware. | ||
407 | |||
408 | - The RouterStation Pro (``routerstationpro``) MIPS reference hardware | ||
409 | has been replaced by the EdgeRouter Lite (``edgerouter``) hardware. | ||
410 | |||
411 | The previous reference BSPs for the ``beagleboard`` and | ||
412 | ``routerstationpro`` machines are still available in a new | ||
413 | ``meta-yocto-bsp-old`` layer in the | ||
414 | :yocto_git:`Source Repositories <>` at | ||
415 | http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/. | ||
416 | |||
417 | |||
diff --git a/documentation/ref-manual/migration-1.7.rst b/documentation/ref-manual/migration-1.7.rst new file mode 100644 index 0000000000..82fd37d3a9 --- /dev/null +++ b/documentation/ref-manual/migration-1.7.rst | |||
@@ -0,0 +1,225 @@ | |||
1 | Moving to the Yocto Project 1.7 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.7 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.7-changes-to-setting-qemu-packageconfig-options: | ||
8 | |||
9 | Changes to Setting QEMU ``PACKAGECONFIG`` Options in ``local.conf`` | ||
10 | ------------------------------------------------------------------- | ||
11 | |||
12 | The QEMU recipe now uses a number of | ||
13 | :term:`PACKAGECONFIG` options to enable various | ||
14 | optional features. The method used to set defaults for these options | ||
15 | means that existing ``local.conf`` files will need to be be modified to | ||
16 | append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu`` | ||
17 | instead of setting it. In other words, to enable graphical output for | ||
18 | QEMU, you should now have these lines in ``local.conf``: | ||
19 | :: | ||
20 | |||
21 | PACKAGECONFIG_append_pn-qemu-native = " sdl" | ||
22 | PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" | ||
23 | |||
24 | .. _migration-1.7-minimum-git-version: | ||
25 | |||
26 | Minimum Git version | ||
27 | ------------------- | ||
28 | |||
29 | The minimum :ref:`overview-manual/overview-manual-development-environment:git` | ||
30 | version required on the | ||
31 | build host is now 1.7.8 because the ``--list`` option is now required by | ||
32 | BitBake's Git fetcher. As always, if your host distribution does not | ||
33 | provide a version of Git that meets this requirement, you can use the | ||
34 | ``buildtools-tarball`` that does. See the "`Required Git, tar, Python | ||
35 | and gcc Versions <#required-git-tar-python-and-gcc-versions>`__" section | ||
36 | for more information. | ||
37 | |||
38 | .. _migration-1.7-autotools-class-changes: | ||
39 | |||
40 | Autotools Class Changes | ||
41 | ----------------------- | ||
42 | |||
43 | The following :ref:`autotools <ref-classes-autotools>` class changes | ||
44 | occurred: | ||
45 | |||
46 | - *A separate build directory is now used by default:* The | ||
47 | ``autotools`` class has been changed to use a directory for building | ||
48 | (:term:`B`), which is separate from the source directory | ||
49 | (:term:`S`). This is commonly referred to as ``B != S``, or | ||
50 | an out-of-tree build. | ||
51 | |||
52 | If the software being built is already capable of building in a | ||
53 | directory separate from the source, you do not need to do anything. | ||
54 | However, if the software is not capable of being built in this | ||
55 | manner, you will need to either patch the software so that it can | ||
56 | build separately, or you will need to change the recipe to inherit | ||
57 | the :ref:`autotools-brokensep <ref-classes-autotools>` class | ||
58 | instead of the ``autotools`` or ``autotools_stage`` classes. | ||
59 | |||
60 | - The ``--foreign`` option is no longer passed to ``automake`` when | ||
61 | running ``autoconf``: This option tells ``automake`` that a | ||
62 | particular software package does not follow the GNU standards and | ||
63 | therefore should not be expected to distribute certain files such as | ||
64 | ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of | ||
65 | upstream software packages already tell ``automake`` to enable | ||
66 | foreign mode themselves, the option is mostly superfluous. However, | ||
67 | some recipes will need patches for this change. You can easily make | ||
68 | the change by patching ``configure.ac`` so that it passes "foreign" | ||
69 | to ``AM_INIT_AUTOMAKE()``. See `this | ||
70 | commit <http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2>`__ | ||
71 | for an example showing how to make the patch. | ||
72 | |||
73 | .. _migration-1.7-binary-configuration-scripts-disabled: | ||
74 | |||
75 | Binary Configuration Scripts Disabled | ||
76 | ------------------------------------- | ||
77 | |||
78 | Some of the core recipes that package binary configuration scripts now | ||
79 | disable the scripts due to the scripts previously requiring error-prone | ||
80 | path substitution. Software that links against these libraries using | ||
81 | these scripts should use the much more robust ``pkg-config`` instead. | ||
82 | The list of recipes changed in this version (and their configuration | ||
83 | scripts) is as follows: | ||
84 | :: | ||
85 | |||
86 | directfb (directfb-config) | ||
87 | freetype (freetype-config) | ||
88 | gpgme (gpgme-config) | ||
89 | libassuan (libassuan-config) | ||
90 | libcroco (croco-6.0-config) | ||
91 | libgcrypt (libgcrypt-config) | ||
92 | libgpg-error (gpg-error-config) | ||
93 | libksba (ksba-config) | ||
94 | libpcap (pcap-config) | ||
95 | libpcre (pcre-config) | ||
96 | libpng (libpng-config, libpng16-config) | ||
97 | libsdl (sdl-config) | ||
98 | libusb-compat (libusb-config) | ||
99 | libxml2 (xml2-config) | ||
100 | libxslt (xslt-config) | ||
101 | ncurses (ncurses-config) | ||
102 | neon (neon-config) | ||
103 | npth (npth-config) | ||
104 | pth (pth-config) | ||
105 | taglib (taglib-config) | ||
106 | |||
107 | Additionally, support for ``pkg-config`` has been added to some recipes in the | ||
108 | previous list in the rare cases where the upstream software package does | ||
109 | not already provide it. | ||
110 | |||
111 | .. _migration-1.7-glibc-replaces-eglibc: | ||
112 | |||
113 | ``eglibc 2.19`` Replaced with ``glibc 2.20`` | ||
114 | -------------------------------------------- | ||
115 | |||
116 | Because ``eglibc`` and ``glibc`` were already fairly close, this | ||
117 | replacement should not require any significant changes to other software | ||
118 | that links to ``eglibc``. However, there were a number of minor changes | ||
119 | in ``glibc 2.20`` upstream that could require patching some software | ||
120 | (e.g. the removal of the ``_BSD_SOURCE`` feature test macro). | ||
121 | |||
122 | ``glibc 2.20`` requires version 2.6.32 or greater of the Linux kernel. | ||
123 | Thus, older kernels will no longer be usable in conjunction with it. | ||
124 | |||
125 | For full details on the changes in ``glibc 2.20``, see the upstream | ||
126 | release notes | ||
127 | `here <https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html>`__. | ||
128 | |||
129 | .. _migration-1.7-kernel-module-autoloading: | ||
130 | |||
131 | Kernel Module Autoloading | ||
132 | ------------------------- | ||
133 | |||
134 | The :term:`module_autoload_* <module_autoload>` variable is now | ||
135 | deprecated and a new | ||
136 | :term:`KERNEL_MODULE_AUTOLOAD` variable | ||
137 | should be used instead. Also, :term:`module_conf_* <module_conf>` | ||
138 | must now be used in conjunction with a new | ||
139 | :term:`KERNEL_MODULE_PROBECONF` variable. | ||
140 | The new variables no longer require you to specify the module name as | ||
141 | part of the variable name. This change not only simplifies usage but | ||
142 | also allows the values of these variables to be appropriately | ||
143 | incorporated into task signatures and thus trigger the appropriate tasks | ||
144 | to re-execute when changed. You should replace any references to | ||
145 | ``module_autoload_*`` with ``KERNEL_MODULE_AUTOLOAD``, and add any | ||
146 | modules for which ``module_conf_*`` is specified to | ||
147 | ``KERNEL_MODULE_PROBECONF``. | ||
148 | |||
149 | .. _migration-1.7-qa-check-changes: | ||
150 | |||
151 | QA Check Changes | ||
152 | ---------------- | ||
153 | |||
154 | The following changes have occurred to the QA check process: | ||
155 | |||
156 | - Additional QA checks ``file-rdeps`` and ``build-deps`` have been | ||
157 | added in order to verify that file dependencies are satisfied (e.g. | ||
158 | package contains a script requiring ``/bin/bash``) and build-time | ||
159 | dependencies are declared, respectively. For more information, please | ||
160 | see the "`QA Error and Warning Messages <#ref-qa-checks>`__" chapter. | ||
161 | |||
162 | - Package QA checks are now performed during a new | ||
163 | :ref:`ref-tasks-package_qa` task rather than being | ||
164 | part of the :ref:`ref-tasks-package` task. This allows | ||
165 | more parallel execution. This change is unlikely to be an issue | ||
166 | except for highly customized recipes that disable packaging tasks | ||
167 | themselves by marking them as ``noexec``. For those packages, you | ||
168 | will need to disable the ``do_package_qa`` task as well. | ||
169 | |||
170 | - Files being overwritten during the | ||
171 | :ref:`ref-tasks-populate_sysroot` task now | ||
172 | trigger an error instead of a warning. Recipes should not be | ||
173 | overwriting files written to the sysroot by other recipes. If you | ||
174 | have these types of recipes, you need to alter them so that they do | ||
175 | not overwrite these files. | ||
176 | |||
177 | You might now receive this error after changes in configuration or | ||
178 | metadata resulting in orphaned files being left in the sysroot. If | ||
179 | you do receive this error, the way to resolve the issue is to delete | ||
180 | your :term:`TMPDIR` or to move it out of the way and | ||
181 | then re-start the build. Anything that has been fully built up to | ||
182 | that point and does not need rebuilding will be restored from the | ||
183 | shared state cache and the rest of the build will be able to proceed | ||
184 | as normal. | ||
185 | |||
186 | .. _migration-1.7-removed-recipes: | ||
187 | |||
188 | Removed Recipes | ||
189 | --------------- | ||
190 | |||
191 | The following recipes have been removed: | ||
192 | |||
193 | - ``x-load``: This recipe has been superseded by U-boot SPL for all | ||
194 | Cortex-based TI SoCs. For legacy boards, the ``meta-ti`` layer, which | ||
195 | contains a maintained recipe, should be used instead. | ||
196 | |||
197 | - ``ubootchart``: This recipe is obsolete. A ``bootchart2`` recipe has | ||
198 | been added to functionally replace it. | ||
199 | |||
200 | - ``linux-yocto 3.4``: Support for the linux-yocto 3.4 kernel has been | ||
201 | dropped. Support for the 3.10 and 3.14 kernels remains, while support | ||
202 | for version 3.17 has been added. | ||
203 | |||
204 | - ``eglibc`` has been removed in favor of ``glibc``. See the | ||
205 | "```eglibc 2.19`` Replaced with | ||
206 | ``glibc 2.20`` <#migration-1.7-glibc-replaces-eglibc>`__" section for | ||
207 | more information. | ||
208 | |||
209 | .. _migration-1.7-miscellaneous-changes: | ||
210 | |||
211 | Miscellaneous Changes | ||
212 | --------------------- | ||
213 | |||
214 | The following miscellaneous change occurred: | ||
215 | |||
216 | - The build history feature now writes ``build-id.txt`` instead of | ||
217 | ``build-id``. Additionally, ``build-id.txt`` now contains the full | ||
218 | build header as printed by BitBake upon starting the build. You | ||
219 | should manually remove old "build-id" files from your existing build | ||
220 | history repositories to avoid confusion. For information on the build | ||
221 | history feature, see the | ||
222 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
223 | section in the Yocto Project Development Tasks Manual. | ||
224 | |||
225 | |||
diff --git a/documentation/ref-manual/migration-1.8.rst b/documentation/ref-manual/migration-1.8.rst new file mode 100644 index 0000000000..d601e6b63b --- /dev/null +++ b/documentation/ref-manual/migration-1.8.rst | |||
@@ -0,0 +1,183 @@ | |||
1 | Moving to the Yocto Project 1.8 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 1.8 Release from the prior release. | ||
6 | |||
7 | .. _migration-1.8-removed-recipes: | ||
8 | |||
9 | Removed Recipes | ||
10 | --------------- | ||
11 | |||
12 | The following recipes have been removed: | ||
13 | |||
14 | - ``owl-video``: Functionality replaced by ``gst-player``. | ||
15 | |||
16 | - ``gaku``: Functionality replaced by ``gst-player``. | ||
17 | |||
18 | - ``gnome-desktop``: This recipe is now available in ``meta-gnome`` and | ||
19 | is no longer needed. | ||
20 | |||
21 | - ``gsettings-desktop-schemas``: This recipe is now available in | ||
22 | ``meta-gnome`` and is no longer needed. | ||
23 | |||
24 | - ``python-argparse``: The ``argparse`` module is already provided in | ||
25 | the default Python distribution in a package named | ||
26 | ``python-argparse``. Consequently, the separate ``python-argparse`` | ||
27 | recipe is no longer needed. | ||
28 | |||
29 | - ``telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control``: | ||
30 | All these recipes have moved to ``meta-oe`` and are consequently no | ||
31 | longer needed by any recipes in OpenEmbedded-Core. | ||
32 | |||
33 | - ``linux-yocto_3.10`` and ``linux-yocto_3.17``: Support for the | ||
34 | linux-yocto 3.10 and 3.17 kernels has been dropped. Support for the | ||
35 | 3.14 kernel remains, while support for 3.19 kernel has been added. | ||
36 | |||
37 | - ``poky-feed-config-opkg``: This recipe has become obsolete and is no | ||
38 | longer needed. Use ``distro-feed-config`` from ``meta-oe`` instead. | ||
39 | |||
40 | - ``libav 0.8.x``: ``libav 9.x`` is now used. | ||
41 | |||
42 | - ``sed-native``: No longer needed. A working version of ``sed`` is | ||
43 | expected to be provided by the host distribution. | ||
44 | |||
45 | .. _migration-1.8-bluez: | ||
46 | |||
47 | BlueZ 4.x / 5.x Selection | ||
48 | ------------------------- | ||
49 | |||
50 | Proper built-in support for selecting BlueZ 5.x in preference to the | ||
51 | default of 4.x now exists. To use BlueZ 5.x, simply add "bluez5" to your | ||
52 | :term:`DISTRO_FEATURES` value. If you had | ||
53 | previously added append files (``*.bbappend``) to make this selection, | ||
54 | you can now remove them. | ||
55 | |||
56 | Additionally, a ``bluetooth`` class has been added to make selection of | ||
57 | the appropriate bluetooth support within a recipe a little easier. If | ||
58 | you wish to make use of this class in a recipe, add something such as | ||
59 | the following: :: | ||
60 | |||
61 | inherit bluetooth | ||
62 | PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}" | ||
63 | PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4" | ||
64 | PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5" | ||
65 | |||
66 | .. _migration-1.8-kernel-build-changes: | ||
67 | |||
68 | Kernel Build Changes | ||
69 | -------------------- | ||
70 | |||
71 | The kernel build process was changed to place the source in a common | ||
72 | shared work area and to place build artifacts separately in the source | ||
73 | code tree. In theory, migration paths have been provided for most common | ||
74 | usages in kernel recipes but this might not work in all cases. In | ||
75 | particular, users need to ensure that ``${S}`` (source files) and | ||
76 | ``${B}`` (build artifacts) are used correctly in functions such as | ||
77 | :ref:`ref-tasks-configure` and | ||
78 | :ref:`ref-tasks-install`. For kernel recipes that do not | ||
79 | inherit from ``kernel-yocto`` or include ``linux-yocto.inc``, you might | ||
80 | wish to refer to the ``linux.inc`` file in the ``meta-oe`` layer for the | ||
81 | kinds of changes you need to make. For reference, here is the | ||
82 | `commit <http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee>`__ | ||
83 | where the ``linux.inc`` file in ``meta-oe`` was updated. | ||
84 | |||
85 | Recipes that rely on the kernel source code and do not inherit the | ||
86 | module classes might need to add explicit dependencies on the | ||
87 | ``do_shared_workdir`` kernel task, for example: :: | ||
88 | |||
89 | do_configure[depends] += "virtual/kernel:do_shared_workdir" | ||
90 | |||
91 | .. _migration-1.8-ssl: | ||
92 | |||
93 | SSL 3.0 is Now Disabled in OpenSSL | ||
94 | ---------------------------------- | ||
95 | |||
96 | SSL 3.0 is now disabled when building OpenSSL. Disabling SSL 3.0 avoids | ||
97 | any lingering instances of the POODLE vulnerability. If you feel you | ||
98 | must re-enable SSL 3.0, then you can add an append file (``*.bbappend``) | ||
99 | for the ``openssl`` recipe to remove "-no-ssl3" from | ||
100 | :term:`EXTRA_OECONF`. | ||
101 | |||
102 | .. _migration-1.8-default-sysroot-poisoning: | ||
103 | |||
104 | Default Sysroot Poisoning | ||
105 | ------------------------- | ||
106 | |||
107 | ``gcc's`` default sysroot and include directories are now "poisoned". In | ||
108 | other words, the sysroot and include directories are being redirected to | ||
109 | a non-existent location in order to catch when host directories are | ||
110 | being used due to the correct options not being passed. This poisoning | ||
111 | applies both to the cross-compiler used within the build and to the | ||
112 | cross-compiler produced in the SDK. | ||
113 | |||
114 | If this change causes something in the build to fail, it almost | ||
115 | certainly means the various compiler flags and commands are not being | ||
116 | passed correctly to the underlying piece of software. In such cases, you | ||
117 | need to take corrective steps. | ||
118 | |||
119 | .. _migration-1.8-rebuild-improvements: | ||
120 | |||
121 | Rebuild Improvements | ||
122 | -------------------- | ||
123 | |||
124 | Changes have been made to the :ref:`base <ref-classes-base>`, | ||
125 | :ref:`autotools <ref-classes-autotools>`, and | ||
126 | :ref:`cmake <ref-classes-cmake>` classes to clean out generated files | ||
127 | when the :ref:`ref-tasks-configure` task needs to be | ||
128 | re-executed. | ||
129 | |||
130 | One of the improvements is to attempt to run "make clean" during the | ||
131 | ``do_configure`` task if a ``Makefile`` exists. Some software packages | ||
132 | do not provide a working clean target within their make files. If you | ||
133 | have such recipes, you need to set | ||
134 | :term:`CLEANBROKEN` to "1" within the recipe, for example: :: | ||
135 | |||
136 | CLEANBROKEN = "1" | ||
137 | |||
138 | .. _migration-1.8-qa-check-and-validation-changes: | ||
139 | |||
140 | QA Check and Validation Changes | ||
141 | ------------------------------- | ||
142 | |||
143 | The following QA Check and Validation Changes have occurred: | ||
144 | |||
145 | - Usage of ``PRINC`` previously triggered a warning. It now triggers an | ||
146 | error. You should remove any remaining usage of ``PRINC`` in any | ||
147 | recipe or append file. | ||
148 | |||
149 | - An additional QA check has been added to detect usage of ``${D}`` in | ||
150 | :term:`FILES` values where :term:`D` values | ||
151 | should not be used at all. The same check ensures that ``$D`` is used | ||
152 | in ``pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm`` functions | ||
153 | instead of ``${D}``. | ||
154 | |||
155 | - :term:`S` now needs to be set to a valid value within a | ||
156 | recipe. If ``S`` is not set in the recipe, the directory is not | ||
157 | automatically created. If ``S`` does not point to a directory that | ||
158 | exists at the time the :ref:`ref-tasks-unpack` task | ||
159 | finishes, a warning will be shown. | ||
160 | |||
161 | - :term:`LICENSE` is now validated for correct | ||
162 | formatting of multiple licenses. If the format is invalid (e.g. | ||
163 | multiple licenses are specified with no operators to specify how the | ||
164 | multiple licenses interact), then a warning will be shown. | ||
165 | |||
166 | .. _migration-1.8-miscellaneous-changes: | ||
167 | |||
168 | Miscellaneous Changes | ||
169 | --------------------- | ||
170 | |||
171 | The following miscellaneous changes have occurred: | ||
172 | |||
173 | - The ``send-error-report`` script now expects a "-s" option to be | ||
174 | specified before the server address. This assumes a server address is | ||
175 | being specified. | ||
176 | |||
177 | - The ``oe-pkgdata-util`` script now expects a "-p" option to be | ||
178 | specified before the ``pkgdata`` directory, which is now optional. If | ||
179 | the ``pkgdata`` directory is not specified, the script will run | ||
180 | BitBake to query :term:`PKGDATA_DIR` from the | ||
181 | build environment. | ||
182 | |||
183 | |||
diff --git a/documentation/ref-manual/migration-2.0.rst b/documentation/ref-manual/migration-2.0.rst new file mode 100644 index 0000000000..570486ba00 --- /dev/null +++ b/documentation/ref-manual/migration-2.0.rst | |||
@@ -0,0 +1,281 @@ | |||
1 | Moving to the Yocto Project 2.0 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.0 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.0-gcc-5: | ||
8 | |||
9 | GCC 5 | ||
10 | ----- | ||
11 | |||
12 | The default compiler is now GCC 5.2. This change has required fixes for | ||
13 | compilation errors in a number of other recipes. | ||
14 | |||
15 | One important example is a fix for when the Linux kernel freezes at boot | ||
16 | time on ARM when built with GCC 5. If you are using your own kernel | ||
17 | recipe or source tree and building for ARM, you will likely need to | ||
18 | apply this | ||
19 | `patch <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2>`__. | ||
20 | The standard ``linux-yocto`` kernel source tree already has a workaround | ||
21 | for the same issue. | ||
22 | |||
23 | For further details, see https://gcc.gnu.org/gcc-5/changes.html | ||
24 | and the porting guide at | ||
25 | https://gcc.gnu.org/gcc-5/porting_to.html. | ||
26 | |||
27 | Alternatively, you can switch back to GCC 4.9 or 4.8 by setting | ||
28 | ``GCCVERSION`` in your configuration, as follows: | ||
29 | :: | ||
30 | |||
31 | GCCVERSION = "4.9%" | ||
32 | |||
33 | .. _migration-2.0-Gstreamer-0.10-removed: | ||
34 | |||
35 | Gstreamer 0.10 Removed | ||
36 | ---------------------- | ||
37 | |||
38 | Gstreamer 0.10 has been removed in favor of Gstreamer 1.x. As part of | ||
39 | the change, recipes for Gstreamer 0.10 and related software are now | ||
40 | located in ``meta-multimedia``. This change results in Qt4 having Phonon | ||
41 | and Gstreamer support in QtWebkit disabled by default. | ||
42 | |||
43 | .. _migration-2.0-removed-recipes: | ||
44 | |||
45 | Removed Recipes | ||
46 | --------------- | ||
47 | |||
48 | The following recipes have been moved or removed: | ||
49 | |||
50 | - ``bluez4``: The recipe is obsolete and has been moved due to | ||
51 | ``bluez5`` becoming fully integrated. The ``bluez4`` recipe now | ||
52 | resides in ``meta-oe``. | ||
53 | |||
54 | - ``gamin``: The recipe is obsolete and has been removed. | ||
55 | |||
56 | - ``gnome-icon-theme``: The recipe's functionally has been replaced by | ||
57 | ``adwaita-icon-theme``. | ||
58 | |||
59 | - Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have been removed | ||
60 | in favor of the recipes for Gstreamer 1.x. | ||
61 | |||
62 | - ``insserv``: The recipe is obsolete and has been removed. | ||
63 | |||
64 | - ``libunique``: The recipe is no longer used and has been moved to | ||
65 | ``meta-oe``. | ||
66 | |||
67 | - ``midori``: The recipe's functionally has been replaced by | ||
68 | ``epiphany``. | ||
69 | |||
70 | - ``python-gst``: The recipe is obsolete and has been removed since it | ||
71 | only contains bindings for Gstreamer 0.10. | ||
72 | |||
73 | - ``qt-mobility``: The recipe is obsolete and has been removed since it | ||
74 | requires ``Gstreamer 0.10``, which has been replaced. | ||
75 | |||
76 | - ``subversion``: All 1.6.x versions of this recipe have been removed. | ||
77 | |||
78 | - ``webkit-gtk``: The older 1.8.3 version of this recipe has been | ||
79 | removed in favor of ``webkitgtk``. | ||
80 | |||
81 | .. _migration-2.0-bitbake-datastore-improvements: | ||
82 | |||
83 | BitBake datastore improvements | ||
84 | ------------------------------ | ||
85 | |||
86 | The method by which BitBake's datastore handles overrides has changed. | ||
87 | Overrides are now applied dynamically and ``bb.data.update_data()`` is | ||
88 | now a no-op. Thus, ``bb.data.update_data()`` is no longer required in | ||
89 | order to apply the correct overrides. In practice, this change is | ||
90 | unlikely to require any changes to Metadata. However, these minor | ||
91 | changes in behavior exist: | ||
92 | |||
93 | - All potential overrides are now visible in the variable history as | ||
94 | seen when you run the following: | ||
95 | :: | ||
96 | |||
97 | $ bitbake -e | ||
98 | |||
99 | - ``d.delVar('``\ VARNAME\ ``')`` and | ||
100 | ``d.setVar('``\ VARNAME\ ``', None)`` result in the variable and all | ||
101 | of its overrides being cleared out. Before the change, only the | ||
102 | non-overridden values were cleared. | ||
103 | |||
104 | .. _migration-2.0-shell-message-function-changes: | ||
105 | |||
106 | Shell Message Function Changes | ||
107 | ------------------------------ | ||
108 | |||
109 | The shell versions of the BitBake message functions (i.e. ``bbdebug``, | ||
110 | ``bbnote``, ``bbwarn``, ``bbplain``, ``bberror``, and ``bbfatal``) are | ||
111 | now connected through to their BitBake equivalents ``bb.debug()``, | ||
112 | ``bb.note()``, ``bb.warn()``, ``bb.plain()``, ``bb.error()``, and | ||
113 | ``bb.fatal()``, respectively. Thus, those message functions that you | ||
114 | would expect to be printed by the BitBake UI are now actually printed. | ||
115 | In practice, this change means two things: | ||
116 | |||
117 | - If you now see messages on the console that you did not previously | ||
118 | see as a result of this change, you might need to clean up the calls | ||
119 | to ``bbwarn``, ``bberror``, and so forth. Or, you might want to | ||
120 | simply remove the calls. | ||
121 | |||
122 | - The ``bbfatal`` message function now suppresses the full error log in | ||
123 | the UI, which means any calls to ``bbfatal`` where you still wish to | ||
124 | see the full error log should be replaced by ``die`` or | ||
125 | ``bbfatal_log``. | ||
126 | |||
127 | .. _migration-2.0-extra-development-debug-package-cleanup: | ||
128 | |||
129 | Extra Development/Debug Package Cleanup | ||
130 | --------------------------------------- | ||
131 | |||
132 | The following recipes have had extra ``dev/dbg`` packages removed: | ||
133 | |||
134 | - ``acl`` | ||
135 | |||
136 | - ``apmd`` | ||
137 | |||
138 | - ``aspell`` | ||
139 | |||
140 | - ``attr`` | ||
141 | |||
142 | - ``augeas`` | ||
143 | |||
144 | - ``bzip2`` | ||
145 | |||
146 | - ``cogl`` | ||
147 | |||
148 | - ``curl`` | ||
149 | |||
150 | - ``elfutils`` | ||
151 | |||
152 | - ``gcc-target`` | ||
153 | |||
154 | - ``libgcc`` | ||
155 | |||
156 | - ``libtool`` | ||
157 | |||
158 | - ``libxmu`` | ||
159 | |||
160 | - ``opkg`` | ||
161 | |||
162 | - ``pciutils`` | ||
163 | |||
164 | - ``rpm`` | ||
165 | |||
166 | - ``sysfsutils`` | ||
167 | |||
168 | - ``tiff`` | ||
169 | |||
170 | - ``xz`` | ||
171 | |||
172 | All of the above recipes now conform to the standard packaging scheme | ||
173 | where a single ``-dev``, ``-dbg``, and ``-staticdev`` package exists per | ||
174 | recipe. | ||
175 | |||
176 | .. _migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core: | ||
177 | |||
178 | Recipe Maintenance Tracking Data Moved to OE-Core | ||
179 | ------------------------------------------------- | ||
180 | |||
181 | Maintenance tracking data for recipes that was previously part of | ||
182 | ``meta-yocto`` has been moved to :term:`OpenEmbedded-Core (OE-Core)`. The change | ||
183 | includes ``package_regex.inc`` and ``distro_alias.inc``, which are | ||
184 | typically enabled when using the ``distrodata`` class. Additionally, the | ||
185 | contents of ``upstream_tracking.inc`` has now been split out to the | ||
186 | relevant recipes. | ||
187 | |||
188 | .. _migration-2.0-automatic-stale-sysroot-file-cleanup: | ||
189 | |||
190 | Automatic Stale Sysroot File Cleanup | ||
191 | ------------------------------------ | ||
192 | |||
193 | Stale files from recipes that no longer exist in the current | ||
194 | configuration are now automatically removed from sysroot as well as | ||
195 | removed from any other place managed by shared state. This automatic | ||
196 | cleanup means that the build system now properly handles situations such | ||
197 | as renaming the build system side of recipes, removal of layers from | ||
198 | ``bblayers.conf``, and :term:`DISTRO_FEATURES` | ||
199 | changes. | ||
200 | |||
201 | Additionally, work directories for old versions of recipes are now | ||
202 | pruned. If you wish to disable pruning old work directories, you can set | ||
203 | the following variable in your configuration: | ||
204 | :: | ||
205 | |||
206 | SSTATE_PRUNE_OBSOLETEWORKDIR = "0" | ||
207 | |||
208 | .. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source: | ||
209 | |||
210 | ``linux-yocto`` Kernel Metadata Repository Now Split from Source | ||
211 | ---------------------------------------------------------------- | ||
212 | |||
213 | The ``linux-yocto`` tree has up to now been a combined set of kernel | ||
214 | changes and configuration (meta) data carried in a single tree. While | ||
215 | this format is effective at keeping kernel configuration and source | ||
216 | modifications synchronized, it is not always obvious to developers how | ||
217 | to manipulate the Metadata as compared to the source. | ||
218 | |||
219 | Metadata processing has now been removed from the | ||
220 | :ref:`kernel-yocto <ref-classes-kernel-yocto>` class and the external | ||
221 | Metadata repository ``yocto-kernel-cache``, which has always been used | ||
222 | to seed the ``linux-yocto`` "meta" branch. This separate ``linux-yocto`` | ||
223 | cache repository is now the primary location for this data. Due to this | ||
224 | change, ``linux-yocto`` is no longer able to process combined trees. | ||
225 | Thus, if you need to have your own combined kernel repository, you must | ||
226 | do the split there as well and update your recipes accordingly. See the | ||
227 | ``meta/recipes-kernel/linux/linux-yocto_4.1.bb`` recipe for an example. | ||
228 | |||
229 | .. _migration-2.0-additional-qa-checks: | ||
230 | |||
231 | Additional QA checks | ||
232 | -------------------- | ||
233 | |||
234 | The following QA checks have been added: | ||
235 | |||
236 | - Added a "host-user-contaminated" check for ownership issues for | ||
237 | packaged files outside of ``/home``. The check looks for files that | ||
238 | are incorrectly owned by the user that ran BitBake instead of owned | ||
239 | by a valid user in the target system. | ||
240 | |||
241 | - Added an "invalid-chars" check for invalid (non-UTF8) characters in | ||
242 | recipe metadata variable values (i.e. | ||
243 | :term:`DESCRIPTION`, | ||
244 | :term:`SUMMARY`, :term:`LICENSE`, and | ||
245 | :term:`SECTION`). Some package managers do not support | ||
246 | these characters. | ||
247 | |||
248 | - Added an "invalid-packageconfig" check for any options specified in | ||
249 | :term:`PACKAGECONFIG` that do not match any | ||
250 | ``PACKAGECONFIG`` option defined for the recipe. | ||
251 | |||
252 | .. _migration-2.0-miscellaneous: | ||
253 | |||
254 | Miscellaneous Changes | ||
255 | --------------------- | ||
256 | |||
257 | These additional changes exist: | ||
258 | |||
259 | - ``gtk-update-icon-cache`` has been renamed to ``gtk-icon-utils``. | ||
260 | |||
261 | - The ``tools-profile`` :term:`IMAGE_FEATURES` | ||
262 | item as well as its corresponding packagegroup and | ||
263 | ``packagegroup-core-tools-profile`` no longer bring in ``oprofile``. | ||
264 | Bringing in ``oprofile`` was originally added to aid compilation on | ||
265 | resource-constrained targets. However, this aid has not been widely | ||
266 | used and is not likely to be used going forward due to the more | ||
267 | powerful target platforms and the existence of better | ||
268 | cross-compilation tools. | ||
269 | |||
270 | - The :term:`IMAGE_FSTYPES` variable's default | ||
271 | value now specifies ``ext4`` instead of ``ext3``. | ||
272 | |||
273 | - All support for the ``PRINC`` variable has been removed. | ||
274 | |||
275 | - The ``packagegroup-core-full-cmdline`` packagegroup no longer brings | ||
276 | in ``lighttpd`` due to the fact that bringing in ``lighttpd`` is not | ||
277 | really in line with the packagegroup's purpose, which is to add full | ||
278 | versions of command-line tools that by default are provided by | ||
279 | ``busybox``. | ||
280 | |||
281 | |||
diff --git a/documentation/ref-manual/migration-2.1.rst b/documentation/ref-manual/migration-2.1.rst new file mode 100644 index 0000000000..a1fd3ea81d --- /dev/null +++ b/documentation/ref-manual/migration-2.1.rst | |||
@@ -0,0 +1,434 @@ | |||
1 | Moving to the Yocto Project 2.1 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.1 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.1-variable-expansion-in-python-functions: | ||
8 | |||
9 | Variable Expansion in Python Functions | ||
10 | -------------------------------------- | ||
11 | |||
12 | Variable expressions, such as ``${``\ VARNAME\ ``}`` no longer expand | ||
13 | automatically within Python functions. Suppressing expansion was done to | ||
14 | allow Python functions to construct shell scripts or other code for | ||
15 | situations in which you do not want such expressions expanded. For any | ||
16 | existing code that relies on these expansions, you need to change the | ||
17 | expansions to expand the value of individual variables through | ||
18 | ``d.getVar()``. To alternatively expand more complex expressions, use | ||
19 | ``d.expand()``. | ||
20 | |||
21 | .. _migration-2.1-overrides-must-now-be-lower-case: | ||
22 | |||
23 | Overrides Must Now be Lower-Case | ||
24 | -------------------------------- | ||
25 | |||
26 | The convention for overrides has always been for them to be lower-case | ||
27 | characters. This practice is now a requirement as BitBake's datastore | ||
28 | now assumes lower-case characters in order to give a slight performance | ||
29 | boost during parsing. In practical terms, this requirement means that | ||
30 | anything that ends up in :term:`OVERRIDES` must now | ||
31 | appear in lower-case characters (e.g. values for ``MACHINE``, | ||
32 | ``TARGET_ARCH``, ``DISTRO``, and also recipe names if | ||
33 | ``_pn-``\ recipename overrides are to be effective). | ||
34 | |||
35 | .. _migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory: | ||
36 | |||
37 | Expand Parameter to ``getVar()`` and ``getVarFlag()`` is Now Mandatory | ||
38 | ---------------------------------------------------------------------- | ||
39 | |||
40 | The expand parameter to ``getVar()`` and ``getVarFlag()`` previously | ||
41 | defaulted to False if not specified. Now, however, no default exists so | ||
42 | one must be specified. You must change any ``getVar()`` calls that do | ||
43 | not specify the final expand parameter to calls that do specify the | ||
44 | parameter. You can run the following ``sed`` command at the base of a | ||
45 | layer to make this change: | ||
46 | :: | ||
47 | |||
48 | sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` | ||
49 | sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` | ||
50 | |||
51 | .. note:: | ||
52 | |||
53 | The reason for this change is that it prepares the way for changing | ||
54 | the default to True in a future Yocto Project release. This future | ||
55 | change is a much more sensible default than False. However, the | ||
56 | change needs to be made gradually as a sudden change of the default | ||
57 | would potentially cause side-effects that would be difficult to | ||
58 | detect. | ||
59 | |||
60 | .. _migration-2.1-makefile-environment-changes: | ||
61 | |||
62 | Makefile Environment Changes | ||
63 | ---------------------------- | ||
64 | |||
65 | :term:`EXTRA_OEMAKE` now defaults to "" instead of | ||
66 | "-e MAKEFLAGS=". Setting ``EXTRA_OEMAKE`` to "-e MAKEFLAGS=" by default | ||
67 | was a historical accident that has required many classes (e.g. | ||
68 | ``autotools``, ``module``) and recipes to override this default in order | ||
69 | to work with sensible build systems. When upgrading to the release, you | ||
70 | must edit any recipe that relies upon this old default by either setting | ||
71 | ``EXTRA_OEMAKE`` back to "-e MAKEFLAGS=" or by explicitly setting any | ||
72 | required variable value overrides using ``EXTRA_OEMAKE``, which is | ||
73 | typically only needed when a Makefile sets a default value for a | ||
74 | variable that is inappropriate for cross-compilation using the "=" | ||
75 | operator rather than the "?=" operator. | ||
76 | |||
77 | .. _migration-2.1-libexecdir-reverted-to-prefix-libexec: | ||
78 | |||
79 | ``libexecdir`` Reverted to ``${prefix}/libexec`` | ||
80 | ------------------------------------------------ | ||
81 | |||
82 | The use of ``${libdir}/${BPN}`` as ``libexecdir`` is different as | ||
83 | compared to all other mainstream distributions, which either uses | ||
84 | ``${prefix}/libexec`` or ``${libdir}``. The use is also contrary to the | ||
85 | GNU Coding Standards (i.e. | ||
86 | https://www.gnu.org/prep/standards/html_node/Directory-Variables.html) | ||
87 | that suggest ``${prefix}/libexec`` and also notes that any | ||
88 | package-specific nesting should be done by the package itself. Finally, | ||
89 | having ``libexecdir`` change between recipes makes it very difficult for | ||
90 | different recipes to invoke binaries that have been installed into | ||
91 | ``libexecdir``. The Filesystem Hierarchy Standard (i.e. | ||
92 | http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html) now | ||
93 | recognizes the use of ``${prefix}/libexec/``, giving distributions the | ||
94 | choice between ``${prefix}/lib`` or ``${prefix}/libexec`` without | ||
95 | breaking FHS. | ||
96 | |||
97 | .. _migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files: | ||
98 | |||
99 | ``ac_cv_sizeof_off_t`` is No Longer Cached in Site Files | ||
100 | -------------------------------------------------------- | ||
101 | |||
102 | For recipes inheriting the :ref:`autotools <ref-classes-autotools>` | ||
103 | class, ``ac_cv_sizeof_off_t`` is no longer cached in the site files for | ||
104 | ``autoconf``. The reason for this change is because the | ||
105 | ``ac_cv_sizeof_off_t`` value is not necessarily static per architecture | ||
106 | as was previously assumed. Rather, the value changes based on whether | ||
107 | large file support is enabled. For most software that uses ``autoconf``, | ||
108 | this change should not be a problem. However, if you have a recipe that | ||
109 | bypasses the standard :ref:`ref-tasks-configure` task | ||
110 | from the ``autotools`` class and the software the recipe is building | ||
111 | uses a very old version of ``autoconf``, the recipe might be incapable | ||
112 | of determining the correct size of ``off_t`` during ``do_configure``. | ||
113 | |||
114 | The best course of action is to patch the software as necessary to allow | ||
115 | the default implementation from the ``autotools`` class to work such | ||
116 | that ``autoreconf`` succeeds and produces a working configure script, | ||
117 | and to remove the overridden ``do_configure`` task such that the default | ||
118 | implementation does get used. | ||
119 | |||
120 | .. _migration-2.1-image-generation-split-out-from-filesystem-generation: | ||
121 | |||
122 | Image Generation is Now Split Out from Filesystem Generation | ||
123 | ------------------------------------------------------------ | ||
124 | |||
125 | Previously, for image recipes the :ref:`ref-tasks-rootfs` | ||
126 | task assembled the filesystem and then from that filesystem generated | ||
127 | images. With this Yocto Project release, image generation is split into | ||
128 | separate ```do_image_*`` <#ref-tasks-image>`__ tasks for clarity both in | ||
129 | operation and in the code. | ||
130 | |||
131 | For most cases, this change does not present any problems. However, if | ||
132 | you have made customizations that directly modify the ``do_rootfs`` task | ||
133 | or that mention ``do_rootfs``, you might need to update those changes. | ||
134 | In particular, if you had added any tasks after ``do_rootfs``, you | ||
135 | should make edits so that those tasks are after the | ||
136 | ```do_image_complete`` <#ref-tasks-image-complete>`__ task rather than | ||
137 | after ``do_rootfs`` so that the your added tasks run at the correct | ||
138 | time. | ||
139 | |||
140 | A minor part of this restructuring is that the post-processing | ||
141 | definitions and functions have been moved from the | ||
142 | :ref:`image <ref-classes-image>` class to the | ||
143 | :ref:`rootfs-postcommands <ref-classes-rootfs*>` class. Functionally, | ||
144 | however, they remain unchanged. | ||
145 | |||
146 | .. _migration-2.1-removed-recipes: | ||
147 | |||
148 | Removed Recipes | ||
149 | --------------- | ||
150 | |||
151 | The following recipes have been removed in the 2.1 release: | ||
152 | |||
153 | - ``gcc`` version 4.8: Versions 4.9 and 5.3 remain. | ||
154 | |||
155 | - ``qt4``: All support for Qt 4.x has been moved out to a separate | ||
156 | ``meta-qt4`` layer because Qt 4 is no longer supported upstream. | ||
157 | |||
158 | - ``x11vnc``: Moved to the ``meta-oe`` layer. | ||
159 | |||
160 | - ``linux-yocto-3.14``: No longer supported. | ||
161 | |||
162 | - ``linux-yocto-3.19``: No longer supported. | ||
163 | |||
164 | - ``libjpeg``: Replaced by the ``libjpeg-turbo`` recipe. | ||
165 | |||
166 | - ``pth``: Became obsolete. | ||
167 | |||
168 | - ``liboil``: Recipe is no longer needed and has been moved to the | ||
169 | ``meta-multimedia`` layer. | ||
170 | |||
171 | - ``gtk-theme-torturer``: Recipe is no longer needed and has been moved | ||
172 | to the ``meta-gnome`` layer. | ||
173 | |||
174 | - ``gnome-mime-data``: Recipe is no longer needed and has been moved to | ||
175 | the ``meta-gnome`` layer. | ||
176 | |||
177 | - ``udev``: Replaced by the ``eudev`` recipe for compatibility when | ||
178 | using ``sysvinit`` with newer kernels. | ||
179 | |||
180 | - ``python-pygtk``: Recipe became obsolete. | ||
181 | |||
182 | - ``adt-installer``: Recipe became obsolete. See the "`ADT | ||
183 | Removed <#migration-2.1-adt-removed>`__" section for more | ||
184 | information. | ||
185 | |||
186 | .. _migration-2.1-class-changes: | ||
187 | |||
188 | Class Changes | ||
189 | ------------- | ||
190 | |||
191 | The following classes have changed: | ||
192 | |||
193 | - ``autotools_stage``: Removed because the | ||
194 | :ref:`autotools <ref-classes-autotools>` class now provides its | ||
195 | functionality. Recipes that inherited from ``autotools_stage`` should | ||
196 | now inherit from ``autotools`` instead. | ||
197 | |||
198 | - ``boot-directdisk``: Merged into the ``image-vm`` class. The | ||
199 | ``boot-directdisk`` class was rarely directly used. Consequently, | ||
200 | this change should not cause any issues. | ||
201 | |||
202 | - ``bootimg``: Merged into the | ||
203 | :ref:`image-live <ref-classes-image-live>` class. The ``bootimg`` | ||
204 | class was rarely directly used. Consequently, this change should not | ||
205 | cause any issues. | ||
206 | |||
207 | - ``packageinfo``: Removed due to its limited use by the Hob UI, which | ||
208 | has itself been removed. | ||
209 | |||
210 | .. _migration-2.1-build-system-ui-changes: | ||
211 | |||
212 | Build System User Interface Changes | ||
213 | ----------------------------------- | ||
214 | |||
215 | The following changes have been made to the build system user interface: | ||
216 | |||
217 | - *Hob GTK+-based UI*: Removed because it is unmaintained and based on | ||
218 | the outdated GTK+ 2 library. The Toaster web-based UI is much more | ||
219 | capable and is actively maintained. See the | ||
220 | ":ref:`toaster-manual/toaster-manual-setup-and-use:using the toaster web interface`" | ||
221 | section in the Toaster User Manual for more information on this | ||
222 | interface. | ||
223 | |||
224 | - *"puccho" BitBake UI*: Removed because is unmaintained and no longer | ||
225 | useful. | ||
226 | |||
227 | .. _migration-2.1-adt-removed: | ||
228 | |||
229 | ADT Removed | ||
230 | ----------- | ||
231 | |||
232 | The Application Development Toolkit (ADT) has been removed because its | ||
233 | functionality almost completely overlapped with the :ref:`standard | ||
234 | SDK <sdk-manual/sdk-using:using the standard sdk>` and the | ||
235 | :ref:`extensible SDK <sdk-manual/sdk-extensible:using the extensible sdk>`. For | ||
236 | information on these SDKs and how to build and use them, see the | ||
237 | :doc:`../sdk-manual/sdk-manual` manual. | ||
238 | |||
239 | .. note:: | ||
240 | |||
241 | The Yocto Project Eclipse IDE Plug-in is still supported and is not | ||
242 | affected by this change. | ||
243 | |||
244 | .. _migration-2.1-poky-reference-distribution-changes: | ||
245 | |||
246 | Poky Reference Distribution Changes | ||
247 | ----------------------------------- | ||
248 | |||
249 | The following changes have been made for the Poky distribution: | ||
250 | |||
251 | - The ``meta-yocto`` layer has been renamed to ``meta-poky`` to better | ||
252 | match its purpose, which is to provide the Poky reference | ||
253 | distribution. The ``meta-yocto-bsp`` layer retains its original name | ||
254 | since it provides reference machines for the Yocto Project and it is | ||
255 | otherwise unrelated to Poky. References to ``meta-yocto`` in your | ||
256 | ``conf/bblayers.conf`` should automatically be updated, so you should | ||
257 | not need to change anything unless you are relying on this naming | ||
258 | elsewhere. | ||
259 | |||
260 | - The :ref:`uninative <ref-classes-uninative>` class is now enabled | ||
261 | by default in Poky. This class attempts to isolate the build system | ||
262 | from the host distribution's C library and makes re-use of native | ||
263 | shared state artifacts across different host distributions practical. | ||
264 | With this class enabled, a tarball containing a pre-built C library | ||
265 | is downloaded at the start of the build. | ||
266 | |||
267 | The ``uninative`` class is enabled through the | ||
268 | ``meta/conf/distro/include/yocto-uninative.inc`` file, which for | ||
269 | those not using the Poky distribution, can include to easily enable | ||
270 | the same functionality. | ||
271 | |||
272 | Alternatively, if you wish to build your own ``uninative`` tarball, | ||
273 | you can do so by building the ``uninative-tarball`` recipe, making it | ||
274 | available to your build machines (e.g. over HTTP/HTTPS) and setting a | ||
275 | similar configuration as the one set by ``yocto-uninative.inc``. | ||
276 | |||
277 | - Static library generation, for most cases, is now disabled by default | ||
278 | in the Poky distribution. Disabling this generation saves some build | ||
279 | time as well as the size used for build output artifacts. | ||
280 | |||
281 | Disabling this library generation is accomplished through a | ||
282 | ``meta/conf/distro/include/no-static-libs.inc``, which for those not | ||
283 | using the Poky distribution can easily include to enable the same | ||
284 | functionality. | ||
285 | |||
286 | Any recipe that needs to opt-out of having the "--disable-static" | ||
287 | option specified on the configure command line either because it is | ||
288 | not a supported option for the configure script or because static | ||
289 | libraries are needed should set the following variable: | ||
290 | DISABLE_STATIC = "" | ||
291 | |||
292 | - The separate ``poky-tiny`` distribution now uses the musl C library | ||
293 | instead of a heavily pared down ``glibc``. Using musl results in a | ||
294 | smaller distribution and facilitates much greater maintainability | ||
295 | because musl is designed to have a small footprint. | ||
296 | |||
297 | If you have used ``poky-tiny`` and have customized the ``glibc`` | ||
298 | configuration you will need to redo those customizations with musl | ||
299 | when upgrading to the new release. | ||
300 | |||
301 | .. _migration-2.1-packaging-changes: | ||
302 | |||
303 | Packaging Changes | ||
304 | ----------------- | ||
305 | |||
306 | The following changes have been made to packaging: | ||
307 | |||
308 | - The ``runuser`` and ``mountpoint`` binaries, which were previously in | ||
309 | the main ``util-linux`` package, have been split out into the | ||
310 | ``util-linux-runuser`` and ``util-linux-mountpoint`` packages, | ||
311 | respectively. | ||
312 | |||
313 | - The ``python-elementtree`` package has been merged into the | ||
314 | ``python-xml`` package. | ||
315 | |||
316 | .. _migration-2.1-tuning-file-changes: | ||
317 | |||
318 | Tuning File Changes | ||
319 | ------------------- | ||
320 | |||
321 | The following changes have been made to the tuning files: | ||
322 | |||
323 | - The "no-thumb-interwork" tuning feature has been dropped from the ARM | ||
324 | tune include files. Because interworking is required for ARM EABI, | ||
325 | attempting to disable it through a tuning feature no longer makes | ||
326 | sense. | ||
327 | |||
328 | .. note:: | ||
329 | |||
330 | Support for ARM OABI was deprecated in gcc 4.7. | ||
331 | |||
332 | - The ``tune-cortexm*.inc`` and ``tune-cortexr4.inc`` files have been | ||
333 | removed because they are poorly tested. Until the OpenEmbedded build | ||
334 | system officially gains support for CPUs without an MMU, these tuning | ||
335 | files would probably be better maintained in a separate layer if | ||
336 | needed. | ||
337 | |||
338 | .. _migration-2.1-supporting-gobject-introspection: | ||
339 | |||
340 | Supporting GObject Introspection | ||
341 | -------------------------------- | ||
342 | |||
343 | This release supports generation of GLib Introspective Repository (GIR) | ||
344 | files through GObject introspection, which is the standard mechanism for | ||
345 | accessing GObject-based software from runtime environments. You can | ||
346 | enable, disable, and test the generation of this data. See the | ||
347 | ":ref:`dev-manual/dev-manual-common-tasks:enabling gobject introspection support`" | ||
348 | section in the Yocto Project Development Tasks Manual for more | ||
349 | information. | ||
350 | |||
351 | .. _migration-2.1-miscellaneous-changes: | ||
352 | |||
353 | Miscellaneous Changes | ||
354 | --------------------- | ||
355 | |||
356 | These additional changes exist: | ||
357 | |||
358 | - The minimum Git version has been increased to 1.8.3.1. If your host | ||
359 | distribution does not provide a sufficiently recent version, you can | ||
360 | install the buildtools, which will provide it. See the "`Required | ||
361 | Git, tar, Python and gcc | ||
362 | Versions <#required-git-tar-python-and-gcc-versions>`__" section for | ||
363 | more information on the buildtools tarball. | ||
364 | |||
365 | - The buggy and incomplete support for the RPM version 4 package | ||
366 | manager has been removed. The well-tested and maintained support for | ||
367 | RPM version 5 remains. | ||
368 | |||
369 | - Previously, the following list of packages were removed if | ||
370 | package-management was not in | ||
371 | :term:`IMAGE_FEATURES`, regardless of any | ||
372 | dependencies: | ||
373 | :: | ||
374 | |||
375 | update-rc.d | ||
376 | base-passwd | ||
377 | shadow | ||
378 | update-alternatives | ||
379 | |||
380 | run-postinsts With the Yocto Project 2.1 release, these packages are | ||
381 | only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since | ||
382 | they might still be needed for a read-write image even in the absence | ||
383 | of a package manager (e.g. if users need to be added, modified, or | ||
384 | removed at runtime). | ||
385 | |||
386 | - The | ||
387 | :ref:`devtool modify <sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component>` | ||
388 | command now defaults to extracting the source since that is most | ||
389 | commonly expected. The "-x" or "--extract" options are now no-ops. If | ||
390 | you wish to provide your own existing source tree, you will now need | ||
391 | to specify either the "-n" or "--no-extract" options when running | ||
392 | ``devtool modify``. | ||
393 | |||
394 | - If the formfactor for a machine is either not supplied or does not | ||
395 | specify whether a keyboard is attached, then the default is to assume | ||
396 | a keyboard is attached rather than assume no keyboard. This change | ||
397 | primarily affects the Sato UI. | ||
398 | |||
399 | - The ``.debug`` directory packaging is now automatic. If your recipe | ||
400 | builds software that installs binaries into directories other than | ||
401 | the standard ones, you no longer need to take care of setting | ||
402 | ``FILES_${PN}-dbg`` to pick up the resulting ``.debug`` directories | ||
403 | as these directories are automatically found and added. | ||
404 | |||
405 | - Inaccurate disk and CPU percentage data has been dropped from | ||
406 | ``buildstats`` output. This data has been replaced with | ||
407 | ``getrusage()`` data and corrected IO statistics. You will probably | ||
408 | need to update any custom code that reads the ``buildstats`` data. | ||
409 | |||
410 | - The ``meta/conf/distro/include/package_regex.inc`` is now deprecated. | ||
411 | The contents of this file have been moved to individual recipes. | ||
412 | |||
413 | .. note:: | ||
414 | |||
415 | Because this file will likely be removed in a future Yocto Project | ||
416 | release, it is suggested that you remove any references to the | ||
417 | file that might be in your configuration. | ||
418 | |||
419 | - The ``v86d/uvesafb`` has been removed from the ``genericx86`` and | ||
420 | ``genericx86-64`` reference machines, which are provided by the | ||
421 | ``meta-yocto-bsp`` layer. Most modern x86 boards do not rely on this | ||
422 | file and it only adds kernel error messages during startup. If you do | ||
423 | still need to support ``uvesafb``, you can simply add ``v86d`` to | ||
424 | your image. | ||
425 | |||
426 | - Build sysroot paths are now removed from debug symbol files. Removing | ||
427 | these paths means that remote GDB using an unstripped build system | ||
428 | sysroot will no longer work (although this was never documented to | ||
429 | work). The supported method to accomplish something similar is to set | ||
430 | ``IMAGE_GEN_DEBUGFS`` to "1", which will generate a companion debug | ||
431 | image containing unstripped binaries and associated debug sources | ||
432 | alongside the image. | ||
433 | |||
434 | |||
diff --git a/documentation/ref-manual/migration-2.2.rst b/documentation/ref-manual/migration-2.2.rst new file mode 100644 index 0000000000..59d0eeeb9d --- /dev/null +++ b/documentation/ref-manual/migration-2.2.rst | |||
@@ -0,0 +1,451 @@ | |||
1 | Moving to the Yocto Project 2.2 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.2 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.2-minimum-kernel-version: | ||
8 | |||
9 | Minimum Kernel Version | ||
10 | ---------------------- | ||
11 | |||
12 | The minimum kernel version for the target system and for SDK is now | ||
13 | 3.2.0, due to the upgrade to ``glibc 2.24``. Specifically, for | ||
14 | AArch64-based targets the version is 3.14. For Nios II-based targets, | ||
15 | the minimum kernel version is 3.19. | ||
16 | |||
17 | .. note:: | ||
18 | |||
19 | For x86 and x86_64, you can reset | ||
20 | OLDEST_KERNEL | ||
21 | to anything down to 2.6.32 if desired. | ||
22 | |||
23 | .. _migration-2.2-staging-directories-in-sysroot-simplified: | ||
24 | |||
25 | Staging Directories in Sysroot Has Been Simplified | ||
26 | -------------------------------------------------- | ||
27 | |||
28 | The way directories are staged in sysroot has been simplified and | ||
29 | introduces the new :term:`SYSROOT_DIRS`, | ||
30 | :term:`SYSROOT_DIRS_NATIVE`, and | ||
31 | :term:`SYSROOT_DIRS_BLACKLIST`. See the | ||
32 | `v2 patch series on the OE-Core Mailing | ||
33 | List <http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html>`__ | ||
34 | for additional information. | ||
35 | |||
36 | .. _migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled: | ||
37 | |||
38 | Removal of Old Images and Other Files in ``tmp/deploy`` Now Enabled | ||
39 | ------------------------------------------------------------------- | ||
40 | |||
41 | Removal of old images and other files in ``tmp/deploy/`` is now enabled | ||
42 | by default due to a new staging method used for those files. As a result | ||
43 | of this change, the ``RM_OLD_IMAGE`` variable is now redundant. | ||
44 | |||
45 | .. _migration-2.2-python-changes: | ||
46 | |||
47 | Python Changes | ||
48 | -------------- | ||
49 | |||
50 | The following changes for Python occurred: | ||
51 | |||
52 | .. _migration-2.2-bitbake-now-requires-python-3.4: | ||
53 | |||
54 | BitBake Now Requires Python 3.4+ | ||
55 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
56 | |||
57 | BitBake requires Python 3.4 or greater. | ||
58 | |||
59 | .. _migration-2.2-utf-8-locale-required-on-build-host: | ||
60 | |||
61 | UTF-8 Locale Required on Build Host | ||
62 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
63 | |||
64 | A UTF-8 locale is required on the build host due to Python 3. Since | ||
65 | C.UTF-8 is not a standard, the default is en_US.UTF-8. | ||
66 | |||
67 | .. _migration-2.2-metadata-now-must-use-python-3-syntax: | ||
68 | |||
69 | Metadata Must Now Use Python 3 Syntax | ||
70 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
71 | |||
72 | The metadata is now required to use Python 3 syntax. For help preparing | ||
73 | metadata, see any of the many Python 3 porting guides available. | ||
74 | Alternatively, you can reference the conversion commits for Bitbake and | ||
75 | you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are | ||
76 | particular areas of interest: | ||
77 | |||
78 | - subprocess command-line pipes needing locale decoding | ||
79 | |||
80 | - the syntax for octal values changed | ||
81 | |||
82 | - the ``iter*()`` functions changed name \* iterators now return views, not lists | ||
83 | |||
84 | - changed names for Python modules | ||
85 | |||
86 | .. _migration-2.2-target-python-recipes-switched-to-python-3: | ||
87 | |||
88 | Target Python Recipes Switched to Python 3 | ||
89 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
90 | |||
91 | Most target Python recipes have now been switched to Python 3. | ||
92 | Unfortunately, systems using RPM as a package manager and providing | ||
93 | online package-manager support through SMART still require Python 2. | ||
94 | |||
95 | .. note:: | ||
96 | |||
97 | Python 2 and recipes that use it can still be built for the target as | ||
98 | with previous versions. | ||
99 | |||
100 | .. _migration-2.2-buildtools-tarball-includes-python-3: | ||
101 | |||
102 | ``buildtools-tarball`` Includes Python 3 | ||
103 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
104 | |||
105 | ``buildtools-tarball`` now includes Python 3. | ||
106 | |||
107 | .. _migration-2.2-uclibc-replaced-by-musl: | ||
108 | |||
109 | uClibc Replaced by musl | ||
110 | ----------------------- | ||
111 | |||
112 | uClibc has been removed in favor of musl. Musl has matured, is better | ||
113 | maintained, and is compatible with a wider range of applications as | ||
114 | compared to uClibc. | ||
115 | |||
116 | .. _migration-2.2-B-no-longer-default-working-directory-for-tasks: | ||
117 | |||
118 | ``${B}`` No Longer Default Working Directory for Tasks | ||
119 | ------------------------------------------------------ | ||
120 | |||
121 | ``${``\ :term:`B`\ ``}`` is no longer the default working | ||
122 | directory for tasks. Consequently, any custom tasks you define now need | ||
123 | to either have the | ||
124 | ``[``\ :ref:`dirs <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` flag | ||
125 | set, or the task needs to change into the appropriate working directory | ||
126 | manually (e.g using ``cd`` for a shell task). | ||
127 | |||
128 | .. note:: | ||
129 | |||
130 | The preferred method is to use the | ||
131 | [dirs] | ||
132 | flag. | ||
133 | |||
134 | .. _migration-2.2-runqemu-ported-to-python: | ||
135 | |||
136 | ``runqemu`` Ported to Python | ||
137 | ---------------------------- | ||
138 | |||
139 | ``runqemu`` has been ported to Python and has changed behavior in some | ||
140 | cases. Previous usage patterns continue to be supported. | ||
141 | |||
142 | The new ``runqemu`` is a Python script. Machine knowledge is no longer | ||
143 | hardcoded into ``runqemu``. You can choose to use the ``qemuboot`` | ||
144 | configuration file to define the BSP's own arguments and to make it | ||
145 | bootable with ``runqemu``. If you use a configuration file, use the | ||
146 | following form: | ||
147 | :: | ||
148 | |||
149 | image-name-machine.qemuboot.conf | ||
150 | |||
151 | The configuration file | ||
152 | enables fine-grained tuning of options passed to QEMU without the | ||
153 | ``runqemu`` script hard-coding any knowledge about different machines. | ||
154 | Using a configuration file is particularly convenient when trying to use | ||
155 | QEMU with machines other than the ``qemu*`` machines in | ||
156 | :term:`OpenEmbedded-Core (OE-Core)`. The ``qemuboot.conf`` file is generated by the | ||
157 | ``qemuboot`` class when the root filesystem is being build (i.e. build | ||
158 | rootfs). QEMU boot arguments can be set in BSP's configuration file and | ||
159 | the ``qemuboot`` class will save them to ``qemuboot.conf``. | ||
160 | |||
161 | If you want to use ``runqemu`` without a configuration file, use the | ||
162 | following command form: | ||
163 | :: | ||
164 | |||
165 | $ runqemu machine rootfs kernel [options] | ||
166 | |||
167 | Supported machines are as follows: | ||
168 | |||
169 | - qemuarm | ||
170 | - qemuarm64 | ||
171 | - qemux86 | ||
172 | - qemux86-64 | ||
173 | - qemuppc | ||
174 | - qemumips | ||
175 | - qemumips64 | ||
176 | - qemumipsel | ||
177 | - qemumips64el | ||
178 | |||
179 | Consider the | ||
180 | following example, which uses the ``qemux86-64`` machine, provides a | ||
181 | root filesystem, provides an image, and uses the ``nographic`` option: :: | ||
182 | |||
183 | $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic | ||
184 | |||
185 | Following is a list of variables that can be set in configuration files | ||
186 | such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``: | ||
187 | |||
188 | .. note:: | ||
189 | |||
190 | "QB" means "QEMU Boot". | ||
191 | |||
192 | :: | ||
193 | |||
194 | QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386") | ||
195 | QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor") | ||
196 | QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage") | ||
197 | QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4") | ||
198 | QB_MEM: Memory (e.g. "-m 512") | ||
199 | QB_MACHINE: QEMU machine (e.g. "-machine virt") | ||
200 | QB_CPU: QEMU cpu (e.g. "-cpu qemu32") | ||
201 | QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64") | ||
202 | QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append | ||
203 | option (e.g. "console=ttyS0 console=tty") | ||
204 | QB_DTB: QEMU dtb name | ||
205 | QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio) | ||
206 | QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used | ||
207 | when QB_AUDIO_DRV is set. | ||
208 | QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda) | ||
209 | QB_TAP_OPT: Network option for 'tap' mode (e.g. | ||
210 | "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0"). | ||
211 | runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ... | ||
212 | QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0") | ||
213 | QB_ROOTFS_OPT: Used as rootfs (e.g. | ||
214 | "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0"). | ||
215 | runqemu will replace "@ROOTFS@" with the one which is used, such as | ||
216 | core-image-minimal-qemuarm64.ext4. | ||
217 | QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio") | ||
218 | QB_TCPSERIAL_OPT: tcp serial port option (e.g. | ||
219 | " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" | ||
220 | runqemu will replace "@PORT@" with the port number which is used. | ||
221 | |||
222 | To use ``runqemu``, set :term:`IMAGE_CLASSES` as | ||
223 | follows and run ``runqemu``: | ||
224 | |||
225 | .. note:: | ||
226 | |||
227 | For command-line syntax, use | ||
228 | runqemu help | ||
229 | . | ||
230 | |||
231 | :: | ||
232 | |||
233 | IMAGE_CLASSES += "qemuboot" | ||
234 | |||
235 | .. _migration-2.2-default-linker-hash-style-changed: | ||
236 | |||
237 | Default Linker Hash Style Changed | ||
238 | --------------------------------- | ||
239 | |||
240 | The default linker hash style for ``gcc-cross`` is now "sysv" in order | ||
241 | to catch recipes that are building software without using the | ||
242 | OpenEmbedded :term:`LDFLAGS`. This change could result in | ||
243 | seeing some "No GNU_HASH in the elf binary" QA issues when building such | ||
244 | recipes. You need to fix these recipes so that they use the expected | ||
245 | ``LDFLAGS``. Depending on how the software is built, the build system | ||
246 | used by the software (e.g. a Makefile) might need to be patched. | ||
247 | However, sometimes making this fix is as simple as adding the following | ||
248 | to the recipe: | ||
249 | :: | ||
250 | |||
251 | TARGET_CC_ARCH += "${LDFLAGS}" | ||
252 | |||
253 | .. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype: | ||
254 | |||
255 | ``KERNEL_IMAGE_BASE_NAME`` no Longer Uses ``KERNEL_IMAGETYPE`` | ||
256 | -------------------------------------------------------------- | ||
257 | |||
258 | The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the | ||
259 | :term:`KERNEL_IMAGETYPE` variable to create the | ||
260 | image's base name. Because the OpenEmbedded build system can now build | ||
261 | multiple kernel image types, this part of the kernel image base name as | ||
262 | been removed leaving only the following: | ||
263 | :: | ||
264 | |||
265 | KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" | ||
266 | |||
267 | If you have recipes or | ||
268 | classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to | ||
269 | update the references to ensure they continue to work. | ||
270 | |||
271 | .. _migration-2.2-bitbake-changes: | ||
272 | |||
273 | BitBake Changes | ||
274 | --------------- | ||
275 | |||
276 | The following changes took place for BitBake: | ||
277 | |||
278 | - The "goggle" UI and standalone image-writer tool have been removed as | ||
279 | they both require GTK+ 2.0 and were not being maintained. | ||
280 | |||
281 | - The Perforce fetcher now supports :term:`SRCREV` for | ||
282 | specifying the source revision to use, be it | ||
283 | ``${``\ :term:`AUTOREV`\ ``}``, changelist number, | ||
284 | p4date, or label, in preference to separate | ||
285 | :term:`SRC_URI` parameters to specify these. This | ||
286 | change is more in-line with how the other fetchers work for source | ||
287 | control systems. Recipes that fetch from Perforce will need to be | ||
288 | updated to use ``SRCREV`` in place of specifying the source revision | ||
289 | within ``SRC_URI``. | ||
290 | |||
291 | - Some of BitBake's internal code structures for accessing the recipe | ||
292 | cache needed to be changed to support the new multi-configuration | ||
293 | functionality. These changes will affect external tools that use | ||
294 | BitBake's tinfoil module. For information on these changes, see the | ||
295 | changes made to the scripts supplied with OpenEmbedded-Core: | ||
296 | `1 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee>`__ | ||
297 | and | ||
298 | `2 <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67>`__. | ||
299 | |||
300 | - The task management code has been rewritten to avoid using ID | ||
301 | indirection in order to improve performance. This change is unlikely | ||
302 | to cause any problems for most users. However, the setscene | ||
303 | verification function as pointed to by | ||
304 | ``BB_SETSCENE_VERIFY_FUNCTION`` needed to change signature. | ||
305 | Consequently, a new variable named ``BB_SETSCENE_VERIFY_FUNCTION2`` | ||
306 | has been added allowing multiple versions of BitBake to work with | ||
307 | suitably written metadata, which includes OpenEmbedded-Core and Poky. | ||
308 | Anyone with custom BitBake task scheduler code might also need to | ||
309 | update the code to handle the new structure. | ||
310 | |||
311 | .. _migration-2.2-swabber-has-been-removed: | ||
312 | |||
313 | Swabber has Been Removed | ||
314 | ------------------------ | ||
315 | |||
316 | Swabber, a tool that was intended to detect host contamination in the | ||
317 | build process, has been removed, as it has been unmaintained and unused | ||
318 | for some time and was never particularly effective. The OpenEmbedded | ||
319 | build system has since incorporated a number of mechanisms including | ||
320 | enhanced QA checks that mean that there is less of a need for such a | ||
321 | tool. | ||
322 | |||
323 | .. _migration-2.2-removed-recipes: | ||
324 | |||
325 | Removed Recipes | ||
326 | --------------- | ||
327 | |||
328 | The following recipes have been removed: | ||
329 | |||
330 | - ``augeas``: No longer needed and has been moved to ``meta-oe``. | ||
331 | |||
332 | - ``directfb``: Unmaintained and has been moved to ``meta-oe``. | ||
333 | |||
334 | - ``gcc``: Removed 4.9 version. Versions 5.4 and 6.2 are still present. | ||
335 | |||
336 | - ``gnome-doc-utils``: No longer needed. | ||
337 | |||
338 | - ``gtk-doc-stub``: Replaced by ``gtk-doc``. | ||
339 | |||
340 | - ``gtk-engines``: No longer needed and has been moved to | ||
341 | ``meta-gnome``. | ||
342 | |||
343 | - ``gtk-sato-engine``: Became obsolete. | ||
344 | |||
345 | - ``libglade``: No longer needed and has been moved to ``meta-oe``. | ||
346 | |||
347 | - ``libmad``: Unmaintained and functionally replaced by ``libmpg123``. | ||
348 | ``libmad`` has been moved to ``meta-oe``. | ||
349 | |||
350 | - ``libowl``: Became obsolete. | ||
351 | |||
352 | - ``libxsettings-client``: No longer needed. | ||
353 | |||
354 | - ``oh-puzzles``: Functionally replaced by ``puzzles``. | ||
355 | |||
356 | - ``oprofileui``: Became obsolete. OProfile has been largely supplanted | ||
357 | by perf. | ||
358 | |||
359 | - ``packagegroup-core-directfb.bb``: Removed. | ||
360 | |||
361 | - ``core-image-directfb.bb``: Removed. | ||
362 | |||
363 | - ``pointercal``: No longer needed and has been moved to ``meta-oe``. | ||
364 | |||
365 | - ``python-imaging``: No longer needed and moved to ``meta-python`` | ||
366 | |||
367 | - ``python-pyrex``: No longer needed and moved to ``meta-python``. | ||
368 | |||
369 | - ``sato-icon-theme``: Became obsolete. | ||
370 | |||
371 | - ``swabber-native``: Swabber has been removed. See the `entry on | ||
372 | Swabber <#migration-2.2-swabber-has-been-removed>`__. | ||
373 | |||
374 | - ``tslib``: No longer needed and has been moved to ``meta-oe``. | ||
375 | |||
376 | - ``uclibc``: Removed in favor of musl. | ||
377 | |||
378 | - ``xtscal``: No longer needed and moved to ``meta-oe`` | ||
379 | |||
380 | .. _migration-2.2-removed-classes: | ||
381 | |||
382 | Removed Classes | ||
383 | --------------- | ||
384 | |||
385 | The following classes have been removed: | ||
386 | |||
387 | - ``distutils-native-base``: No longer needed. | ||
388 | |||
389 | - ``distutils3-native-base``: No longer needed. | ||
390 | |||
391 | - ``sdl``: Only set :term:`DEPENDS` and | ||
392 | :term:`SECTION`, which are better set within the | ||
393 | recipe instead. | ||
394 | |||
395 | - ``sip``: Mostly unused. | ||
396 | |||
397 | - ``swabber``: See the `entry on | ||
398 | Swabber <#migration-2.2-swabber-has-been-removed>`__. | ||
399 | |||
400 | .. _migration-2.2-minor-packaging-changes: | ||
401 | |||
402 | Minor Packaging Changes | ||
403 | ----------------------- | ||
404 | |||
405 | The following minor packaging changes have occurred: | ||
406 | |||
407 | - ``grub``: Split ``grub-editenv`` into its own package. | ||
408 | |||
409 | - ``systemd``: Split container and vm related units into a new package, | ||
410 | systemd-container. | ||
411 | |||
412 | - ``util-linux``: Moved ``prlimit`` to a separate | ||
413 | ``util-linux-prlimit`` package. | ||
414 | |||
415 | .. _migration-2.2-miscellaneous-changes: | ||
416 | |||
417 | Miscellaneous Changes | ||
418 | --------------------- | ||
419 | |||
420 | The following miscellaneous changes have occurred: | ||
421 | |||
422 | - ``package_regex.inc``: Removed because the definitions | ||
423 | ``package_regex.inc`` previously contained have been moved to their | ||
424 | respective recipes. | ||
425 | |||
426 | - Both ``devtool add`` and ``recipetool create`` now use a fixed | ||
427 | :term:`SRCREV` by default when fetching from a Git | ||
428 | repository. You can override this in either case to use | ||
429 | ``${``\ :term:`AUTOREV`\ ``}`` instead by using the | ||
430 | ``-a`` or ``DASHDASHautorev`` command-line option | ||
431 | |||
432 | - ``distcc``: GTK+ UI is now disabled by default. | ||
433 | |||
434 | - ``packagegroup-core-tools-testapps``: Removed Piglit. | ||
435 | |||
436 | - ``image.bbclass``: Renamed COMPRESS(ION) to CONVERSION. This change | ||
437 | means that ``COMPRESSIONTYPES``, ``COMPRESS_DEPENDS`` and | ||
438 | ``COMPRESS_CMD`` are deprecated in favor of ``CONVERSIONTYPES``, | ||
439 | ``CONVERSION_DEPENDS`` and ``CONVERSION_CMD``. The ``COMPRESS*`` | ||
440 | variable names will still work in the 2.2 release but metadata that | ||
441 | does not need to be backwards-compatible should be changed to use the | ||
442 | new names as the ``COMPRESS*`` ones will be removed in a future | ||
443 | release. | ||
444 | |||
445 | - ``gtk-doc``: A full version of ``gtk-doc`` is now made available. | ||
446 | However, some old software might not be capable of using the current | ||
447 | version of ``gtk-doc`` to build documentation. You need to change | ||
448 | recipes that build such software so that they explicitly disable | ||
449 | building documentation with ``gtk-doc``. | ||
450 | |||
451 | |||
diff --git a/documentation/ref-manual/migration-2.3.rst b/documentation/ref-manual/migration-2.3.rst new file mode 100644 index 0000000000..7f34f0cd75 --- /dev/null +++ b/documentation/ref-manual/migration-2.3.rst | |||
@@ -0,0 +1,530 @@ | |||
1 | Moving to the Yocto Project 2.3 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.3 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.3-recipe-specific-sysroots: | ||
8 | |||
9 | Recipe-specific Sysroots | ||
10 | ------------------------ | ||
11 | |||
12 | The OpenEmbedded build system now uses one sysroot per recipe to resolve | ||
13 | long-standing issues with configuration script auto-detection of | ||
14 | undeclared dependencies. Consequently, you might find that some of your | ||
15 | previously written custom recipes are missing declared dependencies, | ||
16 | particularly those dependencies that are incidentally built earlier in a | ||
17 | typical build process and thus are already likely to be present in the | ||
18 | shared sysroot in previous releases. | ||
19 | |||
20 | Consider the following: | ||
21 | |||
22 | - *Declare Build-Time Dependencies:* Because of this new feature, you | ||
23 | must explicitly declare all build-time dependencies for your recipe. | ||
24 | If you do not declare these dependencies, they are not populated into | ||
25 | the sysroot for the recipe. | ||
26 | |||
27 | - *Specify Pre-Installation and Post-Installation Native Tool | ||
28 | Dependencies:* You must specifically specify any special native tool | ||
29 | dependencies of ``pkg_preinst`` and ``pkg_postinst`` scripts by using | ||
30 | the :term:`PACKAGE_WRITE_DEPS` variable. | ||
31 | Specifying these dependencies ensures that these tools are available | ||
32 | if these scripts need to be run on the build host during the | ||
33 | :ref:`ref-tasks-rootfs` task. | ||
34 | |||
35 | As an example, see the ``dbus`` recipe. You will see that this recipe | ||
36 | has a ``pkg_postinst`` that calls ``systemctl`` if "systemd" is in | ||
37 | :term:`DISTRO_FEATURES`. In the example, | ||
38 | ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``, | ||
39 | which is also conditional on "systemd" being in ``DISTRO_FEATURES``. | ||
40 | |||
41 | - Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to | ||
42 | examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine | ||
43 | steps to take. | ||
44 | |||
45 | Functions added to ``SSTATEPOSTINSTFUNCS`` are still called as they | ||
46 | were in previous Yocto Project releases. However, since a separate | ||
47 | sysroot is now being populated for every recipe and if existing | ||
48 | functions being called through ``SSTATEPOSTINSTFUNCS`` are doing | ||
49 | relocation, then you will need to change these to use a | ||
50 | post-installation script that is installed by a function added to | ||
51 | :term:`SYSROOT_PREPROCESS_FUNCS`. | ||
52 | |||
53 | For an example, see the ``pixbufcache`` class in ``meta/classes/`` in | ||
54 | the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`. | ||
55 | |||
56 | .. note:: | ||
57 | |||
58 | The | ||
59 | SSTATEPOSTINSTFUNCS | ||
60 | variable itself is now deprecated in favor of the | ||
61 | do_populate_sysroot[postfuncs] | ||
62 | task. Consequently, if you do still have any function or functions | ||
63 | that need to be called after the sysroot component is created for | ||
64 | a recipe, then you would be well advised to take steps to use a | ||
65 | post installation script as described previously. Taking these | ||
66 | steps prepares your code for when | ||
67 | SSTATEPOSTINSTFUNCS | ||
68 | is removed in a future Yocto Project release. | ||
69 | |||
70 | - *Specify the Sysroot when Using Certain External Scripts:* Because | ||
71 | the shared sysroot is now gone, the scripts | ||
72 | ``oe-find-native-sysroot`` and ``oe-run-native`` have been changed | ||
73 | such that you need to specify which recipe's | ||
74 | :term:`STAGING_DIR_NATIVE` is used. | ||
75 | |||
76 | .. note:: | ||
77 | |||
78 | You can find more information on how recipe-specific sysroots work in | ||
79 | the " | ||
80 | staging.bbclass | ||
81 | " section. | ||
82 | |||
83 | .. _migration-2.3-path-variable: | ||
84 | |||
85 | ``PATH`` Variable | ||
86 | ----------------- | ||
87 | |||
88 | Within the environment used to run build tasks, the environment variable | ||
89 | ``PATH`` is now sanitized such that the normal native binary paths | ||
90 | (``/bin``, ``/sbin``, ``/usr/bin`` and so forth) are removed and a | ||
91 | directory containing symbolic links linking only to the binaries from | ||
92 | the host mentioned in the :term:`HOSTTOOLS` and | ||
93 | :term:`HOSTTOOLS_NONFATAL` variables is added | ||
94 | to ``PATH``. | ||
95 | |||
96 | Consequently, any native binaries provided by the host that you need to | ||
97 | call needs to be in one of these two variables at the configuration | ||
98 | level. | ||
99 | |||
100 | Alternatively, you can add a native recipe (i.e. ``-native``) that | ||
101 | provides the binary to the recipe's :term:`DEPENDS` | ||
102 | value. | ||
103 | |||
104 | .. note:: | ||
105 | |||
106 | PATH | ||
107 | is not sanitized in the same way within | ||
108 | devshell | ||
109 | . If it were, you would have difficulty running host tools for | ||
110 | development and debugging within the shell. | ||
111 | |||
112 | .. _migration-2.3-scripts: | ||
113 | |||
114 | Changes to Scripts | ||
115 | ------------------ | ||
116 | |||
117 | The following changes to scripts took place: | ||
118 | |||
119 | - ``oe-find-native-sysroot``: The usage for the | ||
120 | ``oe-find-native-sysroot`` script has changed to the following: | ||
121 | :: | ||
122 | |||
123 | $ . oe-find-native-sysroot recipe | ||
124 | |||
125 | You must now supply a recipe for recipe | ||
126 | as part of the command. Prior to the Yocto Project &DISTRO; release, it | ||
127 | was not necessary to provide the script with the command. | ||
128 | |||
129 | - ``oe-run-native``: The usage for the ``oe-run-native`` script has | ||
130 | changed to the following: | ||
131 | :: | ||
132 | |||
133 | $ oe-run-native native_recipe tool | ||
134 | |||
135 | You must | ||
136 | supply the name of the native recipe and the tool you want to run as | ||
137 | part of the command. Prior to the Yocto Project DISTRO release, it | ||
138 | was not necessary to provide the native recipe with the command. | ||
139 | |||
140 | - ``cleanup-workdir``: The ``cleanup-workdir`` script has been | ||
141 | removed because the script was found to be deleting files it should | ||
142 | not have, which lead to broken build trees. Rather than trying to | ||
143 | delete portions of :term:`TMPDIR` and getting it wrong, | ||
144 | it is recommended that you delete ``TMPDIR`` and have it restored | ||
145 | from shared state (sstate) on subsequent builds. | ||
146 | |||
147 | - ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as | ||
148 | it is no longer needed with recipe-specific sysroots. | ||
149 | |||
150 | .. _migration-2.3-functions: | ||
151 | |||
152 | Changes to Functions | ||
153 | -------------------- | ||
154 | |||
155 | The previously deprecated ``bb.data.getVar()``, ``bb.data.setVar()``, | ||
156 | and related functions have been removed in favor of ``d.getVar()``, | ||
157 | ``d.setVar()``, and so forth. | ||
158 | |||
159 | You need to fix any references to these old functions. | ||
160 | |||
161 | .. _migration-2.3-bitbake-changes: | ||
162 | |||
163 | BitBake Changes | ||
164 | --------------- | ||
165 | |||
166 | The following changes took place for BitBake: | ||
167 | |||
168 | - *BitBake's Graphical Dependency Explorer UI Replaced:* BitBake's | ||
169 | graphical dependency explorer UI ``depexp`` was replaced by | ||
170 | ``taskexp`` ("Task Explorer"), which provides a graphical way of | ||
171 | exploring the ``task-depends.dot`` file. The data presented by Task | ||
172 | Explorer is much more accurate than the data that was presented by | ||
173 | ``depexp``. Being able to visualize the data is an often requested | ||
174 | feature as standard ``*.dot`` file viewers cannot usual cope with the | ||
175 | size of the ``task-depends.dot`` file. | ||
176 | |||
177 | - *BitBake "-g" Output Changes:* The ``package-depends.dot`` and | ||
178 | ``pn-depends.dot`` files as previously generated using the | ||
179 | ``bitbake -g`` command have been removed. A ``recipe-depends.dot`` | ||
180 | file is now generated as a collapsed version of ``task-depends.dot`` | ||
181 | instead. | ||
182 | |||
183 | The reason for this change is because ``package-depends.dot`` and | ||
184 | ``pn-depends.dot`` largely date back to a time before task-based | ||
185 | execution and do not take into account task-level dependencies | ||
186 | between recipes, which could be misleading. | ||
187 | |||
188 | - *Mirror Variable Splitting Changes:* Mirror variables including | ||
189 | :term:`MIRRORS`, :term:`PREMIRRORS`, | ||
190 | and :term:`SSTATE_MIRRORS` can now separate | ||
191 | values entirely with spaces. Consequently, you no longer need "\\n". | ||
192 | BitBake looks for pairs of values, which simplifies usage. There | ||
193 | should be no change required to existing mirror variable values | ||
194 | themselves. | ||
195 | |||
196 | - *The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an | ||
197 | "rsh" Parameter:* The SVN fetcher now takes an "ssh" parameter | ||
198 | instead of an "rsh" parameter. This new optional parameter is used | ||
199 | when the "protocol" parameter is set to "svn+ssh". You can only use | ||
200 | the new parameter to specify the ``ssh`` program used by SVN. The SVN | ||
201 | fetcher passes the new parameter through the ``SVN_SSH`` environment | ||
202 | variable during the :ref:`ref-tasks-fetch` task. | ||
203 | |||
204 | See the ":ref:`bitbake:svn-fetcher`" | ||
205 | section in the BitBake | ||
206 | User Manual for additional information. | ||
207 | |||
208 | - ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2`` | ||
209 | Removed: Because the mechanism they were part of is no longer | ||
210 | necessary with recipe-specific sysroots, the | ||
211 | ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2`` | ||
212 | variables have been removed. | ||
213 | |||
214 | .. _migration-2.3-absolute-symlinks: | ||
215 | |||
216 | Absolute Symbolic Links | ||
217 | ----------------------- | ||
218 | |||
219 | Absolute symbolic links (symlinks) within staged files are no longer | ||
220 | permitted and now trigger an error. Any explicit creation of symlinks | ||
221 | can use the ``lnr`` script, which is a replacement for ``ln -r``. | ||
222 | |||
223 | If the build scripts in the software that the recipe is building are | ||
224 | creating a number of absolute symlinks that need to be corrected, you | ||
225 | can inherit ``relative_symlinks`` within the recipe to turn those | ||
226 | absolute symlinks into relative symlinks. | ||
227 | |||
228 | .. _migration-2.3-gplv2-and-gplv3-moves: | ||
229 | |||
230 | GPLv2 Versions of GPLv3 Recipes Moved | ||
231 | ------------------------------------- | ||
232 | |||
233 | Older GPLv2 versions of GPLv3 recipes have moved to a separate | ||
234 | ``meta-gplv2`` layer. | ||
235 | |||
236 | If you use :term:`INCOMPATIBLE_LICENSE` to | ||
237 | exclude GPLv3 or set :term:`PREFERRED_VERSION` | ||
238 | to substitute a GPLv2 version of a GPLv3 recipe, then you must add the | ||
239 | ``meta-gplv2`` layer to your configuration. | ||
240 | |||
241 | .. note:: | ||
242 | |||
243 | You can find | ||
244 | meta-gplv2 | ||
245 | layer in the OpenEmbedded layer index at | ||
246 | . | ||
247 | |||
248 | These relocated GPLv2 recipes do not receive the same level of | ||
249 | maintenance as other core recipes. The recipes do not get security fixes | ||
250 | and upstream no longer maintains them. In fact, the upstream community | ||
251 | is actively hostile towards people that use the old versions of the | ||
252 | recipes. Moving these recipes into a separate layer both makes the | ||
253 | different needs of the recipes clearer and clearly identifies the number | ||
254 | of these recipes. | ||
255 | |||
256 | .. note:: | ||
257 | |||
258 | The long-term solution might be to move to BSD-licensed replacements | ||
259 | of the GPLv3 components for those that need to exclude GPLv3-licensed | ||
260 | components from the target system. This solution will be investigated | ||
261 | for future Yocto Project releases. | ||
262 | |||
263 | .. _migration-2.3-package-management-changes: | ||
264 | |||
265 | Package Management Changes | ||
266 | -------------------------- | ||
267 | |||
268 | The following package management changes took place: | ||
269 | |||
270 | - Smart package manager is replaced by DNF package manager. Smart has | ||
271 | become unmaintained upstream, is not ported to Python 3.x. | ||
272 | Consequently, Smart needed to be replaced. DNF is the only feasible | ||
273 | candidate. | ||
274 | |||
275 | The change in functionality is that the on-target runtime package | ||
276 | management from remote package feeds is now done with a different | ||
277 | tool that has a different set of command-line options. If you have | ||
278 | scripts that call the tool directly, or use its API, they need to be | ||
279 | fixed. | ||
280 | |||
281 | For more information, see the `DNF | ||
282 | Documentation <http://dnf.readthedocs.io/en/latest/>`__. | ||
283 | |||
284 | - Rpm 5.x is replaced with Rpm 4.x. This is done for two major reasons: | ||
285 | |||
286 | - DNF is API-incompatible with Rpm 5.x and porting it and | ||
287 | maintaining the port is non-trivial. | ||
288 | |||
289 | - Rpm 5.x itself has limited maintenance upstream, and the Yocto | ||
290 | Project is one of the very few remaining users. | ||
291 | |||
292 | - Berkeley DB 6.x is removed and Berkeley DB 5.x becomes the default: | ||
293 | |||
294 | - Version 6.x of Berkeley DB has largely been rejected by the open | ||
295 | source community due to its AGPLv3 license. As a result, most | ||
296 | mainstream open source projects that require DB are still | ||
297 | developed and tested with DB 5.x. | ||
298 | |||
299 | - In OE-core, the only thing that was requiring DB 6.x was Rpm 5.x. | ||
300 | Thus, no reason exists to continue carrying DB 6.x in OE-core. | ||
301 | |||
302 | - ``createrepo`` is replaced with ``createrepo_c``. | ||
303 | |||
304 | ``createrepo_c`` is the current incarnation of the tool that | ||
305 | generates remote repository metadata. It is written in C as compared | ||
306 | to ``createrepo``, which is written in Python. ``createrepo_c`` is | ||
307 | faster and is maintained. | ||
308 | |||
309 | - Architecture-independent RPM packages are "noarch" instead of "all". | ||
310 | |||
311 | This change was made because too many places in DNF/RPM4 stack | ||
312 | already make that assumption. Only the filenames and the architecture | ||
313 | tag has changed. Nothing else has changed in OE-core system, | ||
314 | particularly in the :ref:`allarch.bbclass <ref-classes-allarch>` | ||
315 | class. | ||
316 | |||
317 | - Signing of remote package feeds using ``PACKAGE_FEED_SIGN`` is not | ||
318 | currently supported. This issue will be fully addressed in a future | ||
319 | Yocto Project release. See `defect | ||
320 | 11209 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209>`__ | ||
321 | for more information on a solution to package feed signing with RPM | ||
322 | in the Yocto Project 2.3 release. | ||
323 | |||
324 | - OPKG now uses the libsolv backend for resolving package dependencies | ||
325 | by default. This is vastly superior to OPKG's internal ad-hoc solver | ||
326 | that was previously used. This change does have a small impact on | ||
327 | disk (around 500 KB) and memory footprint. | ||
328 | |||
329 | .. note:: | ||
330 | |||
331 | For further details on this change, see the | ||
332 | commit message | ||
333 | . | ||
334 | |||
335 | .. _migration-2.3-removed-recipes: | ||
336 | |||
337 | Removed Recipes | ||
338 | --------------- | ||
339 | |||
340 | The following recipes have been removed: | ||
341 | |||
342 | - ``linux-yocto 4.8``: Version 4.8 has been removed. Versions 4.1 | ||
343 | (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present. | ||
344 | |||
345 | - ``python-smartpm``: Functionally replaced by ``dnf``. | ||
346 | |||
347 | - ``createrepo``: Replaced by the ``createrepo-c`` recipe. | ||
348 | |||
349 | - ``rpmresolve``: No longer needed with the move to RPM 4 as RPM | ||
350 | itself is used instead. | ||
351 | |||
352 | - ``gstreamer``: Removed the GStreamer Git version recipes as they | ||
353 | have been stale. ``1.10.``\ x recipes are still present. | ||
354 | |||
355 | - ``alsa-conf-base``: Merged into ``alsa-conf`` since ``libasound`` | ||
356 | depended on both. Essentially, no way existed to install only one of | ||
357 | these. | ||
358 | |||
359 | - ``tremor``: Moved to ``meta-multimedia``. Fixed-integer Vorbis | ||
360 | decoding is not needed by current hardware. Thus, GStreamer's ivorbis | ||
361 | plugin has been disabled by default eliminating the need for the | ||
362 | ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`. | ||
363 | |||
364 | - ``gummiboot``: Replaced by ``systemd-boot``. | ||
365 | |||
366 | .. _migration-2.3-wic-changes: | ||
367 | |||
368 | Wic Changes | ||
369 | ----------- | ||
370 | |||
371 | The following changes have been made to Wic: | ||
372 | |||
373 | .. note:: | ||
374 | |||
375 | For more information on Wic, see the " | ||
376 | Creating Partitioned Images Using Wic | ||
377 | " section in the Yocto Project Development Tasks Manual. | ||
378 | |||
379 | - *Default Output Directory Changed:* Wic's default output directory is | ||
380 | now the current directory by default instead of the unusual | ||
381 | ``/var/tmp/wic``. | ||
382 | |||
383 | The "-o" and "--outdir" options remain unchanged and are used to | ||
384 | specify your preferred output directory if you do not want to use the | ||
385 | default directory. | ||
386 | |||
387 | - *fsimage Plug-in Removed:* The Wic fsimage plugin has been removed as | ||
388 | it duplicates functionality of the rawcopy plugin. | ||
389 | |||
390 | .. _migration-2.3-qa-changes: | ||
391 | |||
392 | QA Changes | ||
393 | ---------- | ||
394 | |||
395 | The following QA checks have changed: | ||
396 | |||
397 | - ``unsafe-references-in-binaries``: The | ||
398 | ``unsafe-references-in-binaries`` QA check, which was disabled by | ||
399 | default, has now been removed. This check was intended to detect | ||
400 | binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have | ||
401 | the case where the user has ``/usr`` on a separate filesystem to | ||
402 | ``/``. | ||
403 | |||
404 | The removed QA check was buggy. Additionally, ``/usr`` residing on a | ||
405 | separate partition from ``/`` is now a rare configuration. | ||
406 | Consequently, ``unsafe-references-in-binaries`` was removed. | ||
407 | |||
408 | - ``file-rdeps``: The ``file-rdeps`` QA check is now an error by | ||
409 | default instead of a warning. Because it is an error instead of a | ||
410 | warning, you need to address missing runtime dependencies. | ||
411 | |||
412 | For additional information, see the | ||
413 | :ref:`insane <ref-classes-insane>` class and the "`Errors and | ||
414 | Warnings <#qa-errors-and-warnings>`__" section. | ||
415 | |||
416 | .. _migration-2.3-miscellaneous-changes: | ||
417 | |||
418 | Miscellaneous Changes | ||
419 | --------------------- | ||
420 | |||
421 | The following miscellaneous changes have occurred: | ||
422 | |||
423 | - In this release, a number of recipes have been changed to ignore the | ||
424 | ``largefile`` :term:`DISTRO_FEATURES` item, | ||
425 | enabling large file support unconditionally. This feature has always | ||
426 | been enabled by default. Disabling the feature has not been widely | ||
427 | tested. | ||
428 | |||
429 | .. note:: | ||
430 | |||
431 | Future releases of the Yocto Project will remove entirely the | ||
432 | ability to disable the | ||
433 | largefile | ||
434 | feature, which would make it unconditionally enabled everywhere. | ||
435 | |||
436 | - If the :term:`DISTRO_VERSION` value contains | ||
437 | the value of the :term:`DATE` variable, which is the | ||
438 | default between Poky releases, the ``DATE`` value is explicitly | ||
439 | excluded from ``/etc/issue`` and ``/etc/issue.net``, which is | ||
440 | displayed at the login prompt, in order to avoid conflicts with | ||
441 | Multilib enabled. Regardless, the ``DATE`` value is inaccurate if the | ||
442 | ``base-files`` recipe is restored from shared state (sstate) rather | ||
443 | than rebuilt. | ||
444 | |||
445 | If you need the build date recorded in ``/etc/issue*`` or anywhere | ||
446 | else in your image, a better method is to define a post-processing | ||
447 | function to do it and have the function called from | ||
448 | :term:`ROOTFS_POSTPROCESS_COMMAND`. | ||
449 | Doing so ensures the value is always up-to-date with the created | ||
450 | image. | ||
451 | |||
452 | - Dropbear's ``init`` script now disables DSA host keys by default. | ||
453 | This change is in line with the systemd service file, which supports | ||
454 | RSA keys only, and with recent versions of OpenSSH, which deprecates | ||
455 | DSA host keys. | ||
456 | |||
457 | - The :ref:`buildhistory <ref-classes-buildhistory>` class now | ||
458 | correctly uses tabs as separators between all columns in | ||
459 | ``installed-package-sizes.txt`` in order to aid import into other | ||
460 | tools. | ||
461 | |||
462 | - The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig" | ||
463 | ``DISTRO_FEATURES`` feature. Distributions that previously set: | ||
464 | :: | ||
465 | |||
466 | USE_LDCONFIG = "0" | ||
467 | |||
468 | should now instead use the following: | ||
469 | |||
470 | :: | ||
471 | |||
472 | DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" | ||
473 | |||
474 | - The default value of | ||
475 | :term:`COPYLEFT_LICENSE_INCLUDE` now | ||
476 | includes all versions of AGPL licenses in addition to GPL and LGPL. | ||
477 | |||
478 | .. note:: | ||
479 | |||
480 | The default list is not intended to be guaranteed as a complete | ||
481 | safe list. You should seek legal advice based on what you are | ||
482 | distributing if you are unsure. | ||
483 | |||
484 | - Kernel module packages are now suffixed with the kernel version in | ||
485 | order to allow module packages from multiple kernel versions to | ||
486 | co-exist on a target system. If you wish to return to the previous | ||
487 | naming scheme that does not include the version suffix, use the | ||
488 | following: | ||
489 | :: | ||
490 | |||
491 | KERNEL_MODULE_PACKAGE_SUFFIX to "" | ||
492 | |||
493 | - Removal of ``libtool`` ``*.la`` files is now enabled by default. The | ||
494 | ``*.la`` files are not actually needed on Linux and relocating them | ||
495 | is an unnecessary burden. | ||
496 | |||
497 | If you need to preserve these ``.la`` files (e.g. in a custom | ||
498 | distribution), you must change | ||
499 | :term:`INHERIT_DISTRO` such that | ||
500 | "remove-libtool" is not included in the value. | ||
501 | |||
502 | - Extensible SDKs built for GCC 5+ now refuse to install on a | ||
503 | distribution where the host GCC version is 4.8 or 4.9. This change | ||
504 | resulted from the fact that the installation is known to fail due to | ||
505 | the way the ``uninative`` shared state (sstate) package is built. See | ||
506 | the :ref:`uninative <ref-classes-uninative>` class for additional | ||
507 | information. | ||
508 | |||
509 | - All native and nativesdk recipes now use a separate | ||
510 | ``DISTRO_FEATURES`` value instead of sharing the value used by | ||
511 | recipes for the target, in order to avoid unnecessary rebuilds. | ||
512 | |||
513 | The ``DISTRO_FEATURES`` for ``native`` recipes is | ||
514 | :term:`DISTRO_FEATURES_NATIVE` added to | ||
515 | an intersection of ``DISTRO_FEATURES`` and | ||
516 | :term:`DISTRO_FEATURES_FILTER_NATIVE`. | ||
517 | |||
518 | For nativesdk recipes, the corresponding variables are | ||
519 | :term:`DISTRO_FEATURES_NATIVESDK` | ||
520 | and | ||
521 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK`. | ||
522 | |||
523 | - The ``FILESDIR`` variable, which was previously deprecated and rarely | ||
524 | used, has now been removed. You should change any recipes that set | ||
525 | ``FILESDIR`` to set :term:`FILESPATH` instead. | ||
526 | |||
527 | - The ``MULTIMACH_HOST_SYS`` variable has been removed as it is no | ||
528 | longer needed with recipe-specific sysroots. | ||
529 | |||
530 | |||
diff --git a/documentation/ref-manual/migration-2.4.rst b/documentation/ref-manual/migration-2.4.rst new file mode 100644 index 0000000000..260b3204b6 --- /dev/null +++ b/documentation/ref-manual/migration-2.4.rst | |||
@@ -0,0 +1,327 @@ | |||
1 | Moving to the Yocto Project 2.4 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.4 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.4-memory-resident-mode: | ||
8 | |||
9 | Memory Resident Mode | ||
10 | -------------------- | ||
11 | |||
12 | A persistent mode is now available in BitBake's default operation, | ||
13 | replacing its previous "memory resident mode" (i.e. | ||
14 | ``oe-init-build-env-memres``). Now you only need to set | ||
15 | :term:`BB_SERVER_TIMEOUT` to a timeout (in | ||
16 | seconds) and BitBake's server stays resident for that amount of time | ||
17 | between invocations. The ``oe-init-build-env-memres`` script has been | ||
18 | removed since a separate environment setup script is no longer needed. | ||
19 | |||
20 | .. _migration-2.4-packaging-changes: | ||
21 | |||
22 | Packaging Changes | ||
23 | ----------------- | ||
24 | |||
25 | This section provides information about packaging changes that have | ||
26 | occurred: | ||
27 | |||
28 | - ``python3`` Changes: | ||
29 | |||
30 | - The main "python3" package now brings in all of the standard | ||
31 | Python 3 distribution rather than a subset. This behavior matches | ||
32 | what is expected based on traditional Linux distributions. If you | ||
33 | wish to install a subset of Python 3, specify ``python-core`` plus | ||
34 | one or more of the individual packages that are still produced. | ||
35 | |||
36 | - ``python3``: The ``bz2.py``, ``lzma.py``, and | ||
37 | ``_compression.py`` scripts have been moved from the | ||
38 | ``python3-misc`` package to the ``python3-compression`` package. | ||
39 | |||
40 | - ``binutils``: The ``libbfd`` library is now packaged in a separate | ||
41 | "libbfd" package. This packaging saves space when certain tools (e.g. | ||
42 | ``perf``) are installed. In such cases, the tools only need | ||
43 | ``libbfd`` rather than all the packages in ``binutils``. | ||
44 | |||
45 | - ``util-linux`` Changes: | ||
46 | |||
47 | - The ``su`` program is now packaged in a separate "util-linux-su" | ||
48 | package, which is only built when "pam" is listed in the | ||
49 | :term:`DISTRO_FEATURES` variable. | ||
50 | ``util-linux`` should not be installed unless it is needed because | ||
51 | ``su`` is normally provided through the shadow file format. The | ||
52 | main ``util-linux`` package has runtime dependencies (i.e. | ||
53 | :term:`RDEPENDS`) on the ``util-linux-su`` package | ||
54 | when "pam" is in ``DISTRO_FEATURES``. | ||
55 | |||
56 | - The ``switch_root`` program is now packaged in a separate | ||
57 | "util-linux-switch-root" package for small initramfs images that | ||
58 | do not need the whole ``util-linux`` package or the busybox | ||
59 | binary, which are both much larger than ``switch_root``. The main | ||
60 | ``util-linux`` package has a recommended runtime dependency (i.e. | ||
61 | :term:`RRECOMMENDS`) on the | ||
62 | ``util-linux-switch-root`` package. | ||
63 | |||
64 | - The ``ionice`` program is now packaged in a separate | ||
65 | "util-linux-ionice" package. The main ``util-linux`` package has a | ||
66 | recommended runtime dependency (i.e. ``RRECOMMENDS``) on the | ||
67 | ``util-linux-ionice`` package. | ||
68 | |||
69 | - ``initscripts``: The ``sushell`` program is now packaged in a | ||
70 | separate "initscripts-sushell" package. This packaging change allows | ||
71 | systems to pull ``sushell`` in when ``selinux`` is enabled. The | ||
72 | change also eliminates needing to pull in the entire ``initscripts`` | ||
73 | package. The main ``initscripts`` package has a runtime dependency | ||
74 | (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in | ||
75 | ``DISTRO_FEATURES``. | ||
76 | |||
77 | - ``glib-2.0``: The ``glib-2.0`` package now has a recommended | ||
78 | runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info`` | ||
79 | package, since large portions of GIO are not useful without the MIME | ||
80 | database. You can remove the dependency by using the | ||
81 | :term:`BAD_RECOMMENDATIONS` variable if | ||
82 | ``shared-mime-info`` is too large and is not required. | ||
83 | |||
84 | - *Go Standard Runtime:* The Go standard runtime has been split out | ||
85 | from the main ``go`` recipe into a separate ``go-runtime`` recipe. | ||
86 | |||
87 | .. _migration-2.4-removed-recipes: | ||
88 | |||
89 | Removed Recipes | ||
90 | --------------- | ||
91 | |||
92 | The following recipes have been removed: | ||
93 | |||
94 | - ``acpitests``: This recipe is not maintained. | ||
95 | |||
96 | - ``autogen-native``: No longer required by Grub, oe-core, or | ||
97 | meta-oe. | ||
98 | |||
99 | - ``bdwgc``: Nothing in OpenEmbedded-Core requires this recipe. It | ||
100 | has moved to meta-oe. | ||
101 | |||
102 | - ``byacc``: This recipe was only needed by rpm 5.x and has moved to | ||
103 | meta-oe. | ||
104 | |||
105 | - ``gcc (5.4)``: The 5.4 series dropped the recipe in favor of 6.3 / | ||
106 | 7.2. | ||
107 | |||
108 | - ``gnome-common``: Deprecated upstream and no longer needed. | ||
109 | |||
110 | - ``go-bootstrap-native``: Go 1.9 does its own bootstrapping so this | ||
111 | recipe has been removed. | ||
112 | |||
113 | - ``guile``: This recipe was only needed by ``autogen-native`` and | ||
114 | ``remake``. The recipe is no longer needed by either of these | ||
115 | programs. | ||
116 | |||
117 | - ``libclass-isa-perl``: This recipe was previously needed for LSB 4, | ||
118 | no longer needed. | ||
119 | |||
120 | - ``libdumpvalue-perl``: This recipe was previously needed for LSB 4, | ||
121 | no longer needed. | ||
122 | |||
123 | - ``libenv-perl``: This recipe was previously needed for LSB 4, no | ||
124 | longer needed. | ||
125 | |||
126 | - ``libfile-checktree-perl``: This recipe was previously needed for | ||
127 | LSB 4, no longer needed. | ||
128 | |||
129 | - ``libi18n-collate-perl``: This recipe was previously needed for LSB | ||
130 | 4, no longer needed. | ||
131 | |||
132 | - ``libiconv``: This recipe was only needed for ``uclibc``, which was | ||
133 | removed in the previous release. ``glibc`` and ``musl`` have their | ||
134 | own implementations. ``meta-mingw`` still needs ``libiconv``, so it | ||
135 | has been moved to ``meta-mingw``. | ||
136 | |||
137 | - ``libpng12``: This recipe was previously needed for LSB. The | ||
138 | current ``libpng`` is 1.6.x. | ||
139 | |||
140 | - ``libpod-plainer-perl``: This recipe was previously needed for LSB | ||
141 | 4, no longer needed. | ||
142 | |||
143 | - ``linux-yocto (4.1)``: This recipe was removed in favor of 4.4, | ||
144 | 4.9, 4.10 and 4.12. | ||
145 | |||
146 | - ``mailx``: This recipe was previously only needed for LSB | ||
147 | compatibility, and upstream is defunct. | ||
148 | |||
149 | - ``mesa (git version only)``: The git version recipe was stale with | ||
150 | respect to the release version. | ||
151 | |||
152 | - ``ofono (git version only)``: The git version recipe was stale with | ||
153 | respect to the release version. | ||
154 | |||
155 | - ``portmap``: This recipe is obsolete and is superseded by | ||
156 | ``rpcbind``. | ||
157 | |||
158 | - ``python3-pygpgme``: This recipe is old and unmaintained. It was | ||
159 | previously required by ``dnf``, which has switched to official | ||
160 | ``gpgme`` Python bindings. | ||
161 | |||
162 | - ``python-async``: This recipe has been removed in favor of the | ||
163 | Python 3 version. | ||
164 | |||
165 | - ``python-gitdb``: This recipe has been removed in favor of the | ||
166 | Python 3 version. | ||
167 | |||
168 | - ``python-git``: This recipe was removed in favor of the Python 3 | ||
169 | version. | ||
170 | |||
171 | - ``python-mako``: This recipe was removed in favor of the Python 3 | ||
172 | version. | ||
173 | |||
174 | - ``python-pexpect``: This recipe was removed in favor of the Python | ||
175 | 3 version. | ||
176 | |||
177 | - ``python-ptyprocess``: This recipe was removed in favor of Python | ||
178 | the 3 version. | ||
179 | |||
180 | - ``python-pycurl``: Nothing is using this recipe in | ||
181 | OpenEmbedded-Core (i.e. ``meta-oe``). | ||
182 | |||
183 | - ``python-six``: This recipe was removed in favor of the Python 3 | ||
184 | version. | ||
185 | |||
186 | - ``python-smmap``: This recipe was removed in favor of the Python 3 | ||
187 | version. | ||
188 | |||
189 | - ``remake``: Using ``remake`` as the provider of ``virtual/make`` is | ||
190 | broken. Consequently, this recipe is not needed in OpenEmbedded-Core. | ||
191 | |||
192 | .. _migration-2.4-kernel-device-tree-move: | ||
193 | |||
194 | Kernel Device Tree Move | ||
195 | ----------------------- | ||
196 | |||
197 | Kernel Device Tree support is now easier to enable in a kernel recipe. | ||
198 | The Device Tree code has moved to a | ||
199 | :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class. | ||
200 | Functionality is automatically enabled for any recipe that inherits the | ||
201 | :ref:`kernel <ref-classes-kernel>` class and sets the | ||
202 | :term:`KERNEL_DEVICETREE` variable. The | ||
203 | previous mechanism for doing this, | ||
204 | ``meta/recipes-kernel/linux/linux-dtb.inc``, is still available to avoid | ||
205 | breakage, but triggers a deprecation warning. Future releases of the | ||
206 | Yocto Project will remove ``meta/recipes-kernel/linux/linux-dtb.inc``. | ||
207 | It is advisable to remove any ``require`` statements that request | ||
208 | ``meta/recipes-kernel/linux/linux-dtb.inc`` from any custom kernel | ||
209 | recipes you might have. This will avoid breakage in post 2.4 releases. | ||
210 | |||
211 | .. _migration-2.4-package-qa-changes: | ||
212 | |||
213 | Package QA Changes | ||
214 | ------------------ | ||
215 | |||
216 | The following package QA changes took place: | ||
217 | |||
218 | - The "unsafe-references-in-scripts" QA check has been removed. | ||
219 | |||
220 | - If you refer to ``${COREBASE}/LICENSE`` within | ||
221 | :term:`LIC_FILES_CHKSUM` you receive a | ||
222 | warning because this file is a description of the license for | ||
223 | OE-Core. Use ``${COMMON_LICENSE_DIR}/MIT`` if your recipe is | ||
224 | MIT-licensed and you cannot use the preferred method of referring to | ||
225 | a file within the source tree. | ||
226 | |||
227 | .. _migration-2.4-readme-changes: | ||
228 | |||
229 | ``README`` File Changes | ||
230 | ----------------------- | ||
231 | |||
232 | The following are changes to ``README`` files: | ||
233 | |||
234 | - The main Poky ``README`` file has been moved to the ``meta-poky`` | ||
235 | layer and has been renamed ``README.poky``. A symlink has been | ||
236 | created so that references to the old location work. | ||
237 | |||
238 | - The ``README.hardware`` file has been moved to ``meta-yocto-bsp``. A | ||
239 | symlink has been created so that references to the old location work. | ||
240 | |||
241 | - A ``README.qemu`` file has been created with coverage of the | ||
242 | ``qemu*`` machines. | ||
243 | |||
244 | .. _migration-2.4-miscellaneous-changes: | ||
245 | |||
246 | Miscellaneous Changes | ||
247 | --------------------- | ||
248 | |||
249 | The following are additional changes: | ||
250 | |||
251 | - The ``ROOTFS_PKGMANAGE_BOOTSTRAP`` variable and any references to it | ||
252 | have been removed. You should remove this variable from any custom | ||
253 | recipes. | ||
254 | |||
255 | - The ``meta-yocto`` directory has been removed. | ||
256 | |||
257 | .. note:: | ||
258 | |||
259 | In the Yocto Project 2.1 release | ||
260 | meta-yocto | ||
261 | was renamed to | ||
262 | meta-poky | ||
263 | and the | ||
264 | meta-yocto | ||
265 | subdirectory remained to avoid breaking existing configurations. | ||
266 | |||
267 | - The ``maintainers.inc`` file, which tracks maintainers by listing a | ||
268 | primary person responsible for each recipe in OE-Core, has been moved | ||
269 | from ``meta-poky`` to OE-Core (i.e. from | ||
270 | ``meta-poky/conf/distro/include`` to ``meta/conf/distro/include``). | ||
271 | |||
272 | - The :ref:`buildhistory <ref-classes-buildhistory>` class now makes | ||
273 | a single commit per build rather than one commit per subdirectory in | ||
274 | the repository. This behavior assumes the commits are enabled with | ||
275 | :term:`BUILDHISTORY_COMMIT` = "1", which | ||
276 | is typical. Previously, the ``buildhistory`` class made one commit | ||
277 | per subdirectory in the repository in order to make it easier to see | ||
278 | the changes for a particular subdirectory. To view a particular | ||
279 | change, specify that subdirectory as the last parameter on the | ||
280 | ``git show`` or ``git diff`` commands. | ||
281 | |||
282 | - The ``x86-base.inc`` file, which is included by all x86-based machine | ||
283 | configurations, now sets :term:`IMAGE_FSTYPES` | ||
284 | using ``?=`` to "live" rather than appending with ``+=``. This change | ||
285 | makes the default easier to override. | ||
286 | |||
287 | - BitBake fires multiple "BuildStarted" events when multiconfig is | ||
288 | enabled (one per configuration). For more information, see the | ||
289 | ":ref:`Events <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:events>`" section in the BitBake User | ||
290 | Manual. | ||
291 | |||
292 | - By default, the ``security_flags.inc`` file sets a | ||
293 | :term:`GCCPIE` variable with an option to enable | ||
294 | Position Independent Executables (PIE) within ``gcc``. Enabling PIE | ||
295 | in the GNU C Compiler (GCC), makes Return Oriented Programming (ROP) | ||
296 | attacks much more difficult to execute. | ||
297 | |||
298 | - OE-Core now provides a ``bitbake-layers`` plugin that implements a | ||
299 | "create-layer" subcommand. The implementation of this subcommand has | ||
300 | resulted in the ``yocto-layer`` script being deprecated and will | ||
301 | likely be removed in the next Yocto Project release. | ||
302 | |||
303 | - The ``vmdk``, ``vdi``, and ``qcow2`` image file types are now used in | ||
304 | conjunction with the "wic" image type through ``CONVERSION_CMD``. | ||
305 | Consequently, the equivalent image types are now ``wic.vmdk``, | ||
306 | ``wic.vdi``, and ``wic.qcow2``, respectively. | ||
307 | |||
308 | - ``do_image_<type>[depends]`` has replaced ``IMAGE_DEPENDS_<type>``. | ||
309 | If you have your own classes that implement custom image types, then | ||
310 | you need to update them. | ||
311 | |||
312 | - OpenSSL 1.1 has been introduced. However, the default is still 1.0.x | ||
313 | through the :term:`PREFERRED_VERSION` | ||
314 | variable. This preference is set is due to the remaining | ||
315 | compatibility issues with other software. The | ||
316 | :term:`PROVIDES` variable in the openssl 1.0 recipe | ||
317 | now includes "openssl10" as a marker that can be used in | ||
318 | :term:`DEPENDS` within recipes that build software | ||
319 | that still depend on OpenSSL 1.0. | ||
320 | |||
321 | - To ensure consistent behavior, BitBake's "-r" and "-R" options (i.e. | ||
322 | prefile and postfile), which are used to read or post-read additional | ||
323 | configuration files from the command line, now only affect the | ||
324 | current BitBake command. Before these BitBake changes, these options | ||
325 | would "stick" for future executions. | ||
326 | |||
327 | |||
diff --git a/documentation/ref-manual/migration-2.5.rst b/documentation/ref-manual/migration-2.5.rst new file mode 100644 index 0000000000..a2adc17757 --- /dev/null +++ b/documentation/ref-manual/migration-2.5.rst | |||
@@ -0,0 +1,310 @@ | |||
1 | Moving to the Yocto Project 2.5 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.5 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.5-packaging-changes: | ||
8 | |||
9 | Packaging Changes | ||
10 | ----------------- | ||
11 | |||
12 | This section provides information about packaging changes that have | ||
13 | occurred: | ||
14 | |||
15 | - ``bind-libs``: The libraries packaged by the bind recipe are in a | ||
16 | separate ``bind-libs`` package. | ||
17 | |||
18 | - ``libfm-gtk``: The ``libfm`` GTK+ bindings are split into a | ||
19 | separate ``libfm-gtk`` package. | ||
20 | |||
21 | - ``flex-libfl``: The flex recipe splits out libfl into a separate | ||
22 | ``flex-libfl`` package to avoid too many dependencies being pulled in | ||
23 | where only the library is needed. | ||
24 | |||
25 | - ``grub-efi``: The ``grub-efi`` configuration is split into a | ||
26 | separate ``grub-bootconf`` recipe. However, the dependency | ||
27 | relationship from ``grub-efi`` is through a virtual/grub-bootconf | ||
28 | provider making it possible to have your own recipe provide the | ||
29 | dependency. Alternatively, you can use a BitBake append file to bring | ||
30 | the configuration back into the ``grub-efi`` recipe. | ||
31 | |||
32 | - *armv7a Legacy Package Feed Support:* Legacy support is removed for | ||
33 | transitioning from ``armv7a`` to ``armv7a-vfp-neon`` in package | ||
34 | feeds, which was previously enabled by setting | ||
35 | ``PKGARCHCOMPAT_ARMV7A``. This transition occurred in 2011 and active | ||
36 | package feeds should by now be updated to the new naming. | ||
37 | |||
38 | .. _migration-2.5-removed-recipes: | ||
39 | |||
40 | Removed Recipes | ||
41 | --------------- | ||
42 | |||
43 | The following recipes have been removed: | ||
44 | |||
45 | - ``gcc``: The version 6.4 recipes are replaced by 7.x. | ||
46 | |||
47 | - ``gst-player``: Renamed to ``gst-examples`` as per upstream. | ||
48 | |||
49 | - ``hostap-utils``: This software package is obsolete. | ||
50 | |||
51 | - ``latencytop``: This recipe is no longer maintained upstream. The | ||
52 | last release was in 2009. | ||
53 | |||
54 | - ``libpfm4``: The only file that requires this recipe is | ||
55 | ``oprofile``, which has been removed. | ||
56 | |||
57 | - ``linux-yocto``: The version 4.4, 4.9, and 4.10 recipes have been | ||
58 | removed. Versions 4.12, 4.14, and 4.15 remain. | ||
59 | |||
60 | - ``man``: This recipe has been replaced by modern ``man-db`` | ||
61 | |||
62 | - ``mkelfimage``: This tool has been removed in the upstream coreboot | ||
63 | project, and is no longer needed with the removal of the ELF image | ||
64 | type. | ||
65 | |||
66 | - ``nativesdk-postinst-intercept``: This recipe is not maintained. | ||
67 | |||
68 | - ``neon``: This software package is no longer maintained upstream | ||
69 | and is no longer needed by anything in OpenEmbedded-Core. | ||
70 | |||
71 | - ``oprofile``: The functionality of this recipe is replaced by | ||
72 | ``perf`` and keeping compatibility on an ongoing basis with ``musl`` | ||
73 | is difficult. | ||
74 | |||
75 | - ``pax``: This software package is obsolete. | ||
76 | |||
77 | - ``stat``: This software package is not maintained upstream. | ||
78 | ``coreutils`` provides a modern stat binary. | ||
79 | |||
80 | - ``zisofs-tools-native``: This recipe is no longer needed because | ||
81 | the compressed ISO image feature has been removed. | ||
82 | |||
83 | .. _migration-2.5-scripts-and-tools-changes: | ||
84 | |||
85 | Scripts and Tools Changes | ||
86 | ------------------------- | ||
87 | |||
88 | The following are changes to scripts and tools: | ||
89 | |||
90 | - ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``: The | ||
91 | ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts | ||
92 | previously shipped with poky but not in OpenEmbedded-Core have been | ||
93 | removed. These scripts are not maintained and are outdated. In many | ||
94 | cases, they are also limited in scope. The | ||
95 | ``bitbake-layers create-layer`` command is a direct replacement for | ||
96 | ``yocto-layer``. See the documentation to create a BSP or kernel | ||
97 | recipe in the ":ref:`bsp-guide/bsp:bsp kernel recipe example`" section. | ||
98 | |||
99 | - ``devtool finish``: ``devtool finish`` now exits with an error if | ||
100 | there are uncommitted changes or a rebase/am in progress in the | ||
101 | recipe's source repository. If this error occurs, there might be | ||
102 | uncommitted changes that will not be included in updates to the | ||
103 | patches applied by the recipe. A -f/--force option is provided for | ||
104 | situations that the uncommitted changes are inconsequential and you | ||
105 | want to proceed regardless. | ||
106 | |||
107 | - ``scripts/oe-setup-rpmrepo`` script: The functionality of | ||
108 | ``scripts/oe-setup-rpmrepo`` is replaced by | ||
109 | ``bitbake package-index``. | ||
110 | |||
111 | - ``scripts/test-dependencies.sh`` script: The script is largely made | ||
112 | obsolete by the recipe-specific sysroots functionality introduced in | ||
113 | the previous release. | ||
114 | |||
115 | .. _migration-2.5-bitbake-changes: | ||
116 | |||
117 | BitBake Changes | ||
118 | --------------- | ||
119 | |||
120 | The following are BitBake changes: | ||
121 | |||
122 | - The ``--runall`` option has changed. There are two different | ||
123 | behaviors people might want: | ||
124 | |||
125 | - *Behavior A:* For a given target (or set of targets) look through | ||
126 | the task graph and run task X only if it is present and will be | ||
127 | built. | ||
128 | |||
129 | - *Behavior B:* For a given target (or set of targets) look through | ||
130 | the task graph and run task X if any recipe in the taskgraph has | ||
131 | such a target, even if it is not in the original task graph. | ||
132 | |||
133 | The ``--runall`` option now performs "Behavior B". Previously | ||
134 | ``--runall`` behaved like "Behavior A". A ``--runonly`` option has | ||
135 | been added to retain the ability to perform "Behavior A". | ||
136 | |||
137 | - Several explicit "run this task for all recipes in the dependency | ||
138 | tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``, | ||
139 | and the ``*all`` tasks provided by the ``distrodata`` and | ||
140 | ``archiver`` classes). There is a BitBake option to complete this for | ||
141 | any arbitrary task. For example: | ||
142 | :: | ||
143 | |||
144 | bitbake <target> -c fetchall | ||
145 | |||
146 | should now be replaced with: | ||
147 | :: | ||
148 | |||
149 | bitbake <target> --runall=fetch | ||
150 | |||
151 | .. _migration-2.5-python-and-python3-changes: | ||
152 | |||
153 | Python and Python 3 Changes | ||
154 | --------------------------- | ||
155 | |||
156 | The following are auto-packaging changes to Python and Python 3: | ||
157 | |||
158 | The script-managed ``python-*-manifest.inc`` files that were previously | ||
159 | used to generate Python and Python 3 packages have been replaced with a | ||
160 | JSON-based file that is easier to read and maintain. A new task is | ||
161 | available for maintainers of the Python recipes to update the JSON file | ||
162 | when upgrading to new Python versions. You can now edit the file | ||
163 | directly instead of having to edit a script and run it to update the | ||
164 | file. | ||
165 | |||
166 | One particular change to note is that the Python recipes no longer have | ||
167 | build-time provides for their packages. This assumes ``python-foo`` is | ||
168 | one of the packages provided by the Python recipe. You can no longer run | ||
169 | ``bitbake python-foo`` or have a | ||
170 | :term:`DEPENDS` on ``python-foo``, | ||
171 | but doing either of the following causes the package to work as | ||
172 | expected: :: | ||
173 | |||
174 | IMAGE_INSTALL_append = " python-foo" | ||
175 | |||
176 | or :: | ||
177 | |||
178 | RDEPENDS_${PN} = "python-foo" | ||
179 | |||
180 | The earlier build-time provides behavior was a quirk of the | ||
181 | way the Python manifest file was created. For more information on this | ||
182 | change please see `this | ||
183 | commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`__. | ||
184 | |||
185 | .. _migration-2.5-miscellaneous-changes: | ||
186 | |||
187 | Miscellaneous Changes | ||
188 | --------------------- | ||
189 | |||
190 | The following are additional changes: | ||
191 | |||
192 | - The ``kernel`` class supports building packages for multiple kernels. | ||
193 | If your kernel recipe or ``.bbappend`` file mentions packaging at | ||
194 | all, you should replace references to the kernel in package names | ||
195 | with ``${KERNEL_PACKAGE_NAME}``. For example, if you disable | ||
196 | automatic installation of the kernel image using | ||
197 | ``RDEPENDS_kernel-base = ""`` you can avoid warnings using | ||
198 | ``RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""`` instead. | ||
199 | |||
200 | - The ``buildhistory`` class commits changes to the repository by | ||
201 | default so you no longer need to set ``BUILDHISTORY_COMMIT = "1"``. | ||
202 | If you want to disable commits you need to set | ||
203 | ``BUILDHISTORY_COMMIT = "0"`` in your configuration. | ||
204 | |||
205 | - The ``beaglebone`` reference machine has been renamed to | ||
206 | ``beaglebone-yocto``. The ``beaglebone-yocto`` BSP is a reference | ||
207 | implementation using only mainline components available in | ||
208 | OpenEmbedded-Core and ``meta-yocto-bsp``, whereas Texas Instruments | ||
209 | maintains a full-featured BSP in the ``meta-ti`` layer. This rename | ||
210 | avoids the previous name clash that existed between the two BSPs. | ||
211 | |||
212 | - The ``update-alternatives`` class no longer works with SysV ``init`` | ||
213 | scripts because this usage has been problematic. Also, the | ||
214 | ``sysklogd`` recipe no longer uses ``update-alternatives`` because it | ||
215 | is incompatible with other implementations. | ||
216 | |||
217 | - By default, the :ref:`cmake <ref-classes-cmake>` class uses | ||
218 | ``ninja`` instead of ``make`` for building. This improves build | ||
219 | performance. If a recipe is broken with ``ninja``, then the recipe | ||
220 | can set ``OECMAKE_GENERATOR = "Unix Makefiles"`` to change back to | ||
221 | ``make``. | ||
222 | |||
223 | - The previously deprecated ``base_*`` functions have been removed in | ||
224 | favor of their replacements in ``meta/lib/oe`` and | ||
225 | ``bitbake/lib/bb``. These are typically used from recipes and | ||
226 | classes. Any references to the old functions must be updated. The | ||
227 | following table shows the removed functions and their replacements: | ||
228 | |||
229 | +------------------------------+----------------------------------------------------------+ | ||
230 | | *Removed* | *Replacement* | | ||
231 | +==============================+==========================================================+ | ||
232 | | base_path_join() | oe.path.join() | | ||
233 | +------------------------------+----------------------------------------------------------+ | ||
234 | | base_path_relative() | oe.path.relative() | | ||
235 | +------------------------------+----------------------------------------------------------+ | ||
236 | | base_path_out() | oe.path.format_display() | | ||
237 | +------------------------------+----------------------------------------------------------+ | ||
238 | | base_read_file() | oe.utils.read_file() | | ||
239 | +------------------------------+----------------------------------------------------------+ | ||
240 | | base_ifelse() | oe.utils.ifelse() | | ||
241 | +------------------------------+----------------------------------------------------------+ | ||
242 | | base_conditional() | oe.utils.conditional() | | ||
243 | +------------------------------+----------------------------------------------------------+ | ||
244 | | base_less_or_equal() | oe.utils.less_or_equal() | | ||
245 | +------------------------------+----------------------------------------------------------+ | ||
246 | | base_version_less_or_equal() | oe.utils.version_less_or_equal() | | ||
247 | +------------------------------+----------------------------------------------------------+ | ||
248 | | base_contains() | bb.utils.contains() | | ||
249 | +------------------------------+----------------------------------------------------------+ | ||
250 | | base_both_contain() | oe.utils.both_contain() | | ||
251 | +------------------------------+----------------------------------------------------------+ | ||
252 | | base_prune_suffix() | oe.utils.prune_suffix() | | ||
253 | +------------------------------+----------------------------------------------------------+ | ||
254 | | oe_filter() | oe.utils.str_filter() | | ||
255 | +------------------------------+----------------------------------------------------------+ | ||
256 | | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) | | ||
257 | +------------------------------+----------------------------------------------------------+ | ||
258 | |||
259 | - Using ``exit 1`` to explicitly defer a postinstall script until first | ||
260 | boot is now deprecated since it is not an obvious mechanism and can | ||
261 | mask actual errors. If you want to explicitly defer a postinstall to | ||
262 | first boot on the target rather than at ``rootfs`` creation time, use | ||
263 | ``pkg_postinst_ontarget()`` or call | ||
264 | ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``. | ||
265 | Any failure of a ``pkg_postinst()`` script (including ``exit 1``) | ||
266 | will trigger a warning during ``do_rootfs``. | ||
267 | |||
268 | For more information, see the | ||
269 | ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`" | ||
270 | section in the Yocto Project Development Tasks Manual. | ||
271 | |||
272 | - The ``elf`` image type has been removed. This image type was removed | ||
273 | because the ``mkelfimage`` tool that was required to create it is no | ||
274 | longer provided by coreboot upstream and required updating every time | ||
275 | ``binutils`` updated. | ||
276 | |||
277 | - Support for .iso image compression (previously enabled through | ||
278 | ``COMPRESSISO = "1"``) has been removed. The userspace tools | ||
279 | (``zisofs-tools``) are unmaintained and ``squashfs`` provides better | ||
280 | performance and compression. In order to build a live image with | ||
281 | squashfs+lz4 compression enabled you should now set | ||
282 | ``LIVE_ROOTFS_TYPE = "squashfs-lz4"`` and ensure that ``live`` is in | ||
283 | ``IMAGE_FSTYPES``. | ||
284 | |||
285 | - Recipes with an unconditional dependency on ``libpam`` are only | ||
286 | buildable with ``pam`` in ``DISTRO_FEATURES``. If the dependency is | ||
287 | truly optional then it is recommended that the dependency be | ||
288 | conditional upon ``pam`` being in ``DISTRO_FEATURES``. | ||
289 | |||
290 | - For EFI-based machines, the bootloader (``grub-efi`` by default) is | ||
291 | installed into the image at /boot. Wic can be used to split the | ||
292 | bootloader into separate boot and rootfs partitions if necessary. | ||
293 | |||
294 | - Patches whose context does not match exactly (i.e. where patch | ||
295 | reports "fuzz" when applying) will generate a warning. For an example | ||
296 | of this see `this | ||
297 | commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57>`__. | ||
298 | |||
299 | - Layers are expected to set ``LAYERSERIES_COMPAT_layername`` to match | ||
300 | the version(s) of OpenEmbedded-Core they are compatible with. This is | ||
301 | specified as codenames using spaces to separate multiple values (e.g. | ||
302 | "rocko sumo"). If a layer does not set | ||
303 | ``LAYERSERIES_COMPAT_layername``, a warning will is shown. If a layer | ||
304 | sets a value that does not include the current version ("sumo" for | ||
305 | the 2.5 release), then an error will be produced. | ||
306 | |||
307 | - The ``TZ`` environment variable is set to "UTC" within the build | ||
308 | environment in order to fix reproducibility problems in some recipes. | ||
309 | |||
310 | |||
diff --git a/documentation/ref-manual/migration-2.6.rst b/documentation/ref-manual/migration-2.6.rst new file mode 100644 index 0000000000..f16aaaa975 --- /dev/null +++ b/documentation/ref-manual/migration-2.6.rst | |||
@@ -0,0 +1,476 @@ | |||
1 | Moving to the Yocto Project 2.6 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.6 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.6-gcc-changes: | ||
8 | |||
9 | GCC 8.2 is Now Used by Default | ||
10 | ------------------------------ | ||
11 | |||
12 | The GNU Compiler Collection version 8.2 is now used by default for | ||
13 | compilation. For more information on what has changed in the GCC 8.x | ||
14 | release, see https://gcc.gnu.org/gcc-8/changes.html. | ||
15 | |||
16 | If you still need to compile with version 7.x, GCC 7.3 is also provided. | ||
17 | You can select this version by setting the and can be selected by | ||
18 | setting the :term:`GCCVERSION` variable to "7.%" in | ||
19 | your configuration. | ||
20 | |||
21 | .. _migration-2.6-removed-recipes: | ||
22 | |||
23 | Removed Recipes | ||
24 | --------------- | ||
25 | |||
26 | The following recipes have been removed: | ||
27 | |||
28 | - *beecrypt*: No longer needed since moving to RPM 4. | ||
29 | - *bigreqsproto*: Replaced by ``xorgproto``. | ||
30 | - *calibrateproto*: Removed in favor of ``xinput``. | ||
31 | - *compositeproto*: Replaced by ``xorgproto``. | ||
32 | - *damageproto*: Replaced by ``xorgproto``. | ||
33 | - *dmxproto*: Replaced by ``xorgproto``. | ||
34 | - *dri2proto*: Replaced by ``xorgproto``. | ||
35 | - *dri3proto*: Replaced by ``xorgproto``. | ||
36 | - *eee-acpi-scripts*: Became obsolete. | ||
37 | - *fixesproto*: Replaced by ``xorgproto``. | ||
38 | - *fontsproto*: Replaced by ``xorgproto``. | ||
39 | - *fstests*: Became obsolete. | ||
40 | - *gccmakedep*: No longer used. | ||
41 | - *glproto*: Replaced by ``xorgproto``. | ||
42 | - *gnome-desktop3*: No longer needed. This recipe has moved to ``meta-oe``. | ||
43 | - *icon-naming-utils*: No longer used since the Sato theme was removed in 2016. | ||
44 | - *inputproto*: Replaced by ``xorgproto``. | ||
45 | - *kbproto*: Replaced by ``xorgproto``. | ||
46 | - *libusb-compat*: Became obsolete. | ||
47 | - *libuser*: Became obsolete. | ||
48 | - *libnfsidmap*: No longer an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is now integrated. | ||
49 | - *libxcalibrate*: No longer needed with ``xinput`` | ||
50 | - *mktemp*: Became obsolete. The ``mktemp`` command is provided by both ``busybox`` and ``coreutils``. | ||
51 | - *ossp-uuid*: Is not being maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``. | ||
52 | - *pax-utils*: No longer needed. Previous QA tests that did use this recipe are now done at build time. | ||
53 | - *pcmciautils*: Became obsolete. | ||
54 | - *pixz*: No longer needed. ``xz`` now supports multi-threaded compression. | ||
55 | - *presentproto*: Replaced by ``xorgproto``. | ||
56 | - *randrproto*: Replaced by ``xorgproto``. | ||
57 | - *recordproto*: Replaced by ``xorgproto``. | ||
58 | - *renderproto*: Replaced by ``xorgproto``. | ||
59 | - *resourceproto*: Replaced by ``xorgproto``. | ||
60 | - *scrnsaverproto*: Replaced by ``xorgproto``. | ||
61 | - *trace-cmd*: Became obsolete. ``perf`` replaced this recipe's functionally. | ||
62 | - *videoproto*: Replaced by ``xorgproto``. | ||
63 | - *wireless-tools*: Became obsolete. Superseded by ``iw``. | ||
64 | - *xcmiscproto*: Replaced by ``xorgproto``. | ||
65 | - *xextproto*: Replaced by ``xorgproto``. | ||
66 | - *xf86dgaproto*: Replaced by ``xorgproto``. | ||
67 | - *xf86driproto*: Replaced by ``xorgproto``. | ||
68 | - *xf86miscproto*: Replaced by ``xorgproto``. | ||
69 | - *xf86-video-omapfb*: Became obsolete. Use kernel modesetting driver instead. | ||
70 | - *xf86-video-omap*: Became obsolete. Use kernel modesetting driver instead. | ||
71 | - *xf86vidmodeproto*: Replaced by ``xorgproto``. | ||
72 | - *xineramaproto*: Replaced by ``xorgproto``. | ||
73 | - *xproto*: Replaced by ``xorgproto``. | ||
74 | - *yasm*: No longer needed since previous usages are now satisfied by ``nasm``. | ||
75 | |||
76 | .. _migration-2.6-packaging-changes: | ||
77 | |||
78 | Packaging Changes | ||
79 | ----------------- | ||
80 | |||
81 | The following packaging changes have been made: | ||
82 | |||
83 | - *cmake*: ``cmake.m4`` and ``toolchain`` files have been moved to | ||
84 | the main package. | ||
85 | |||
86 | - *iptables*: The ``iptables`` modules have been split into | ||
87 | separate packages. | ||
88 | |||
89 | - *alsa-lib*: ``libasound`` is now in the main ``alsa-lib`` package | ||
90 | instead of ``libasound``. | ||
91 | |||
92 | - *glibc*: ``libnss-db`` is now in its own package along with a | ||
93 | ``/var/db/makedbs.sh`` script to update databases. | ||
94 | |||
95 | - *python and python3*: The main package has been removed from | ||
96 | the recipe. You must install specific packages or ``python-modules`` | ||
97 | / ``python3-modules`` for everything. | ||
98 | |||
99 | - *systemtap*: Moved ``systemtap-exporter`` into its own package. | ||
100 | |||
101 | .. _migration-2.6-xorg-protocol-dependencies: | ||
102 | |||
103 | XOrg Protocol dependencies | ||
104 | -------------------------- | ||
105 | |||
106 | The ``*proto`` upstream repositories have been combined into one | ||
107 | "xorgproto" repository. Thus, the corresponding recipes have also been | ||
108 | combined into a single ``xorgproto`` recipe. Any recipes that depend | ||
109 | upon the older ``*proto`` recipes need to be changed to depend on the | ||
110 | newer ``xorgproto`` recipe instead. | ||
111 | |||
112 | For names of recipes removed because of this repository change, see the | ||
113 | `Removed Recipes <#migration-2.6-removed-recipes>`__ section. | ||
114 | |||
115 | .. _migration-2.6-distutils-distutils3-fetching-dependencies: | ||
116 | |||
117 | ``distutils`` and ``distutils3`` Now Prevent Fetching Dependencies During the ``do_configure`` Task | ||
118 | --------------------------------------------------------------------------------------------------- | ||
119 | |||
120 | Previously, it was possible for Python recipes that inherited the | ||
121 | :ref:`distutils <ref-classes-distutils>` and | ||
122 | :ref:`distutils3 <ref-classes-distutils3>` classes to fetch code | ||
123 | during the :ref:`ref-tasks-configure` task to satisfy | ||
124 | dependencies mentioned in ``setup.py`` if those dependencies were not | ||
125 | provided in the sysroot (i.e. recipes providing the dependencies were | ||
126 | missing from :term:`DEPENDS`). | ||
127 | |||
128 | .. note:: | ||
129 | |||
130 | This change affects classes beyond just the two mentioned (i.e. | ||
131 | distutils | ||
132 | and | ||
133 | distutils3 | ||
134 | ). Any recipe that inherits | ||
135 | distutils\* | ||
136 | classes are affected. For example, the | ||
137 | setuptools | ||
138 | and | ||
139 | setuptools3 | ||
140 | recipes are affected since they inherit the | ||
141 | distutils\* | ||
142 | classes. | ||
143 | |||
144 | Fetching these types of dependencies that are not provided in the | ||
145 | sysroot negatively affects the ability to reproduce builds. This type of | ||
146 | fetching is now explicitly disabled. Consequently, any missing | ||
147 | dependencies in Python recipes that use these classes now result in an | ||
148 | error during the ``do_configure`` task. | ||
149 | |||
150 | .. _migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported: | ||
151 | |||
152 | ``linux-yocto`` Configuration Audit Issues Now Correctly Reported | ||
153 | ----------------------------------------------------------------- | ||
154 | |||
155 | Due to a bug, the kernel configuration audit functionality was not | ||
156 | writing out any resulting warnings during the build. This issue is now | ||
157 | corrected. You might notice these warnings now if you have a custom | ||
158 | kernel configuration with a ``linux-yocto`` style kernel recipe. | ||
159 | |||
160 | .. _migration-2.6-image-kernel-artifact-naming-changes: | ||
161 | |||
162 | Image/Kernel Artifact Naming Changes | ||
163 | ------------------------------------ | ||
164 | |||
165 | The following changes have been made: | ||
166 | |||
167 | - Name variables (e.g. :term:`IMAGE_NAME`) use a new | ||
168 | ``IMAGE_VERSION_SUFFIX`` variable instead of | ||
169 | :term:`DATETIME`. Using ``IMAGE_VERSION_SUFFIX`` | ||
170 | allows easier and more direct changes. | ||
171 | |||
172 | The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf`` | ||
173 | configuration file as follows: | ||
174 | :: | ||
175 | |||
176 | IMAGE_VERSION_SUFFIX = "-${DATETIME}" | ||
177 | |||
178 | - Several variables have changed names for consistency: | ||
179 | :: | ||
180 | |||
181 | Old Variable Name New Variable Name | ||
182 | ======================================================== | ||
183 | KERNEL_IMAGE_BASE_NAME :term:`KERNEL_IMAGE_NAME` | ||
184 | KERNEL_IMAGE_SYMLINK_NAME :term:`KERNEL_IMAGE_LINK_NAME` | ||
185 | MODULE_TARBALL_BASE_NAME :term:`MODULE_TARBALL_NAME` | ||
186 | MODULE_TARBALL_SYMLINK_NAME :term:`MODULE_TARBALL_LINK_NAME` | ||
187 | INITRAMFS_BASE_NAME :term:`INITRAMFS_NAME` | ||
188 | |||
189 | - The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module | ||
190 | tarball name is now controlled directly with the | ||
191 | :term:`MODULE_TARBALL_NAME` variable. | ||
192 | |||
193 | - The :term:`KERNEL_DTB_NAME` and | ||
194 | :term:`KERNEL_DTB_LINK_NAME` variables | ||
195 | have been introduced to control kernel Device Tree Binary (DTB) | ||
196 | artifact names instead of mangling ``KERNEL_IMAGE_*`` variables. | ||
197 | |||
198 | - The :term:`KERNEL_FIT_NAME` and | ||
199 | :term:`KERNEL_FIT_LINK_NAME` variables | ||
200 | have been introduced to specify the name of flattened image tree | ||
201 | (FIT) kernel images similar to other deployed artifacts. | ||
202 | |||
203 | - The :term:`MODULE_TARBALL_NAME` and | ||
204 | :term:`MODULE_TARBALL_LINK_NAME` | ||
205 | variable values no longer include the "module-" prefix or ".tgz" | ||
206 | suffix. These parts are now hardcoded so that the values are | ||
207 | consistent with other artifact naming variables. | ||
208 | |||
209 | - Added the :term:`INITRAMFS_LINK_NAME` | ||
210 | variable so that the symlink can be controlled similarly to other | ||
211 | artifact types. | ||
212 | |||
213 | - :term:`INITRAMFS_NAME` now uses | ||
214 | "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" instead | ||
215 | of "${PV}-${PR}-${MACHINE}-${DATETIME}", which makes it consistent | ||
216 | with other variables. | ||
217 | |||
218 | .. _migration-2.6-serial-console-deprecated: | ||
219 | |||
220 | ``SERIAL_CONSOLE`` Deprecated | ||
221 | ----------------------------- | ||
222 | |||
223 | The :term:`SERIAL_CONSOLE` variable has been | ||
224 | functionally replaced by the | ||
225 | :term:`SERIAL_CONSOLES` variable for some time. | ||
226 | With the Yocto Project 2.6 release, ``SERIAL_CONSOLE`` has been | ||
227 | officially deprecated. | ||
228 | |||
229 | ``SERIAL_CONSOLE`` will continue to work as before for the 2.6 release. | ||
230 | However, for the sake of future compatibility, it is recommended that | ||
231 | you replace all instances of ``SERIAL_CONSOLE`` with | ||
232 | ``SERIAL_CONSOLES``. | ||
233 | |||
234 | .. note:: | ||
235 | |||
236 | The only difference in usage is that | ||
237 | SERIAL_CONSOLES | ||
238 | expects entries to be separated using semicolons as compared to | ||
239 | SERIAL_CONSOLE | ||
240 | , which expects spaces. | ||
241 | |||
242 | .. _migration-2.6-poky-sets-unknown-configure-option-to-qa-error: | ||
243 | |||
244 | Configure Script Reports Unknown Options as Errors | ||
245 | -------------------------------------------------- | ||
246 | |||
247 | If the configure script reports an unknown option, this now triggers a | ||
248 | QA error instead of a warning. Any recipes that previously got away with | ||
249 | specifying such unknown options now need to be fixed. | ||
250 | |||
251 | .. _migration-2.6-override-changes: | ||
252 | |||
253 | Override Changes | ||
254 | ---------------- | ||
255 | |||
256 | The following changes have occurred: | ||
257 | |||
258 | - The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have | ||
259 | Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk`` | ||
260 | overrides have been deprecated since 2012 in favor of | ||
261 | ``class-native`` and ``class-nativesdk``, respectively. Both | ||
262 | ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped. | ||
263 | |||
264 | .. note:: | ||
265 | |||
266 | The | ||
267 | virtclass-multilib- | ||
268 | overrides for multilib are still valid. | ||
269 | |||
270 | - The ``forcevariable`` Override Now Has a Higher Priority Than | ||
271 | ``libc`` Overrides: The ``forcevariable`` override is documented to | ||
272 | be the highest priority override. However, due to a long-standing | ||
273 | quirk of how :term:`OVERRIDES` is set, the ``libc`` | ||
274 | overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth) | ||
275 | erroneously had a higher priority. This issue is now corrected. | ||
276 | |||
277 | It is likely this change will not cause any problems. However, it is | ||
278 | possible with some unusual configurations that you might see a change | ||
279 | in behavior if you were relying on the previous behavior. Be sure to | ||
280 | check how you use ``forcevariable`` and ``libc-*`` overrides in your | ||
281 | custom layers and configuration files to ensure they make sense. | ||
282 | |||
283 | - The ``build-${BUILD_OS}`` Override Has Been Removed: The | ||
284 | ``build-${BUILD_OS}``, which is typically ``build-linux``, override | ||
285 | has been removed because building on a host operating system other | ||
286 | than a recent version of Linux is neither supported nor recommended. | ||
287 | Dropping the override avoids giving the impression that other host | ||
288 | operating systems might be supported. | ||
289 | |||
290 | - The "_remove" operator now preserves whitespace. Consequently, when | ||
291 | specifying list items to remove, be aware that leading and trailing | ||
292 | whitespace resulting from the removal is retained. | ||
293 | |||
294 | See the ":ref:`bitbake:removing-override-style-syntax`" | ||
295 | section in the BitBake User Manual for a detailed example. | ||
296 | |||
297 | .. _migration-2.6-systemd-configuration-now-split-out-to-system-conf: | ||
298 | |||
299 | ``systemd`` Configuration is Now Split Into ``systemd-conf`` | ||
300 | ------------------------------------------------------------ | ||
301 | |||
302 | The configuration for the ``systemd`` recipe has been moved into a | ||
303 | ``system-conf`` recipe. Moving this configuration to a separate recipe | ||
304 | avoids the ``systemd`` recipe from becoming machine-specific for cases | ||
305 | where machine-specific configurations need to be applied (e.g. for | ||
306 | ``qemu*`` machines). | ||
307 | |||
308 | Currently, the new recipe packages the following files: | ||
309 | :: | ||
310 | |||
311 | ${sysconfdir}/machine-id | ||
312 | ${sysconfdir}/systemd/coredump.conf | ||
313 | ${sysconfdir}/systemd/journald.conf | ||
314 | ${sysconfdir}/systemd/logind.conf | ||
315 | ${sysconfdir}/systemd/system.conf | ||
316 | ${sysconfdir}/systemd/user.conf | ||
317 | |||
318 | If you previously used bbappend files to append the ``systemd`` recipe to | ||
319 | change any of the listed files, you must do so for the ``systemd-conf`` | ||
320 | recipe instead. | ||
321 | |||
322 | .. _migration-2.6-automatic-testing-changes: | ||
323 | |||
324 | Automatic Testing Changes | ||
325 | ------------------------- | ||
326 | |||
327 | This section provides information about automatic testing changes: | ||
328 | |||
329 | - ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the | ||
330 | ``TEST_IMAGE`` variable to "1" to enable automatic testing for | ||
331 | successfully built images. The ``TEST_IMAGE`` variable no longer | ||
332 | exists and has been replaced by the | ||
333 | :term:`TESTIMAGE_AUTO` variable. | ||
334 | |||
335 | - Inheriting the ``testimage`` and ``testsdk`` Classes: Best | ||
336 | practices now dictate that you use the | ||
337 | :term:`IMAGE_CLASSES` variable rather than the | ||
338 | :term:`INHERIT` variable when you inherit the | ||
339 | :ref:`testimage <ref-classes-testimage*>` and | ||
340 | :ref:`testsdk <ref-classes-testsdk>` classes used for automatic | ||
341 | testing. | ||
342 | |||
343 | .. _migration-2.6-openssl-changes: | ||
344 | |||
345 | OpenSSL Changes | ||
346 | --------------- | ||
347 | |||
348 | `OpenSSL <https://www.openssl.org/>`__ has been upgraded from 1.0 to | ||
349 | 1.1. By default, this upgrade could cause problems for recipes that have | ||
350 | both versions in their dependency chains. The problem is that both | ||
351 | versions cannot be installed together at build time. | ||
352 | |||
353 | .. note:: | ||
354 | |||
355 | It is possible to have both versions of the library at runtime. | ||
356 | |||
357 | .. _migration-2.6-bitbake-changes: | ||
358 | |||
359 | BitBake Changes | ||
360 | --------------- | ||
361 | |||
362 | The server logfile ``bitbake-cookerdaemon.log`` is now always placed in | ||
363 | the :term:`Build Directory` instead of the current | ||
364 | directory. | ||
365 | |||
366 | .. _migration-2.6-security-changes: | ||
367 | |||
368 | Security Changes | ||
369 | ---------------- | ||
370 | |||
371 | The Poky distribution now uses security compiler flags by default. | ||
372 | Inclusion of these flags could cause new failures due to stricter | ||
373 | checking for various potential security issues in code. | ||
374 | |||
375 | .. _migration-2.6-post-installation-changes: | ||
376 | |||
377 | Post Installation Changes | ||
378 | ------------------------- | ||
379 | |||
380 | You must explicitly mark post installs to defer to the target. If you | ||
381 | want to explicitly defer a postinstall to first boot on the target | ||
382 | rather than at rootfs creation time, use ``pkg_postinst_ontarget()`` or | ||
383 | call ``postinst_intercept delay_to_first_boot`` from ``pkg_postinst()``. | ||
384 | Any failure of a ``pkg_postinst()`` script (including exit 1) triggers | ||
385 | an error during the :ref:`ref-tasks-rootfs` task. | ||
386 | |||
387 | For more information on post-installation behavior, see the | ||
388 | ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`" | ||
389 | section in the Yocto Project Development Tasks Manual. | ||
390 | |||
391 | .. _migration-2.6-python-3-profile-guided-optimizations: | ||
392 | |||
393 | Python 3 Profile-Guided Optimization | ||
394 | ------------------------------------ | ||
395 | |||
396 | The ``python3`` recipe now enables profile-guided optimization. Using | ||
397 | this optimization requires a little extra build time in exchange for | ||
398 | improved performance on the target at runtime. Additionally, the | ||
399 | optimization is only enabled if the current | ||
400 | :term:`MACHINE` has support for user-mode emulation in | ||
401 | QEMU (i.e. "qemu-usermode" is in | ||
402 | :term:`MACHINE_FEATURES`, which it is by | ||
403 | default). | ||
404 | |||
405 | If you wish to disable Python profile-guided optimization regardless of | ||
406 | the value of ``MACHINE_FEATURES``, then ensure that | ||
407 | :term:`PACKAGECONFIG` for the ``python3`` recipe | ||
408 | does not contain "pgo". You could accomplish the latter using the | ||
409 | following at the configuration level: | ||
410 | :: | ||
411 | |||
412 | PACKAGECONFIG_remove_pn-python3 = "pgo" | ||
413 | |||
414 | Alternatively, you can set ``PACKAGECONFIG`` using an append file | ||
415 | for the ``python3`` recipe. | ||
416 | |||
417 | .. _migration-2.6-miscellaneous-changes: | ||
418 | |||
419 | Miscellaneous Changes | ||
420 | --------------------- | ||
421 | |||
422 | The following miscellaneous changes occurred: | ||
423 | |||
424 | - Default to using the Thumb-2 instruction set for armv7a and above. If | ||
425 | you have any custom recipes that build software that needs to be | ||
426 | built with the ARM instruction set, change the recipe to set the | ||
427 | instruction set as follows: | ||
428 | :: | ||
429 | |||
430 | ARM_INSTRUCTION_SET = "arm" | ||
431 | |||
432 | - ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for | ||
433 | ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior | ||
434 | remains unchanged. | ||
435 | |||
436 | - The ``NOISO`` and ``NOHDD`` variables are no longer used. You now | ||
437 | control building ``*.iso`` and ``*.hddimg`` image types directly by | ||
438 | using the :term:`IMAGE_FSTYPES` variable. | ||
439 | |||
440 | - The ``scripts/contrib/mkefidisk.sh`` has been removed in favor of | ||
441 | Wic. | ||
442 | |||
443 | - ``kernel-modules`` has been removed from | ||
444 | :term:`RRECOMMENDS` for ``qemumips`` and | ||
445 | ``qemumips64`` machines. Removal also impacts the ``x86-base.inc`` | ||
446 | file. | ||
447 | |||
448 | .. note:: | ||
449 | |||
450 | genericx86 | ||
451 | and | ||
452 | genericx86-64 | ||
453 | retain | ||
454 | kernel-modules | ||
455 | as part of the | ||
456 | RRECOMMENDS | ||
457 | variable setting. | ||
458 | |||
459 | - The ``LGPLv2_WHITELIST_GPL-3.0`` variable has been removed. If you | ||
460 | are setting this variable in your configuration, set or append it to | ||
461 | the ``WHITELIST_GPL-3.0`` variable instead. | ||
462 | |||
463 | - ``${ASNEEDED}`` is now included in the | ||
464 | :term:`TARGET_LDFLAGS` variable directly. The | ||
465 | remaining definitions from ``meta/conf/distro/include/as-needed.inc`` | ||
466 | have been moved to corresponding recipes. | ||
467 | |||
468 | - Support for DSA host keys has been dropped from the OpenSSH recipes. | ||
469 | If you are still using DSA keys, you must switch over to a more | ||
470 | secure algorithm as recommended by OpenSSH upstream. | ||
471 | |||
472 | - The ``dhcp`` recipe now uses the ``dhcpd6.conf`` configuration file | ||
473 | in ``dhcpd6.service`` for IPv6 DHCP rather than re-using | ||
474 | ``dhcpd.conf``, which is now reserved for IPv4. | ||
475 | |||
476 | |||
diff --git a/documentation/ref-manual/migration-2.7.rst b/documentation/ref-manual/migration-2.7.rst new file mode 100644 index 0000000000..7e628fc3ec --- /dev/null +++ b/documentation/ref-manual/migration-2.7.rst | |||
@@ -0,0 +1,180 @@ | |||
1 | Moving to the Yocto Project 2.7 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 2.7 Release from the prior release. | ||
6 | |||
7 | .. _migration-2.7-bitbake-changes: | ||
8 | |||
9 | BitBake Changes | ||
10 | --------------- | ||
11 | |||
12 | The following changes have been made to BitBake: | ||
13 | |||
14 | - BitBake now checks anonymous Python functions and pure Python | ||
15 | functions (e.g. ``def funcname:``) in the metadata for tab | ||
16 | indentation. If found, BitBake produces a warning. | ||
17 | |||
18 | - Bitbake now checks | ||
19 | :term:`BBFILE_COLLECTIONS` for duplicate | ||
20 | entries and triggers an error if any are found. | ||
21 | |||
22 | .. _migration-2.7-eclipse-support-dropped: | ||
23 | |||
24 | Eclipse Support Removed | ||
25 | ----------------------- | ||
26 | |||
27 | Support for the Eclipse IDE has been removed. Support continues for | ||
28 | those releases prior to 2.7 that did include support. The 2.7 release | ||
29 | does not include the Eclipse Yocto plugin. | ||
30 | |||
31 | .. _migration-2.7-qemu-native-splits-system-and-user-mode-parts: | ||
32 | |||
33 | ``qemu-native`` Splits the System and User-Mode Parts | ||
34 | ----------------------------------------------------- | ||
35 | |||
36 | The system and user-mode parts of ``qemu-native`` are now split. | ||
37 | ``qemu-native`` provides the user-mode components and | ||
38 | ``qemu-system-native`` provides the system components. If you have | ||
39 | recipes that depend on QEMU's system emulation functionality at build | ||
40 | time, they should now depend upon ``qemu-system-native`` instead of | ||
41 | ``qemu-native``. | ||
42 | |||
43 | .. _migration-2.7-upstream-tracking.inc-removed: | ||
44 | |||
45 | The ``upstream-tracking.inc`` File Has Been Removed | ||
46 | --------------------------------------------------- | ||
47 | |||
48 | The previously deprecated ``upstream-tracking.inc`` file is now removed. | ||
49 | Any ``UPSTREAM_TRACKING*`` variables are now set in the corresponding | ||
50 | recipes instead. | ||
51 | |||
52 | Remove any references you have to the ``upstream-tracking.inc`` file in | ||
53 | your configuration. | ||
54 | |||
55 | .. _migration-2.7-distro-features-libc-removed: | ||
56 | |||
57 | The ``DISTRO_FEATURES_LIBC`` Variable Has Been Removed | ||
58 | ------------------------------------------------------ | ||
59 | |||
60 | The ``DISTRO_FEATURES_LIBC`` variable is no longer used. The ability to | ||
61 | configure glibc using kconfig has been removed for quite some time | ||
62 | making the ``libc-*`` features set no longer effective. | ||
63 | |||
64 | Remove any references you have to ``DISTRO_FEATURES_LIBC`` in your own | ||
65 | layers. | ||
66 | |||
67 | .. _migration-2.7-license-values: | ||
68 | |||
69 | License Value Corrections | ||
70 | ------------------------- | ||
71 | |||
72 | The following corrections have been made to the | ||
73 | :term:`LICENSE` values set by recipes: | ||
74 | |||
75 | - *socat*: Corrected ``LICENSE`` to be "GPLv2" rather than "GPLv2+". | ||
76 | - *libgfortran*: Set license to "GPL-3.0-with-GCC-exception". | ||
77 | - *elfutils*: Removed "Elfutils-Exception" and set to "GPLv2" for shared libraries | ||
78 | |||
79 | .. _migration-2.7-packaging-changes: | ||
80 | |||
81 | Packaging Changes | ||
82 | ----------------- | ||
83 | |||
84 | This section provides information about packaging changes. | ||
85 | |||
86 | - ``bind``: The ``nsupdate`` binary has been moved to the | ||
87 | ``bind-utils`` package. | ||
88 | |||
89 | - Debug split: The default debug split has been changed to create | ||
90 | separate source packages (i.e. package_name\ ``-dbg`` and | ||
91 | package_name\ ``-src``). If you are currently using ``dbg-pkgs`` in | ||
92 | :term:`IMAGE_FEATURES` to bring in debug | ||
93 | symbols and you still need the sources, you must now also add | ||
94 | ``src-pkgs`` to ``IMAGE_FEATURES``. Source packages remain in the | ||
95 | target portion of the SDK by default, unless you have set your own | ||
96 | value for :term:`SDKIMAGE_FEATURES` that | ||
97 | does not include ``src-pkgs``. | ||
98 | |||
99 | - Mount all using ``util-linux``: ``/etc/default/mountall`` has moved | ||
100 | into the -mount sub-package. | ||
101 | |||
102 | - Splitting binaries using ``util-linux``: ``util-linux`` now splits | ||
103 | each binary into its own package for fine-grained control. The main | ||
104 | ``util-linux`` package pulls in the individual binary packages using | ||
105 | the :term:`RRECOMMENDS` and | ||
106 | :term:`RDEPENDS` variables. As a result, existing | ||
107 | images should not see any changes assuming | ||
108 | :term:`NO_RECOMMENDATIONS` is not set. | ||
109 | |||
110 | - ``netbase/base-files``: ``/etc/hosts`` has moved from ``netbase`` to | ||
111 | ``base-files``. | ||
112 | |||
113 | - ``tzdata``: The main package has been converted to an empty meta | ||
114 | package that pulls in all ``tzdata`` packages by default. | ||
115 | |||
116 | - ``lrzsz``: This package has been removed from | ||
117 | ``packagegroup-self-hosted`` and | ||
118 | ``packagegroup-core-tools-testapps``. The X/Y/ZModem support is less | ||
119 | likely to be needed on modern systems. If you are relying on these | ||
120 | packagegroups to include the ``lrzsz`` package in your image, you now | ||
121 | need to explicitly add the package. | ||
122 | |||
123 | .. _migration-2.7-removed-recipes: | ||
124 | |||
125 | Removed Recipes | ||
126 | --------------- | ||
127 | |||
128 | The following recipes have been removed: | ||
129 | |||
130 | - *gcc*: Drop version 7.3 recipes. Version 8.3 now remains. | ||
131 | - *linux-yocto*: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain. | ||
132 | - *go*: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain. | ||
133 | - *xvideo-tests*: Became obsolete. | ||
134 | - *libart-lgpl*: Became obsolete. | ||
135 | - *gtk-icon-utils-native*: These tools are now provided by gtk+3-native | ||
136 | - *gcc-cross-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead. | ||
137 | - *gcc-crosssdk-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead. | ||
138 | - *glibc-initial*: Removed because the benefits of having it for site_config are currently outweighed by the cost of building the recipe. | ||
139 | |||
140 | .. _migration-2.7-removed-classes: | ||
141 | |||
142 | Removed Classes | ||
143 | --------------- | ||
144 | |||
145 | The following classes have been removed: | ||
146 | |||
147 | - *distutils-tools*: This class was never used. | ||
148 | - *bugzilla.bbclass*: Became obsolete. | ||
149 | - *distrodata*: This functionally has been replaced by a more modern tinfoil-based implementation. | ||
150 | |||
151 | .. _migration-2.7-miscellaneous-changes: | ||
152 | |||
153 | Miscellaneous Changes | ||
154 | --------------------- | ||
155 | |||
156 | The following miscellaneous changes occurred: | ||
157 | |||
158 | - The ``distro`` subdirectory of the Poky repository has been removed | ||
159 | from the top-level ``scripts`` directory. | ||
160 | |||
161 | - Perl now builds for the target using | ||
162 | `perl-cross <http://arsv.github.io/perl-cross/>`_ for better | ||
163 | maintainability and improved build performance. This change should | ||
164 | not present any problems unless you have heavily customized your Perl | ||
165 | recipe. | ||
166 | |||
167 | - ``arm-tunes``: Removed the "-march" option if mcpu is already added. | ||
168 | |||
169 | - ``update-alternatives``: Convert file renames to | ||
170 | :term:`PACKAGE_PREPROCESS_FUNCS` | ||
171 | |||
172 | - ``base/pixbufcache``: Obsolete ``sstatecompletions`` code has been | ||
173 | removed. | ||
174 | |||
175 | - :ref:`native <ref-classes-native>` class: | ||
176 | :term:`RDEPENDS` handling has been enabled. | ||
177 | |||
178 | - ``inetutils``: This recipe has rsh disabled. | ||
179 | |||
180 | |||
diff --git a/documentation/ref-manual/migration-3.0.rst b/documentation/ref-manual/migration-3.0.rst new file mode 100644 index 0000000000..e1305dfccf --- /dev/null +++ b/documentation/ref-manual/migration-3.0.rst | |||
@@ -0,0 +1,321 @@ | |||
1 | Moving to the Yocto Project 3.0 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 3.0 Release from the prior release. | ||
6 | |||
7 | .. _migration-3.0-init-system-selection: | ||
8 | |||
9 | Init System Selection | ||
10 | --------------------- | ||
11 | |||
12 | Changing the init system manager previously required setting a number of | ||
13 | different variables. You can now change the manager by setting the | ||
14 | ``INIT_MANAGER`` variable and the corresponding include files (i.e. | ||
15 | ``conf/distro/include/init-manager-*.conf``). Include files are provided | ||
16 | for four values: "none", "sysvinit", "systemd", and "mdev-busybox". The | ||
17 | default value, "none", for ``INIT_MANAGER`` should allow your current | ||
18 | settings to continue working. However, it is advisable to explicitly set | ||
19 | ``INIT_MANAGER``. | ||
20 | |||
21 | .. _migration-3.0-lsb-support-removed: | ||
22 | |||
23 | LSB Support Removed | ||
24 | ------------------- | ||
25 | |||
26 | Linux Standard Base (LSB) as a standard is not current, and is not well | ||
27 | suited for embedded applications. Support can be continued in a separate | ||
28 | layer if needed. However, presently LSB support has been removed from | ||
29 | the core. | ||
30 | |||
31 | As a result of this change, the ``poky-lsb`` derivative distribution | ||
32 | configuration that was also used for testing alternative configurations | ||
33 | has been replaced with a ``poky-altcfg`` distribution that has LSB parts | ||
34 | removed. | ||
35 | |||
36 | .. _migration-3.0-removed-recipes: | ||
37 | |||
38 | Removed Recipes | ||
39 | --------------- | ||
40 | |||
41 | The following recipes have been removed. | ||
42 | |||
43 | - ``core-image-lsb-dev``: Part of removed LSB support. | ||
44 | |||
45 | - ``core-image-lsb``: Part of removed LSB support. | ||
46 | |||
47 | - ``core-image-lsb-sdk``: Part of removed LSB support. | ||
48 | |||
49 | - ``cve-check-tool``: Functionally replaced by the ``cve-update-db`` | ||
50 | recipe and ``cve-check`` class. | ||
51 | |||
52 | - ``eglinfo``: No longer maintained. ``eglinfo`` from ``mesa-demos`` is | ||
53 | an adequate and maintained alternative. | ||
54 | |||
55 | - ``gcc-8.3``: Version 8.3 removed. Replaced by 9.2. | ||
56 | |||
57 | - ``gnome-themes-standard``: Only needed by gtk+ 2.x, which has been | ||
58 | removed. | ||
59 | |||
60 | - ``gtk+``: GTK+ 2 is obsolete and has been replaced by gtk+3. | ||
61 | |||
62 | - ``irda-utils``: Has become obsolete. IrDA support has been removed | ||
63 | from the Linux kernel in version 4.17 and later. | ||
64 | |||
65 | - ``libnewt-python``: ``libnewt`` Python support merged into main | ||
66 | ``libnewt`` recipe. | ||
67 | |||
68 | - ``libsdl``: Replaced by newer ``libsdl2``. | ||
69 | |||
70 | - ``libx11-diet``: Became obsolete. | ||
71 | |||
72 | - ``libxx86dga``: Removed obsolete client library. | ||
73 | |||
74 | - ``libxx86misc``: Removed. Library is redundant. | ||
75 | |||
76 | - ``linux-yocto``: Version 5.0 removed, which is now redundant (5.2 / | ||
77 | 4.19 present). | ||
78 | |||
79 | - ``lsbinitscripts``: Part of removed LSB support. | ||
80 | |||
81 | - ``lsb``: Part of removed LSB support. | ||
82 | |||
83 | - ``lsbtest``: Part of removed LSB support. | ||
84 | |||
85 | - ``openssl10``: Replaced by newer ``openssl`` version 1.1. | ||
86 | |||
87 | - ``packagegroup-core-lsb``: Part of removed LSB support. | ||
88 | |||
89 | - ``python-nose``: Removed the Python 2.x version of the recipe. | ||
90 | |||
91 | - ``python-numpy``: Removed the Python 2.x version of the recipe. | ||
92 | |||
93 | - ``python-scons``: Removed the Python 2.x version of the recipe. | ||
94 | |||
95 | - ``source-highlight``: No longer needed. | ||
96 | |||
97 | - ``stress``: Replaced by ``stress-ng``. | ||
98 | |||
99 | - ``vulkan``: Split into ``vulkan-loader``, ``vulkan-headers``, and | ||
100 | ``vulkan-tools``. | ||
101 | |||
102 | - ``weston-conf``: Functionality moved to ``weston-init``. | ||
103 | |||
104 | .. _migration-3.0-packaging-changes: | ||
105 | |||
106 | Packaging Changes | ||
107 | ----------------- | ||
108 | |||
109 | The following packaging changes have occurred. | ||
110 | |||
111 | - The `Epiphany <https://en.wikipedia.org/wiki/GNOME_Web>`__ browser | ||
112 | has been dropped from ``packagegroup-self-hosted`` as it has not been | ||
113 | needed inside ``build-appliance-image`` for quite some time and was | ||
114 | causing resource problems. | ||
115 | |||
116 | - ``libcap-ng`` Python support has been moved to a separate | ||
117 | ``libcap-ng-python`` recipe to streamline the build process when the | ||
118 | Python bindings are not needed. | ||
119 | |||
120 | - ``libdrm`` now packages the file ``amdgpu.ids`` into a separate | ||
121 | ``libdrm-amdgpu`` package. | ||
122 | |||
123 | - ``python3``: The ``runpy`` module is now in the ``python3-core`` | ||
124 | package as it is required to support the common "python3 -m" command | ||
125 | usage. | ||
126 | |||
127 | - ``distcc`` now provides separate ``distcc-client`` and | ||
128 | ``distcc-server`` packages as typically one or the other are needed, | ||
129 | rather than both. | ||
130 | |||
131 | - ``python*-setuptools`` recipes now separately package the | ||
132 | ``pkg_resources`` module in a ``python-pkg-resources`` / | ||
133 | ``python3-pkg-resources`` package as the module is useful independent | ||
134 | of the rest of the setuptools package. The main ``python-setuptools`` | ||
135 | / ``python3-setuptools`` package depends on this new package so you | ||
136 | should only need to update dependencies unless you want to take | ||
137 | advantage of the increased granularity. | ||
138 | |||
139 | .. _migration-3.0-cve-checking: | ||
140 | |||
141 | CVE Checking | ||
142 | ------------ | ||
143 | |||
144 | ``cve-check-tool`` has been functionally replaced by a new | ||
145 | ``cve-update-db`` recipe and functionality built into the ``cve-check`` | ||
146 | class. The result uses NVD JSON data feeds rather than the deprecated | ||
147 | XML feeds that ``cve-check-tool`` was using, supports CVSSv3 scoring, | ||
148 | and makes other improvements. | ||
149 | |||
150 | Additionally, the ``CVE_CHECK_CVE_WHITELIST`` variable has been replaced | ||
151 | by ``CVE_CHECK_WHITELIST``. | ||
152 | |||
153 | .. _migration-3.0-bitbake-changes: | ||
154 | |||
155 | Bitbake Changes | ||
156 | --------------- | ||
157 | |||
158 | The following BitBake changes have occurred. | ||
159 | |||
160 | - ``addtask`` statements now properly validate dependent tasks. | ||
161 | Previously, an invalid task was silently ignored. With this change, | ||
162 | the invalid task generates a warning. | ||
163 | |||
164 | - Other invalid ``addtask`` and ``deltask`` usages now trigger these | ||
165 | warnings: "multiple target tasks arguments with addtask / deltask", | ||
166 | and "multiple before/after clauses". | ||
167 | |||
168 | - The "multiconfig" prefix is now shortened to "mc". "multiconfig" will | ||
169 | continue to work, however it may be removed in a future release. | ||
170 | |||
171 | - The ``bitbake -g`` command no longer generates a | ||
172 | ``recipe-depends.dot`` file as the contents (i.e. a reprocessed | ||
173 | version of ``task-depends.dot``) were confusing. | ||
174 | |||
175 | - The ``bb.build.FuncFailed`` exception, previously raised by | ||
176 | ``bb.build.exec_func()`` when certain other exceptions have occurred, | ||
177 | has been removed. The real underlying exceptions will be raised | ||
178 | instead. If you have calls to ``bb.build.exec_func()`` in custom | ||
179 | classes or ``tinfoil-using`` scripts, any references to | ||
180 | ``bb.build.FuncFailed`` should be cleaned up. | ||
181 | |||
182 | - Additionally, the ``bb.build.exec_func()`` no longer accepts the | ||
183 | "pythonexception" parameter. The function now always raises | ||
184 | exceptions. Remove this argument in any calls to | ||
185 | ``bb.build.exec_func()`` in custom classes or scripts. | ||
186 | |||
187 | - The | ||
188 | :term:`bitbake:BB_SETSCENE_VERIFY_FUNCTION2` | ||
189 | is no longer used. In the unlikely event that you have any references | ||
190 | to it, they should be removed. | ||
191 | |||
192 | - The ``RunQueueExecuteScenequeue`` and ``RunQueueExecuteTasks`` events | ||
193 | have been removed since setscene tasks are now executed as part of | ||
194 | the normal runqueue. Any event handling code in custom classes or | ||
195 | scripts that handles these two events need to be updated. | ||
196 | |||
197 | - The arguments passed to functions used with | ||
198 | :term:`bitbake:BB_HASHCHECK_FUNCTION` | ||
199 | have changed. If you are using your own custom hash check function, | ||
200 | see | ||
201 | http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725 | ||
202 | for details. | ||
203 | |||
204 | - Task specifications in ``BB_TASKDEPDATA`` and class implementations | ||
205 | used in signature generator classes now use "<fn>:<task>" everywhere | ||
206 | rather than the "." delimiter that was being used in some places. | ||
207 | This change makes it consistent with all areas in the code. Custom | ||
208 | signature generator classes and code that reads ``BB_TASKDEPDATA`` | ||
209 | need to be updated to use ':' as a separator rather than '.'. | ||
210 | |||
211 | .. _migration-3.0-sanity-checks: | ||
212 | |||
213 | Sanity Checks | ||
214 | ------------- | ||
215 | |||
216 | The following sanity check changes occurred. | ||
217 | |||
218 | - :term:`SRC_URI` is now checked for usage of two | ||
219 | problematic items: | ||
220 | |||
221 | - "${PN}" prefix/suffix use - Warnings always appear if ${PN} is | ||
222 | used. You must fix the issue regardless of whether multiconfig or | ||
223 | anything else that would cause prefixing/suffixing to happen. | ||
224 | |||
225 | - Github archive tarballs - these are not guaranteed to be stable. | ||
226 | Consequently, it is likely that the tarballs will be refreshed and | ||
227 | thus the SRC_URI checksums will fail to apply. It is recommended | ||
228 | that you fetch either an official release tarball or a specific | ||
229 | revision from the actual Git repository instead. | ||
230 | |||
231 | Either one of these items now trigger a warning by default. If you | ||
232 | wish to disable this check, remove ``src-uri-bad`` from | ||
233 | :term:`WARN_QA`. | ||
234 | |||
235 | - The ``file-rdeps`` runtime dependency check no longer expands | ||
236 | :term:`RDEPENDS` recursively as there is no mechanism | ||
237 | to ensure they can be fully computed, and thus races sometimes result | ||
238 | in errors either showing up or not. Thus, you might now see errors | ||
239 | for missing runtime dependencies that were previously satisfied | ||
240 | recursively. Here is an example: package A contains a shell script | ||
241 | starting with ``#!/bin/bash`` but has no dependency on bash. However, | ||
242 | package A depends on package B, which does depend on bash. You need | ||
243 | to add the missing dependency or dependencies to resolve the warning. | ||
244 | |||
245 | - Setting ``DEPENDS_${PN}`` anywhere (i.e. typically in a recipe) now | ||
246 | triggers an error. The error is triggered because | ||
247 | :term:`DEPENDS` is not a package-specific variable | ||
248 | unlike RDEPENDS. You should set ``DEPENDS`` instead. | ||
249 | |||
250 | - systemd currently does not work well with the musl C library because | ||
251 | only upstream officially supports linking the library with glibc. | ||
252 | Thus, a warning is shown when building systemd in conjunction with | ||
253 | musl. | ||
254 | |||
255 | .. _migration-3.0-miscellaneous-changes: | ||
256 | |||
257 | Miscellaneous Changes | ||
258 | --------------------- | ||
259 | |||
260 | The following miscellaneous changes have occurred. | ||
261 | |||
262 | - The ``gnome`` class has been removed because it now does very little. | ||
263 | You should update recipes that previously inherited this class to do | ||
264 | the following: inherit gnomebase gtk-icon-cache gconf mime | ||
265 | |||
266 | - The ``meta/recipes-kernel/linux/linux-dtb.inc`` file has been | ||
267 | removed. This file was previously deprecated in favor of setting | ||
268 | :term:`KERNEL_DEVICETREE` in any kernel | ||
269 | recipe and only produced a warning. Remove any ``include`` or | ||
270 | ``require`` statements pointing to this file. | ||
271 | |||
272 | - :term:`TARGET_CFLAGS`, | ||
273 | :term:`TARGET_CPPFLAGS`, | ||
274 | :term:`TARGET_CXXFLAGS`, and | ||
275 | :term:`TARGET_LDFLAGS` are no longer exported | ||
276 | to the external environment. This change did not require any changes | ||
277 | to core recipes, which is a good indicator that no changes will be | ||
278 | required. However, if for some reason the software being built by one | ||
279 | of your recipes is expecting these variables to be set, then building | ||
280 | the recipe will fail. In such cases, you must either export the | ||
281 | variable or variables in the recipe or change the scripts so that | ||
282 | exporting is not necessary. | ||
283 | |||
284 | - You must change the host distro identifier used in | ||
285 | :term:`NATIVELSBSTRING` to use all lowercase | ||
286 | characters even if it does not contain a version number. This change | ||
287 | is necessary only if you are not using ``uninative`` and | ||
288 | :term:`SANITY_TESTED_DISTROS`. | ||
289 | |||
290 | - In the ``base-files`` recipe, writing the hostname into | ||
291 | ``/etc/hosts`` and ``/etc/hostname`` is now done within the main | ||
292 | :ref:`ref-tasks-install` function rather than in the | ||
293 | ``do_install_basefilesissue`` function. The reason for the change is | ||
294 | because ``do_install_basefilesissue`` is more easily overridden | ||
295 | without having to duplicate the hostname functionality. If you have | ||
296 | done the latter (e.g. in a ``base-files`` bbappend), then you should | ||
297 | remove it from your customized ``do_install_basefilesissue`` | ||
298 | function. | ||
299 | |||
300 | - The ``wic --expand`` command now uses commas to separate "key:value" | ||
301 | pairs rather than hyphens. | ||
302 | |||
303 | .. note:: | ||
304 | |||
305 | The wic command-line help is not updated. | ||
306 | |||
307 | You must update any scripts or commands where you use | ||
308 | ``wic --expand`` with multiple "key:value" pairs. | ||
309 | |||
310 | - UEFI image variable settings have been moved from various places to a | ||
311 | central ``conf/image-uefi.conf``. This change should not influence | ||
312 | any existing configuration as the ``meta/conf/image-uefi.conf`` in | ||
313 | the core metadata sets defaults that can be overridden in the same | ||
314 | manner as before. | ||
315 | |||
316 | - ``conf/distro/include/world-broken.inc`` has been removed. For cases | ||
317 | where certain recipes need to be disabled when using the musl C | ||
318 | library, these recipes now have ``COMPATIBLE_HOST_libc-musl`` set | ||
319 | with a comment that explains why. | ||
320 | |||
321 | |||
diff --git a/documentation/ref-manual/migration-3.1.rst b/documentation/ref-manual/migration-3.1.rst new file mode 100644 index 0000000000..92c8c77613 --- /dev/null +++ b/documentation/ref-manual/migration-3.1.rst | |||
@@ -0,0 +1,276 @@ | |||
1 | Moving to the Yocto Project 3.1 Release | ||
2 | ======================================= | ||
3 | |||
4 | This section provides migration information for moving to the Yocto | ||
5 | Project 3.1 Release from the prior release. | ||
6 | |||
7 | .. _migration-3.1-minimum-system-requirements: | ||
8 | |||
9 | Minimum system requirements | ||
10 | --------------------------- | ||
11 | |||
12 | The following versions / requirements of build host components have been | ||
13 | updated: | ||
14 | |||
15 | - gcc 5.0 | ||
16 | |||
17 | - python 3.5 | ||
18 | |||
19 | - tar 1.28 | ||
20 | |||
21 | - ``rpcgen`` is now required on the host (part of the ``libc-dev-bin`` | ||
22 | package on Ubuntu, Debian and related distributions, and the | ||
23 | ``glibc`` package on RPM-based distributions). | ||
24 | |||
25 | Additionally, the ``makeinfo`` and ``pod2man`` tools are *no longer* | ||
26 | required on the host. | ||
27 | |||
28 | .. _migration-3.1-mpc8315e-rdb-removed: | ||
29 | |||
30 | mpc8315e-rdb machine removed | ||
31 | ---------------------------- | ||
32 | |||
33 | The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given | ||
34 | the maintenance burden the ``mpc8315e-rdb`` machine configuration that | ||
35 | supported it has been removed in this release. The removal does leave a | ||
36 | gap in official PowerPC reference hardware support; this may change in | ||
37 | future if a suitable machine with accompanying support resources is | ||
38 | found. | ||
39 | |||
40 | .. _migration-3.1-python-2-removed: | ||
41 | |||
42 | Python 2 removed | ||
43 | ---------------- | ||
44 | |||
45 | Due to the expiration of upstream support in January 2020, support for | ||
46 | Python 2 has now been removed; it is recommended that you use Python 3 | ||
47 | instead. If absolutely needed there is a meta-python2 community layer | ||
48 | containing Python 2, related classes and various Python 2-based modules, | ||
49 | however it should not be considered as supported. | ||
50 | |||
51 | .. _migration-3.1-reproducible-builds: | ||
52 | |||
53 | Reproducible builds now enabled by default | ||
54 | ------------------------------------------ | ||
55 | |||
56 | In order to avoid unnecessary differences in output files (aiding binary | ||
57 | reproducibility), the Poky distribution configuration | ||
58 | (``DISTRO = "poky"``) now inherits the ``reproducible_build`` class by | ||
59 | default. | ||
60 | |||
61 | .. _migration-3.1-ptest-feature-impact: | ||
62 | |||
63 | Impact of ptest feature is now more significant | ||
64 | ----------------------------------------------- | ||
65 | |||
66 | The Poky distribution configuration (``DISTRO = "poky"``) enables ptests | ||
67 | by default to enable runtime testing of various components. In this | ||
68 | release, a dependency needed to be added that has resulted in a | ||
69 | significant increase in the number of components that will be built just | ||
70 | when building a simple image such as core-image-minimal. If you do not | ||
71 | need runtime tests enabled for core components, then it is recommended | ||
72 | that you remove "ptest" from | ||
73 | :term:`DISTRO_FEATURES` to save a significant | ||
74 | amount of build time e.g. by adding the following in your configuration: | ||
75 | :: | ||
76 | |||
77 | DISTRO_FEATURES_remove = "ptest" | ||
78 | |||
79 | .. _migration-3.1-removed-recipes: | ||
80 | |||
81 | Removed recipes | ||
82 | --------------- | ||
83 | |||
84 | The following recipes have been removed: | ||
85 | |||
86 | - ``chkconfig``: obsolete | ||
87 | |||
88 | - ``console-tools``: obsolete | ||
89 | |||
90 | - ``enchant``: replaced by ``enchant2`` | ||
91 | |||
92 | - ``foomatic-filters``: obsolete | ||
93 | |||
94 | - ``libidn``: no longer needed, moved to meta-oe | ||
95 | |||
96 | - ``libmodulemd``: replaced by ``libmodulemd-v1`` | ||
97 | |||
98 | - ``linux-yocto``: drop 4.19, 5.2 version recipes (5.4 now provided) | ||
99 | |||
100 | - ``nspr``: no longer needed, moved to meta-oe | ||
101 | |||
102 | - ``nss``: no longer needed, moved to meta-oe | ||
103 | |||
104 | - ``python``: Python 2 removed (Python 3 preferred) | ||
105 | |||
106 | - ``python-setuptools``: Python 2 version removed (python3-setuptools | ||
107 | preferred) | ||
108 | |||
109 | - ``sysprof``: no longer needed, moved to meta-oe | ||
110 | |||
111 | - ``texi2html``: obsolete | ||
112 | |||
113 | - ``u-boot-fw-utils``: functionally replaced by ``libubootenv`` | ||
114 | |||
115 | .. _migration-3.1-features-check: | ||
116 | |||
117 | features_check class replaces distro_features_check | ||
118 | --------------------------------------------------- | ||
119 | |||
120 | The ``distro_features_check`` class has had its functionality expanded, | ||
121 | now supporting ``ANY_OF_MACHINE_FEATURES``, | ||
122 | ``REQUIRED_MACHINE_FEATURES``, ``CONFLICT_MACHINE_FEATURES``, | ||
123 | ``ANY_OF_COMBINED_FEATURES``, ``REQUIRED_COMBINED_FEATURES``, | ||
124 | ``CONFLICT_COMBINED_FEATURES``. As a result the class has now been | ||
125 | renamed to ``features_check``; the ``distro_features_check`` class still | ||
126 | exists but generates a warning and redirects to the new class. In | ||
127 | preparation for a future removal of the old class it is recommended that | ||
128 | you update recipes currently inheriting ``distro_features_check`` to | ||
129 | inherit ``features_check`` instead. | ||
130 | |||
131 | .. _migration-3.1-removed-classes: | ||
132 | |||
133 | Removed classes | ||
134 | --------------- | ||
135 | |||
136 | The following classes have been removed: | ||
137 | |||
138 | - ``distutils-base``: moved to meta-python2 | ||
139 | |||
140 | - ``distutils``: moved to meta-python2 | ||
141 | |||
142 | - ``libc-common``: merged into the glibc recipe as nothing else used | ||
143 | it. | ||
144 | |||
145 | - ``python-dir``: moved to meta-python2 | ||
146 | |||
147 | - ``pythonnative``: moved to meta-python2 | ||
148 | |||
149 | - ``setuptools``: moved to meta-python2 | ||
150 | |||
151 | - ``tinderclient``: dropped as it was obsolete. | ||
152 | |||
153 | .. _migration-3.1-src-uri-checksums: | ||
154 | |||
155 | SRC_URI checksum behaviour | ||
156 | -------------------------- | ||
157 | |||
158 | Previously, recipes by tradition included both SHA256 and MD5 checksums | ||
159 | for remotely fetched files in :term:`SRC_URI`, even | ||
160 | though only one is actually mandated. However, the MD5 checksum does not | ||
161 | add much given its inherent weakness; thus when a checksum fails only | ||
162 | the SHA256 sum will now be printed. The md5sum will still be verified if | ||
163 | it is specified. | ||
164 | |||
165 | .. _migration-3.1-npm: | ||
166 | |||
167 | npm fetcher changes | ||
168 | ------------------- | ||
169 | |||
170 | The npm fetcher has been completely reworked in this release. The npm | ||
171 | fetcher now only fetches the package source itself and no longer the | ||
172 | dependencies; there is now also an npmsw fetcher which explicitly | ||
173 | fetches the shrinkwrap file and the dependencies. This removes the | ||
174 | slightly awkward ``NPM_LOCKDOWN`` and ``NPM_SHRINKWRAP`` variables which | ||
175 | pointed to local files; the lockdown file is no longer needed at all. | ||
176 | Additionally, the package name in ``npm://`` entries in | ||
177 | :term:`SRC_URI` is now specified using a ``package`` | ||
178 | parameter instead of the earlier ``name`` which overlapped with the | ||
179 | generic ``name`` parameter. All recipes using the npm fetcher will need | ||
180 | to be changed as a result. | ||
181 | |||
182 | An example of the new scheme: :: | ||
183 | |||
184 | SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \\ | ||
185 | npmsw://${THISDIR}/npm-shrinkwrap.json" | ||
186 | |||
187 | Another example where the sources are fetched from git rather than an npm repository: :: | ||
188 | |||
189 | SRC_URI = "git://github.com/foo/bar.git;protocol=https \ | ||
190 | npmsw://${THISDIR}/npm-shrinkwrap.json" | ||
191 | |||
192 | devtool and recipetool have also been updated to match with the npm | ||
193 | fetcher changes. Other than producing working and more complete recipes | ||
194 | for npm sources, there is also a minor change to the command line for | ||
195 | devtool: the ``--fetch-dev`` option has been renamed to ``--npm-dev`` as | ||
196 | it is npm-specific. | ||
197 | |||
198 | .. _migration-3.1-packaging-changes: | ||
199 | |||
200 | Packaging changes | ||
201 | ----------------- | ||
202 | |||
203 | - ``intltool`` has been removed from ``packagegroup-core-sdk`` as it is | ||
204 | rarely needed to build modern software - gettext can do most of the | ||
205 | things it used to be needed for. ``intltool`` has also been removed | ||
206 | from ``packagegroup-core-self-hosted`` as it is not needed to for | ||
207 | standard builds. | ||
208 | |||
209 | - git: ``git-am``, ``git-difftool``, ``git-submodule``, and | ||
210 | ``git-request-pull`` are no longer perl-based, so are now installed | ||
211 | with the main ``git`` package instead of within ``git-perltools``. | ||
212 | |||
213 | - The ``ldconfig`` binary built as part of glibc has now been moved to | ||
214 | its own ``ldconfig`` package (note no ``glibc-`` prefix). This | ||
215 | package is in the :term:`RRECOMMENDS` of the main | ||
216 | ``glibc`` package if ``ldconfig`` is present in | ||
217 | :term:`DISTRO_FEATURES`. | ||
218 | |||
219 | - ``libevent`` now splits each shared library into its own package (as | ||
220 | Debian does). Since these are shared libraries and will be pulled in | ||
221 | through the normal shared library dependency handling, there should | ||
222 | be no impact to existing configurations other than less unnecessary | ||
223 | libraries being installed in some cases. | ||
224 | |||
225 | - linux-firmware now has a new package for ``bcm4366c`` and includes | ||
226 | available NVRAM config files into the ``bcm43340``, ``bcm43362``, | ||
227 | ``bcm43430`` and ``bcm4356-pcie`` packages. | ||
228 | |||
229 | - ``harfbuzz`` now splits the new ``libharfbuzz-subset.so`` library | ||
230 | into its own package to reduce the main package size in cases where | ||
231 | ``libharfbuzz-subset.so`` is not needed. | ||
232 | |||
233 | .. _migration-3.1-package-qa-warnings: | ||
234 | |||
235 | Additional warnings | ||
236 | ------------------- | ||
237 | |||
238 | Warnings will now be shown at ``do_package_qa`` time in the following | ||
239 | circumstances: | ||
240 | |||
241 | - A recipe installs ``.desktop`` files containing ``MimeType`` keys but | ||
242 | does not inherit the new ``mime-xdg`` class | ||
243 | |||
244 | - A recipe installs ``.xml`` files into ``${datadir}/mime/packages`` | ||
245 | but does not inherit the ``mime`` class | ||
246 | |||
247 | .. _migration-3.1-x86-live-wic: | ||
248 | |||
249 | ``wic`` image type now used instead of ``live`` by default for x86 | ||
250 | ------------------------------------------------------------------ | ||
251 | |||
252 | ``conf/machine/include/x86-base.inc`` (inherited by most x86 machine | ||
253 | configurations) now specifies ``wic`` instead of ``live`` by default in | ||
254 | :term:`IMAGE_FSTYPES`. The ``live`` image type will | ||
255 | likely be removed in a future release so it is recommended that you use | ||
256 | ``wic`` instead. | ||
257 | |||
258 | .. _migration-3.1-misc: | ||
259 | |||
260 | Miscellaneous changes | ||
261 | --------------------- | ||
262 | |||
263 | - The undocumented ``SRC_DISTRIBUTE_LICENSES`` variable has now been | ||
264 | removed in favour of a new ``AVAILABLE_LICENSES`` variable which is | ||
265 | dynamically set based upon license files found in | ||
266 | ``${COMMON_LICENSE_DIR}`` and ``${LICENSE_PATH}``. | ||
267 | |||
268 | - The tune definition for big-endian microblaze machines is now | ||
269 | ``microblaze`` instead of ``microblazeeb``. | ||
270 | |||
271 | - ``newlib`` no longer has built-in syscalls. ``libgloss`` should then | ||
272 | provide the syscalls, ``crt0.o`` and other functions that are no | ||
273 | longer part of ``newlib`` itself. If you are using | ||
274 | ``TCLIBC = "newlib"`` this now means that you must link applications | ||
275 | with both ``newlib`` and ``libgloss``, whereas before ``newlib`` | ||
276 | would run in many configurations by itself. | ||
diff --git a/documentation/ref-manual/migration-general.rst b/documentation/ref-manual/migration-general.rst new file mode 100644 index 0000000000..182482ec43 --- /dev/null +++ b/documentation/ref-manual/migration-general.rst | |||
@@ -0,0 +1,54 @@ | |||
1 | General Migration Considerations | ||
2 | ================================ | ||
3 | |||
4 | Some considerations are not tied to a specific Yocto Project release. | ||
5 | This section presents information you should consider when migrating to | ||
6 | any new Yocto Project release. | ||
7 | |||
8 | - *Dealing with Customized Recipes*: | ||
9 | |||
10 | Issues could arise if you take | ||
11 | older recipes that contain customizations and simply copy them | ||
12 | forward expecting them to work after you migrate to new Yocto Project | ||
13 | metadata. For example, suppose you have a recipe in your layer that | ||
14 | is a customized version of a core recipe copied from the earlier | ||
15 | release, rather than through the use of an append file. When you | ||
16 | migrate to a newer version of Yocto Project, the metadata (e.g. | ||
17 | perhaps an include file used by the recipe) could have changed in a | ||
18 | way that would break the build. Say, for example, a function is | ||
19 | removed from an include file and the customized recipe tries to call | ||
20 | that function. | ||
21 | |||
22 | You could "forward-port" all your customizations in your recipe so | ||
23 | that everything works for the new release. However, this is not the | ||
24 | optimal solution as you would have to repeat this process with each | ||
25 | new release if changes occur that give rise to problems. | ||
26 | |||
27 | The better solution (where practical) is to use append files | ||
28 | (``*.bbappend``) to capture any customizations you want to make to a | ||
29 | recipe. Doing so, isolates your changes from the main recipe making | ||
30 | them much more manageable. However, sometimes it is not practical to | ||
31 | use an append file. A good example of this is when introducing a | ||
32 | newer or older version of a recipe in another layer. | ||
33 | |||
34 | - *Updating Append Files*: | ||
35 | |||
36 | Since append files generally only contain | ||
37 | your customizations, they often do not need to be adjusted for new | ||
38 | releases. However, if the ``.bbappend`` file is specific to a | ||
39 | particular version of the recipe (i.e. its name does not use the % | ||
40 | wildcard) and the version of the recipe to which it is appending has | ||
41 | changed, then you will at a minimum need to rename the append file to | ||
42 | match the name of the recipe file. A mismatch between an append file | ||
43 | and its corresponding recipe file (``.bb``) will trigger an error | ||
44 | during parsing. | ||
45 | |||
46 | Depending on the type of customization the append file applies, other | ||
47 | incompatibilities might occur when you upgrade. For example, if your | ||
48 | append file applies a patch and the recipe to which it is appending | ||
49 | is updated to a newer version, the patch might no longer apply. If | ||
50 | this is the case and assuming the patch is still needed, you must | ||
51 | modify the patch file so that it does apply. | ||
52 | |||
53 | |||
54 | |||
diff --git a/documentation/ref-manual/migration.rst b/documentation/ref-manual/migration.rst new file mode 100644 index 0000000000..6c6119daec --- /dev/null +++ b/documentation/ref-manual/migration.rst | |||
@@ -0,0 +1,30 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ****************************************** | ||
4 | Migrating to a Newer Yocto Project Release | ||
5 | ****************************************** | ||
6 | |||
7 | This chapter provides information you can use to migrate work to a newer | ||
8 | Yocto Project release. You can find the same information in the release | ||
9 | notes for a given release. | ||
10 | |||
11 | .. toctree:: | ||
12 | |||
13 | migration-general | ||
14 | migration-1.3 | ||
15 | migration-1.4 | ||
16 | migration-1.5 | ||
17 | migration-1.6 | ||
18 | migration-1.7 | ||
19 | migration-1.8 | ||
20 | migration-2.0 | ||
21 | migration-2.1 | ||
22 | migration-2.2 | ||
23 | migration-2.3 | ||
24 | migration-2.4 | ||
25 | migration-2.5 | ||
26 | migration-2.6 | ||
27 | migration-2.7 | ||
28 | migration-3.0 | ||
29 | migration-3.1 | ||
30 | |||
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index affc8b90a7..d3d5b16bdd 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='migration'> | 6 | <chapter id='migration'> |
6 | <title>Migrating to a Newer Yocto Project Release</title> | 7 | <title>Migrating to a Newer Yocto Project Release</title> |
diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst new file mode 100644 index 0000000000..60ce8efd21 --- /dev/null +++ b/documentation/ref-manual/ref-classes.rst | |||
@@ -0,0 +1,2963 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******* | ||
4 | Classes | ||
5 | ******* | ||
6 | |||
7 | Class files are used to abstract common functionality and share it | ||
8 | amongst multiple recipe (``.bb``) files. To use a class file, you simply | ||
9 | make sure the recipe inherits the class. In most cases, when a recipe | ||
10 | inherits a class it is enough to enable its features. There are cases, | ||
11 | however, where in the recipe you might need to set variables or override | ||
12 | some default behavior. | ||
13 | |||
14 | Any :term:`Metadata` usually found in a recipe can also be | ||
15 | placed in a class file. Class files are identified by the extension | ||
16 | ``.bbclass`` and are usually placed in a ``classes/`` directory beneath | ||
17 | the ``meta*/`` directory found in the :term:`Source Directory`. | ||
18 | Class files can also be pointed to by | ||
19 | :term:`BUILDDIR` (e.g. ``build/``) in the same way as | ||
20 | ``.conf`` files in the ``conf`` directory. Class files are searched for | ||
21 | in :term:`BBPATH` using the same method by which ``.conf`` | ||
22 | files are searched. | ||
23 | |||
24 | This chapter discusses only the most useful and important classes. Other | ||
25 | classes do exist within the ``meta/classes`` directory in the Source | ||
26 | Directory. You can reference the ``.bbclass`` files directly for more | ||
27 | information. | ||
28 | |||
29 | .. _ref-classes-allarch: | ||
30 | |||
31 | ``allarch.bbclass`` | ||
32 | =================== | ||
33 | |||
34 | The ``allarch`` class is inherited by recipes that do not produce | ||
35 | architecture-specific output. The class disables functionality that is | ||
36 | normally needed for recipes that produce executable binaries (such as | ||
37 | building the cross-compiler and a C library as pre-requisites, and | ||
38 | splitting out of debug symbols during packaging). | ||
39 | |||
40 | .. note:: | ||
41 | |||
42 | Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes that | ||
43 | produce packages that depend on tunings through use of the | ||
44 | :term:`RDEPENDS` and | ||
45 | :term:`TUNE_PKGARCH` variables, should never be | ||
46 | configured for all architectures using ``allarch``. This is the case | ||
47 | even if the recipes do not produce architecture-specific output. | ||
48 | |||
49 | Configuring such recipes for all architectures causes the | ||
50 | ```do_package_write_*`` tasks to | ||
51 | have different signatures for the machines with different tunings. | ||
52 | Additionally, unnecessary rebuilds occur every time an image for a | ||
53 | different ``MACHINE`` is built even when the recipe never changes. | ||
54 | |||
55 | By default, all recipes inherit the :ref:`base <ref-classes-base>` and | ||
56 | :ref:`package <ref-classes-package>` classes, which enable | ||
57 | functionality needed for recipes that produce executable output. If your | ||
58 | recipe, for example, only produces packages that contain configuration | ||
59 | files, media files, or scripts (e.g. Python and Perl), then it should | ||
60 | inherit the ``allarch`` class. | ||
61 | |||
62 | .. _ref-classes-archiver: | ||
63 | |||
64 | ``archiver.bbclass`` | ||
65 | ==================== | ||
66 | |||
67 | The ``archiver`` class supports releasing source code and other | ||
68 | materials with the binaries. | ||
69 | |||
70 | For more details on the source archiver, see the | ||
71 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
72 | section in the Yocto Project Development Tasks Manual. You can also see | ||
73 | the :term:`ARCHIVER_MODE` variable for information | ||
74 | about the variable flags (varflags) that help control archive creation. | ||
75 | |||
76 | .. _ref-classes-autotools: | ||
77 | |||
78 | ``autotools*.bbclass`` | ||
79 | ====================== | ||
80 | |||
81 | The ``autotools*`` classes support Autotooled packages. | ||
82 | |||
83 | The ``autoconf``, ``automake``, and ``libtool`` packages bring | ||
84 | standardization. This class defines a set of tasks (e.g. ``configure``, | ||
85 | ``compile`` and so forth) that work for all Autotooled packages. It | ||
86 | should usually be enough to define a few standard variables and then | ||
87 | simply ``inherit autotools``. These classes can also work with software | ||
88 | that emulates Autotools. For more information, see the | ||
89 | ":ref:`new-recipe-autotooled-package`" section | ||
90 | in the Yocto Project Development Tasks Manual. | ||
91 | |||
92 | By default, the ``autotools*`` classes use out-of-tree builds (i.e. | ||
93 | ``autotools.bbclass`` building with ``B != S``). | ||
94 | |||
95 | If the software being built by a recipe does not support using | ||
96 | out-of-tree builds, you should have the recipe inherit the | ||
97 | ``autotools-brokensep`` class. The ``autotools-brokensep`` class behaves | ||
98 | the same as the ``autotools`` class but builds with :term:`B` | ||
99 | == :term:`S`. This method is useful when out-of-tree build | ||
100 | support is either not present or is broken. | ||
101 | |||
102 | .. note:: | ||
103 | |||
104 | It is recommended that out-of-tree support be fixed and used if at | ||
105 | all possible. | ||
106 | |||
107 | It's useful to have some idea of how the tasks defined by the | ||
108 | ``autotools*`` classes work and what they do behind the scenes. | ||
109 | |||
110 | - :ref:`ref-tasks-configure` - Regenerates the | ||
111 | configure script (using ``autoreconf``) and then launches it with a | ||
112 | standard set of arguments used during cross-compilation. You can pass | ||
113 | additional parameters to ``configure`` through the ``EXTRA_OECONF`` | ||
114 | or :term:`PACKAGECONFIG_CONFARGS` | ||
115 | variables. | ||
116 | |||
117 | - :ref:`ref-tasks-compile` - Runs ``make`` with | ||
118 | arguments that specify the compiler and linker. You can pass | ||
119 | additional arguments through the ``EXTRA_OEMAKE`` variable. | ||
120 | |||
121 | - :ref:`ref-tasks-install` - Runs ``make install`` and | ||
122 | passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``. | ||
123 | |||
124 | .. _ref-classes-base: | ||
125 | |||
126 | ``base.bbclass`` | ||
127 | ================ | ||
128 | |||
129 | The ``base`` class is special in that every ``.bb`` file implicitly | ||
130 | inherits the class. This class contains definitions for standard basic | ||
131 | tasks such as fetching, unpacking, configuring (empty by default), | ||
132 | compiling (runs any ``Makefile`` present), installing (empty by default) | ||
133 | and packaging (empty by default). These classes are often overridden or | ||
134 | extended by other classes such as the | ||
135 | :ref:`autotools <ref-classes-autotools>` class or the | ||
136 | :ref:`package <ref-classes-package>` class. | ||
137 | |||
138 | The class also contains some commonly used functions such as | ||
139 | ``oe_runmake``, which runs ``make`` with the arguments specified in | ||
140 | :term:`EXTRA_OEMAKE` variable as well as the | ||
141 | arguments passed directly to ``oe_runmake``. | ||
142 | |||
143 | .. _ref-classes-bash-completion: | ||
144 | |||
145 | ``bash-completion.bbclass`` | ||
146 | =========================== | ||
147 | |||
148 | Sets up packaging and dependencies appropriate for recipes that build | ||
149 | software that includes bash-completion data. | ||
150 | |||
151 | .. _ref-classes-bin-package: | ||
152 | |||
153 | ``bin_package.bbclass`` | ||
154 | ======================= | ||
155 | |||
156 | The ``bin_package`` class is a helper class for recipes that extract the | ||
157 | contents of a binary package (e.g. an RPM) and install those contents | ||
158 | rather than building the binary from source. The binary package is | ||
159 | extracted and new packages in the configured output package format are | ||
160 | created. Extraction and installation of proprietary binaries is a good | ||
161 | example use for this class. | ||
162 | |||
163 | .. note:: | ||
164 | |||
165 | For RPMs and other packages that do not contain a subdirectory, you | ||
166 | should specify an appropriate fetcher parameter to point to the | ||
167 | subdirectory. For example, if BitBake is using the Git fetcher ( | ||
168 | git:// | ||
169 | ), the "subpath" parameter limits the checkout to a specific subpath | ||
170 | of the tree. Here is an example where | ||
171 | ${BP} | ||
172 | is used so that the files are extracted into the subdirectory | ||
173 | expected by the default value of | ||
174 | S | ||
175 | : | ||
176 | :: | ||
177 | |||
178 | SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" | ||
179 | |||
180 | |||
181 | See the " | ||
182 | Fetchers | ||
183 | " section in the BitBake User Manual for more information on | ||
184 | supported BitBake Fetchers. | ||
185 | |||
186 | .. _ref-classes-binconfig: | ||
187 | |||
188 | ``binconfig.bbclass`` | ||
189 | ===================== | ||
190 | |||
191 | The ``binconfig`` class helps to correct paths in shell scripts. | ||
192 | |||
193 | Before ``pkg-config`` had become widespread, libraries shipped shell | ||
194 | scripts to give information about the libraries and include paths needed | ||
195 | to build software (usually named ``LIBNAME-config``). This class assists | ||
196 | any recipe using such scripts. | ||
197 | |||
198 | During staging, the OpenEmbedded build system installs such scripts into | ||
199 | the ``sysroots/`` directory. Inheriting this class results in all paths | ||
200 | in these scripts being changed to point into the ``sysroots/`` directory | ||
201 | so that all builds that use the script use the correct directories for | ||
202 | the cross compiling layout. See the | ||
203 | :term:`BINCONFIG_GLOB` variable for more | ||
204 | information. | ||
205 | |||
206 | .. _ref-classes-binconfig-disabled: | ||
207 | |||
208 | ``binconfig-disabled.bbclass`` | ||
209 | ============================== | ||
210 | |||
211 | An alternative version of the :ref:`binconfig <ref-classes-binconfig>` | ||
212 | class, which disables binary configuration scripts by making them return | ||
213 | an error in favor of using ``pkg-config`` to query the information. The | ||
214 | scripts to be disabled should be specified using the | ||
215 | :term:`BINCONFIG` variable within the recipe inheriting | ||
216 | the class. | ||
217 | |||
218 | .. _ref-classes-blacklist: | ||
219 | |||
220 | ``blacklist.bbclass`` | ||
221 | ===================== | ||
222 | |||
223 | The ``blacklist`` class prevents the OpenEmbedded build system from | ||
224 | building specific recipes (blacklists them). To use this class, inherit | ||
225 | the class globally and set :term:`PNBLACKLIST` for | ||
226 | each recipe you wish to blacklist. Specify the :term:`PN` | ||
227 | value as a variable flag (varflag) and provide a reason, which is | ||
228 | reported, if the package is requested to be built as the value. For | ||
229 | example, if you want to blacklist a recipe called "exoticware", you add | ||
230 | the following to your ``local.conf`` or distribution configuration: | ||
231 | :: | ||
232 | |||
233 | INHERIT += "blacklist" | ||
234 | PNBLACKLIST[exoticware] = "Not supported by our organization." | ||
235 | |||
236 | .. _ref-classes-buildhistory: | ||
237 | |||
238 | ``buildhistory.bbclass`` | ||
239 | ======================== | ||
240 | |||
241 | The ``buildhistory`` class records a history of build output metadata, | ||
242 | which can be used to detect possible regressions as well as used for | ||
243 | analysis of the build output. For more information on using Build | ||
244 | History, see the | ||
245 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
246 | section in the Yocto Project Development Tasks Manual. | ||
247 | |||
248 | .. _ref-classes-buildstats: | ||
249 | |||
250 | ``buildstats.bbclass`` | ||
251 | ====================== | ||
252 | |||
253 | The ``buildstats`` class records performance statistics about each task | ||
254 | executed during the build (e.g. elapsed time, CPU usage, and I/O usage). | ||
255 | |||
256 | When you use this class, the output goes into the | ||
257 | :term:`BUILDSTATS_BASE` directory, which defaults | ||
258 | to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using | ||
259 | ``scripts/pybootchartgui/pybootchartgui.py``, which produces a cascading | ||
260 | chart of the entire build process and can be useful for highlighting | ||
261 | bottlenecks. | ||
262 | |||
263 | Collecting build statistics is enabled by default through the | ||
264 | :term:`USER_CLASSES` variable from your | ||
265 | ``local.conf`` file. Consequently, you do not have to do anything to | ||
266 | enable the class. However, if you want to disable the class, simply | ||
267 | remove "buildstats" from the ``USER_CLASSES`` list. | ||
268 | |||
269 | .. _ref-classes-buildstats-summary: | ||
270 | |||
271 | ``buildstats-summary.bbclass`` | ||
272 | ============================== | ||
273 | |||
274 | When inherited globally, prints statistics at the end of the build on | ||
275 | sstate re-use. In order to function, this class requires the | ||
276 | :ref:`buildstats <ref-classes-buildstats>` class be enabled. | ||
277 | |||
278 | .. _ref-classes-ccache: | ||
279 | |||
280 | ``ccache.bbclass`` | ||
281 | ================== | ||
282 | |||
283 | The ``ccache`` class enables the C/C++ Compiler Cache for the build. | ||
284 | This class is used to give a minor performance boost during the build. | ||
285 | However, using the class can lead to unexpected side-effects. Thus, it | ||
286 | is recommended that you do not use this class. See | ||
287 | http://ccache.samba.org/ for information on the C/C++ Compiler | ||
288 | Cache. | ||
289 | |||
290 | .. _ref-classes-chrpath: | ||
291 | |||
292 | ``chrpath.bbclass`` | ||
293 | =================== | ||
294 | |||
295 | The ``chrpath`` class is a wrapper around the "chrpath" utility, which | ||
296 | is used during the build process for ``nativesdk``, ``cross``, and | ||
297 | ``cross-canadian`` recipes to change ``RPATH`` records within binaries | ||
298 | in order to make them relocatable. | ||
299 | |||
300 | .. _ref-classes-clutter: | ||
301 | |||
302 | ``clutter.bbclass`` | ||
303 | =================== | ||
304 | |||
305 | The ``clutter`` class consolidates the major and minor version naming | ||
306 | and other common items used by Clutter and related recipes. | ||
307 | |||
308 | .. note:: | ||
309 | |||
310 | Unlike some other classes related to specific libraries, recipes | ||
311 | building other software that uses Clutter do not need to inherit this | ||
312 | class unless they use the same recipe versioning scheme that the | ||
313 | Clutter and related recipes do. | ||
314 | |||
315 | .. _ref-classes-cmake: | ||
316 | |||
317 | ``cmake.bbclass`` | ||
318 | ================= | ||
319 | |||
320 | The ``cmake`` class allows for recipes that need to build software using | ||
321 | the `CMake <https://cmake.org/overview/>`__ build system. You can use | ||
322 | the :term:`EXTRA_OECMAKE` variable to specify | ||
323 | additional configuration options to be passed using the ``cmake`` | ||
324 | command line. | ||
325 | |||
326 | On the occasion that you would be installing custom CMake toolchain | ||
327 | files supplied by the application being built, you should install them | ||
328 | to the preferred CMake Module directory: ``${D}${datadir}/cmake/`` | ||
329 | Modules during | ||
330 | :ref:`ref-tasks-install`. | ||
331 | |||
332 | .. _ref-classes-cml1: | ||
333 | |||
334 | ``cml1.bbclass`` | ||
335 | ================ | ||
336 | |||
337 | The ``cml1`` class provides basic support for the Linux kernel style | ||
338 | build configuration system. | ||
339 | |||
340 | .. _ref-classes-compress_doc: | ||
341 | |||
342 | ``compress_doc.bbclass`` | ||
343 | ======================== | ||
344 | |||
345 | Enables compression for man pages and info pages. This class is intended | ||
346 | to be inherited globally. The default compression mechanism is gz (gzip) | ||
347 | but you can select an alternative mechanism by setting the | ||
348 | :term:`DOC_COMPRESS` variable. | ||
349 | |||
350 | .. _ref-classes-copyleft_compliance: | ||
351 | |||
352 | ``copyleft_compliance.bbclass`` | ||
353 | =============================== | ||
354 | |||
355 | The ``copyleft_compliance`` class preserves source code for the purposes | ||
356 | of license compliance. This class is an alternative to the ``archiver`` | ||
357 | class and is still used by some users even though it has been deprecated | ||
358 | in favor of the :ref:`archiver <ref-classes-archiver>` class. | ||
359 | |||
360 | .. _ref-classes-copyleft_filter: | ||
361 | |||
362 | ``copyleft_filter.bbclass`` | ||
363 | =========================== | ||
364 | |||
365 | A class used by the :ref:`archiver <ref-classes-archiver>` and | ||
366 | :ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes | ||
367 | for filtering licenses. The ``copyleft_filter`` class is an internal | ||
368 | class and is not intended to be used directly. | ||
369 | |||
370 | .. _ref-classes-core-image: | ||
371 | |||
372 | ``core-image.bbclass`` | ||
373 | ====================== | ||
374 | |||
375 | The ``core-image`` class provides common definitions for the | ||
376 | ``core-image-*`` image recipes, such as support for additional | ||
377 | :term:`IMAGE_FEATURES`. | ||
378 | |||
379 | .. _ref-classes-cpan: | ||
380 | |||
381 | ``cpan*.bbclass`` | ||
382 | ================= | ||
383 | |||
384 | The ``cpan*`` classes support Perl modules. | ||
385 | |||
386 | Recipes for Perl modules are simple. These recipes usually only need to | ||
387 | point to the source's archive and then inherit the proper class file. | ||
388 | Building is split into two methods depending on which method the module | ||
389 | authors used. | ||
390 | |||
391 | - Modules that use old ``Makefile.PL``-based build system require | ||
392 | ``cpan.bbclass`` in their recipes. | ||
393 | |||
394 | - Modules that use ``Build.PL``-based build system require using | ||
395 | ``cpan_build.bbclass`` in their recipes. | ||
396 | |||
397 | Both build methods inherit the ``cpan-base`` class for basic Perl | ||
398 | support. | ||
399 | |||
400 | .. _ref-classes-cross: | ||
401 | |||
402 | ``cross.bbclass`` | ||
403 | ================= | ||
404 | |||
405 | The ``cross`` class provides support for the recipes that build the | ||
406 | cross-compilation tools. | ||
407 | |||
408 | .. _ref-classes-cross-canadian: | ||
409 | |||
410 | ``cross-canadian.bbclass`` | ||
411 | ========================== | ||
412 | |||
413 | The ``cross-canadian`` class provides support for the recipes that build | ||
414 | the Canadian Cross-compilation tools for SDKs. See the | ||
415 | ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" | ||
416 | section in the Yocto Project Overview and Concepts Manual for more | ||
417 | discussion on these cross-compilation tools. | ||
418 | |||
419 | .. _ref-classes-crosssdk: | ||
420 | |||
421 | ``crosssdk.bbclass`` | ||
422 | ==================== | ||
423 | |||
424 | The ``crosssdk`` class provides support for the recipes that build the | ||
425 | cross-compilation tools used for building SDKs. See the | ||
426 | ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" | ||
427 | section in the Yocto Project Overview and Concepts Manual for more | ||
428 | discussion on these cross-compilation tools. | ||
429 | |||
430 | .. _ref-classes-debian: | ||
431 | |||
432 | ``debian.bbclass`` | ||
433 | ================== | ||
434 | |||
435 | The ``debian`` class renames output packages so that they follow the | ||
436 | Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and | ||
437 | ``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library | ||
438 | name and version as part of the package name. | ||
439 | |||
440 | If a recipe creates packages for multiple libraries (shared object files | ||
441 | of ``.so`` type), use the :term:`LEAD_SONAME` | ||
442 | variable in the recipe to specify the library on which to apply the | ||
443 | naming scheme. | ||
444 | |||
445 | .. _ref-classes-deploy: | ||
446 | |||
447 | ``deploy.bbclass`` | ||
448 | ================== | ||
449 | |||
450 | The ``deploy`` class handles deploying files to the | ||
451 | :term:`DEPLOY_DIR_IMAGE` directory. The main | ||
452 | function of this class is to allow the deploy step to be accelerated by | ||
453 | shared state. Recipes that inherit this class should define their own | ||
454 | :ref:`ref-tasks-deploy` function to copy the files to be | ||
455 | deployed to :term:`DEPLOYDIR`, and use ``addtask`` to | ||
456 | add the task at the appropriate place, which is usually after | ||
457 | :ref:`ref-tasks-compile` or | ||
458 | :ref:`ref-tasks-install`. The class then takes care of | ||
459 | staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``. | ||
460 | |||
461 | .. _ref-classes-devshell: | ||
462 | |||
463 | ``devshell.bbclass`` | ||
464 | ==================== | ||
465 | |||
466 | The ``devshell`` class adds the ``do_devshell`` task. Distribution | ||
467 | policy dictates whether to include this class. See the ":ref:`platdev-appdev-devshell`" | ||
468 | section in the Yocto Project Development Tasks Manual for more | ||
469 | information about using ``devshell``. | ||
470 | |||
471 | .. _ref-classes-devupstream: | ||
472 | |||
473 | ``devupstream.bbclass`` | ||
474 | ======================= | ||
475 | |||
476 | The ``devupstream`` class uses | ||
477 | :term:`BBCLASSEXTEND` to add a variant of the | ||
478 | recipe that fetches from an alternative URI (e.g. Git) instead of a | ||
479 | tarball. Following is an example: | ||
480 | :: | ||
481 | |||
482 | BBCLASSEXTEND = "devupstream:target" | ||
483 | SRC_URI_class-devupstream = "git://git.example.com/example" | ||
484 | SRCREV_class-devupstream = "abcd1234" | ||
485 | |||
486 | Adding the above statements to your recipe creates a variant that has | ||
487 | :term:`DEFAULT_PREFERENCE` set to "-1". | ||
488 | Consequently, you need to select the variant of the recipe to use it. | ||
489 | Any development-specific adjustments can be done by using the | ||
490 | ``class-devupstream`` override. Here is an example: | ||
491 | :: | ||
492 | |||
493 | DEPENDS_append_class-devupstream = " gperf-native" | ||
494 | do_configure_prepend_class-devupstream() { | ||
495 | touch ${S}/README | ||
496 | } | ||
497 | |||
498 | The class | ||
499 | currently only supports creating a development variant of the target | ||
500 | recipe, not ``native`` or ``nativesdk`` variants. | ||
501 | |||
502 | The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides | ||
503 | support for ``native`` and ``nativesdk`` variants. Consequently, this | ||
504 | functionality can be added in a future release. | ||
505 | |||
506 | Support for other version control systems such as Subversion is limited | ||
507 | due to BitBake's automatic fetch dependencies (e.g. | ||
508 | ``subversion-native``). | ||
509 | |||
510 | .. _ref-classes-distro_features_check: | ||
511 | |||
512 | ``distro_features_check.bbclass`` | ||
513 | ================================= | ||
514 | |||
515 | The ``distro_features_check`` class allows individual recipes to check | ||
516 | for required and conflicting | ||
517 | :term:`DISTRO_FEATURES`. | ||
518 | |||
519 | This class provides support for the | ||
520 | :term:`REQUIRED_DISTRO_FEATURES` and | ||
521 | :term:`CONFLICT_DISTRO_FEATURES` | ||
522 | variables. If any conditions specified in the recipe using the above | ||
523 | variables are not met, the recipe will be skipped. | ||
524 | |||
525 | .. _ref-classes-distutils: | ||
526 | |||
527 | ``distutils*.bbclass`` | ||
528 | ====================== | ||
529 | |||
530 | The ``distutils*`` classes support recipes for Python version 2.x | ||
531 | extensions, which are simple. These recipes usually only need to point | ||
532 | to the source's archive and then inherit the proper class. Building is | ||
533 | split into two methods depending on which method the module authors | ||
534 | used. | ||
535 | |||
536 | - Extensions that use an Autotools-based build system require Autotools | ||
537 | and the classes based on ``distutils`` in their recipes. | ||
538 | |||
539 | - Extensions that use build systems based on ``distutils`` require the | ||
540 | ``distutils`` class in their recipes. | ||
541 | |||
542 | - Extensions that use build systems based on ``setuptools`` require the | ||
543 | :ref:`setuptools <ref-classes-setuptools>` class in their recipes. | ||
544 | |||
545 | The ``distutils-common-base`` class is required by some of the | ||
546 | ``distutils*`` classes to provide common Python2 support. | ||
547 | |||
548 | .. _ref-classes-distutils3: | ||
549 | |||
550 | ``distutils3*.bbclass`` | ||
551 | ======================= | ||
552 | |||
553 | The ``distutils3*`` classes support recipes for Python version 3.x | ||
554 | extensions, which are simple. These recipes usually only need to point | ||
555 | to the source's archive and then inherit the proper class. Building is | ||
556 | split into three methods depending on which method the module authors | ||
557 | used. | ||
558 | |||
559 | - Extensions that use an Autotools-based build system require Autotools | ||
560 | and ``distutils``-based classes in their recipes. | ||
561 | |||
562 | - Extensions that use ``distutils``-based build systems require the | ||
563 | ``distutils`` class in their recipes. | ||
564 | |||
565 | - Extensions that use build systems based on ``setuptools3`` require | ||
566 | the :ref:`setuptools3 <ref-classes-setuptools>` class in their | ||
567 | recipes. | ||
568 | |||
569 | The ``distutils3*`` classes either inherit their corresponding | ||
570 | ``distutils*`` class or replicate them using a Python3 version instead | ||
571 | (e.g. ``distutils3-base`` inherits ``distutils-common-base``, which is | ||
572 | the same as ``distutils-base`` but inherits ``python3native`` instead of | ||
573 | ``pythonnative``). | ||
574 | |||
575 | .. _ref-classes-externalsrc: | ||
576 | |||
577 | ``externalsrc.bbclass`` | ||
578 | ======================= | ||
579 | |||
580 | The ``externalsrc`` class supports building software from source code | ||
581 | that is external to the OpenEmbedded build system. Building software | ||
582 | from an external source tree means that the build system's normal fetch, | ||
583 | unpack, and patch process is not used. | ||
584 | |||
585 | By default, the OpenEmbedded build system uses the :term:`S` | ||
586 | and :term:`B` variables to locate unpacked recipe source code | ||
587 | and to build it, respectively. When your recipe inherits the | ||
588 | ``externalsrc`` class, you use the | ||
589 | :term:`EXTERNALSRC` and | ||
590 | :term:`EXTERNALSRC_BUILD` variables to | ||
591 | ultimately define ``S`` and ``B``. | ||
592 | |||
593 | By default, this class expects the source code to support recipe builds | ||
594 | that use the :term:`B` variable to point to the directory in | ||
595 | which the OpenEmbedded build system places the generated objects built | ||
596 | from the recipes. By default, the ``B`` directory is set to the | ||
597 | following, which is separate from the source directory (``S``): | ||
598 | :: | ||
599 | |||
600 | ${WORKDIR}/${BPN}/{PV}/ | ||
601 | |||
602 | See these variables for more information: | ||
603 | :term:`WORKDIR`, :term:`BPN`, and | ||
604 | :term:`PV`, | ||
605 | |||
606 | For more information on the ``externalsrc`` class, see the comments in | ||
607 | ``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. | ||
608 | For information on how to use the | ||
609 | ``externalsrc`` class, see the | ||
610 | ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" | ||
611 | section in the Yocto Project Development Tasks Manual. | ||
612 | |||
613 | .. _ref-classes-extrausers: | ||
614 | |||
615 | ``extrausers.bbclass`` | ||
616 | ====================== | ||
617 | |||
618 | The ``extrausers`` class allows additional user and group configuration | ||
619 | to be applied at the image level. Inheriting this class either globally | ||
620 | or from an image recipe allows additional user and group operations to | ||
621 | be performed using the | ||
622 | :term:`EXTRA_USERS_PARAMS` variable. | ||
623 | |||
624 | .. note:: | ||
625 | |||
626 | The user and group operations added using the | ||
627 | extrausers | ||
628 | class are not tied to a specific recipe outside of the recipe for the | ||
629 | image. Thus, the operations can be performed across the image as a | ||
630 | whole. Use the | ||
631 | useradd | ||
632 | class to add user and group configuration to a specific recipe. | ||
633 | |||
634 | Here is an example that uses this class in an image recipe: | ||
635 | :: | ||
636 | |||
637 | inherit extrausers | ||
638 | EXTRA_USERS_PARAMS = "\ | ||
639 | useradd -p '' tester; \ | ||
640 | groupadd developers; \ | ||
641 | userdel nobody; \ | ||
642 | groupdel -g video; \ | ||
643 | groupmod -g 1020 developers; \ | ||
644 | usermod -s /bin/sh tester; \ | ||
645 | " | ||
646 | |||
647 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns | ||
648 | passwords: | ||
649 | :: | ||
650 | |||
651 | inherit extrausers | ||
652 | EXTRA_USERS_PARAMS = "\ | ||
653 | useradd -P tester01 tester-jim; \ | ||
654 | useradd -P tester01 tester-sue; \ | ||
655 | " | ||
656 | |||
657 | Finally, 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 | " | ||
664 | |||
665 | .. _ref-classes-fontcache: | ||
666 | |||
667 | ``fontcache.bbclass`` | ||
668 | ===================== | ||
669 | |||
670 | The ``fontcache`` class generates the proper post-install and | ||
671 | post-remove (postinst and postrm) scriptlets for font packages. These | ||
672 | scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts | ||
673 | to the font information cache. Since the cache files are | ||
674 | architecture-specific, ``fc-cache`` runs using QEMU if the postinst | ||
675 | scriptlets need to be run on the build host during image creation. | ||
676 | |||
677 | If the fonts being installed are in packages other than the main | ||
678 | package, set :term:`FONT_PACKAGES` to specify the | ||
679 | packages containing the fonts. | ||
680 | |||
681 | .. _ref-classes-fs-uuid: | ||
682 | |||
683 | ``fs-uuid.bbclass`` | ||
684 | =================== | ||
685 | |||
686 | The ``fs-uuid`` class extracts UUID from | ||
687 | ``${``\ :term:`ROOTFS`\ ``}``, which must have been built | ||
688 | by the time that this function gets called. The ``fs-uuid`` class only | ||
689 | works on ``ext`` file systems and depends on ``tune2fs``. | ||
690 | |||
691 | .. _ref-classes-gconf: | ||
692 | |||
693 | ``gconf.bbclass`` | ||
694 | ================= | ||
695 | |||
696 | The ``gconf`` class provides common functionality for recipes that need | ||
697 | to install GConf schemas. The schemas will be put into a separate | ||
698 | package (``${``\ :term:`PN`\ ``}-gconf``) that is created | ||
699 | automatically when this class is inherited. This package uses the | ||
700 | appropriate post-install and post-remove (postinst/postrm) scriptlets to | ||
701 | register and unregister the schemas in the target image. | ||
702 | |||
703 | .. _ref-classes-gettext: | ||
704 | |||
705 | ``gettext.bbclass`` | ||
706 | =================== | ||
707 | |||
708 | The ``gettext`` class provides support for building software that uses | ||
709 | the GNU ``gettext`` internationalization and localization system. All | ||
710 | recipes building software that use ``gettext`` should inherit this | ||
711 | class. | ||
712 | |||
713 | .. _ref-classes-gnomebase: | ||
714 | |||
715 | ``gnomebase.bbclass`` | ||
716 | ===================== | ||
717 | |||
718 | The ``gnomebase`` class is the base class for recipes that build | ||
719 | software from the GNOME stack. This class sets | ||
720 | :term:`SRC_URI` to download the source from the GNOME | ||
721 | mirrors as well as extending :term:`FILES` with the typical | ||
722 | GNOME installation paths. | ||
723 | |||
724 | .. _ref-classes-gobject-introspection: | ||
725 | |||
726 | ``gobject-introspection.bbclass`` | ||
727 | ================================= | ||
728 | |||
729 | Provides support for recipes building software that supports GObject | ||
730 | introspection. This functionality is only enabled if the | ||
731 | "gobject-introspection-data" feature is in | ||
732 | :term:`DISTRO_FEATURES` as well as | ||
733 | "qemu-usermode" being in | ||
734 | :term:`MACHINE_FEATURES`. | ||
735 | |||
736 | .. note:: | ||
737 | |||
738 | This functionality is backfilled by default and, if not applicable, | ||
739 | should be disabled through | ||
740 | DISTRO_FEATURES_BACKFILL_CONSIDERED | ||
741 | or | ||
742 | MACHINE_FEATURES_BACKFILL_CONSIDERED | ||
743 | , respectively. | ||
744 | |||
745 | .. _ref-classes-grub-efi: | ||
746 | |||
747 | ``grub-efi.bbclass`` | ||
748 | ==================== | ||
749 | |||
750 | The ``grub-efi`` class provides ``grub-efi``-specific functions for | ||
751 | building bootable images. | ||
752 | |||
753 | This class supports several variables: | ||
754 | |||
755 | - :term:`INITRD`: Indicates list of filesystem images to | ||
756 | concatenate and use as an initial RAM disk (initrd) (optional). | ||
757 | |||
758 | - :term:`ROOTFS`: Indicates a filesystem image to include | ||
759 | as the root filesystem (optional). | ||
760 | |||
761 | - :term:`GRUB_GFXSERIAL`: Set this to "1" to have | ||
762 | graphics and serial in the boot menu. | ||
763 | |||
764 | - :term:`LABELS`: A list of targets for the automatic | ||
765 | configuration. | ||
766 | |||
767 | - :term:`APPEND`: An override list of append strings for | ||
768 | each ``LABEL``. | ||
769 | |||
770 | - :term:`GRUB_OPTS`: Additional options to add to the | ||
771 | configuration (optional). Options are delimited using semi-colon | ||
772 | characters (``;``). | ||
773 | |||
774 | - :term:`GRUB_TIMEOUT`: Timeout before executing | ||
775 | the default ``LABEL`` (optional). | ||
776 | |||
777 | .. _ref-classes-gsettings: | ||
778 | |||
779 | ``gsettings.bbclass`` | ||
780 | ===================== | ||
781 | |||
782 | The ``gsettings`` class provides common functionality for recipes that | ||
783 | need to install GSettings (glib) schemas. The schemas are assumed to be | ||
784 | part of the main package. Appropriate post-install and post-remove | ||
785 | (postinst/postrm) scriptlets are added to register and unregister the | ||
786 | schemas in the target image. | ||
787 | |||
788 | .. _ref-classes-gtk-doc: | ||
789 | |||
790 | ``gtk-doc.bbclass`` | ||
791 | =================== | ||
792 | |||
793 | The ``gtk-doc`` class is a helper class to pull in the appropriate | ||
794 | ``gtk-doc`` dependencies and disable ``gtk-doc``. | ||
795 | |||
796 | .. _ref-classes-gtk-icon-cache: | ||
797 | |||
798 | ``gtk-icon-cache.bbclass`` | ||
799 | ========================== | ||
800 | |||
801 | The ``gtk-icon-cache`` class generates the proper post-install and | ||
802 | post-remove (postinst/postrm) scriptlets for packages that use GTK+ and | ||
803 | install icons. These scriptlets call ``gtk-update-icon-cache`` to add | ||
804 | the fonts to GTK+'s icon cache. Since the cache files are | ||
805 | architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if | ||
806 | the postinst scriptlets need to be run on the build host during image | ||
807 | creation. | ||
808 | |||
809 | .. _ref-classes-gtk-immodules-cache: | ||
810 | |||
811 | ``gtk-immodules-cache.bbclass`` | ||
812 | =============================== | ||
813 | |||
814 | The ``gtk-immodules-cache`` class generates the proper post-install and | ||
815 | post-remove (postinst/postrm) scriptlets for packages that install GTK+ | ||
816 | input method modules for virtual keyboards. These scriptlets call | ||
817 | ``gtk-update-icon-cache`` to add the input method modules to the cache. | ||
818 | Since the cache files are architecture-specific, | ||
819 | ``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets | ||
820 | need to be run on the build host during image creation. | ||
821 | |||
822 | If the input method modules being installed are in packages other than | ||
823 | the main package, set | ||
824 | :term:`GTKIMMODULES_PACKAGES` to specify | ||
825 | the packages containing the modules. | ||
826 | |||
827 | .. _ref-classes-gzipnative: | ||
828 | |||
829 | ``gzipnative.bbclass`` | ||
830 | ====================== | ||
831 | |||
832 | The ``gzipnative`` class enables the use of different native versions of | ||
833 | ``gzip`` and ``pigz`` rather than the versions of these tools from the | ||
834 | build host. | ||
835 | |||
836 | .. _ref-classes-icecc: | ||
837 | |||
838 | ``icecc.bbclass`` | ||
839 | ================= | ||
840 | |||
841 | The ``icecc`` class supports | ||
842 | `Icecream <https://github.com/icecc/icecream>`__, which facilitates | ||
843 | taking compile jobs and distributing them among remote machines. | ||
844 | |||
845 | The class stages directories with symlinks from ``gcc`` and ``g++`` to | ||
846 | ``icecc``, for both native and cross compilers. Depending on each | ||
847 | configure or compile, the OpenEmbedded build system adds the directories | ||
848 | at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and | ||
849 | ``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc`` | ||
850 | compilers, respectively. | ||
851 | |||
852 | For the cross compiler, the class creates a ``tar.gz`` file that | ||
853 | contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which | ||
854 | is the version of the cross-compiler used in the cross-development | ||
855 | toolchain, accordingly. | ||
856 | |||
857 | The class handles all three different compile stages (i.e native | ||
858 | ,cross-kernel and target) and creates the necessary environment | ||
859 | ``tar.gz`` file to be used by the remote machines. The class also | ||
860 | supports SDK generation. | ||
861 | |||
862 | If :term:`ICECC_PATH` is not set in your | ||
863 | ``local.conf`` file, then the class tries to locate the ``icecc`` binary | ||
864 | using ``which``. If :term:`ICECC_ENV_EXEC` is set | ||
865 | in your ``local.conf`` file, the variable should point to the | ||
866 | ``icecc-create-env`` script provided by the user. If you do not point to | ||
867 | a user-provided script, the build system uses the default script | ||
868 | provided by the recipe ``icecc-create-env-native.bb``. | ||
869 | |||
870 | .. note:: | ||
871 | |||
872 | This script is a modified version and not the one that comes with | ||
873 | icecc. | ||
874 | |||
875 | If you do not want the Icecream distributed compile support to apply to | ||
876 | specific recipes or classes, you can effectively "blacklist" them by | ||
877 | listing the recipes and classes using the | ||
878 | :term:`ICECC_USER_PACKAGE_BL` and | ||
879 | :term:`ICECC_USER_CLASS_BL`, variables, | ||
880 | respectively, in your ``local.conf`` file. Doing so causes the | ||
881 | OpenEmbedded build system to handle these compilations locally. | ||
882 | |||
883 | Additionally, you can list recipes using the | ||
884 | :term:`ICECC_USER_PACKAGE_WL` variable in | ||
885 | your ``local.conf`` file to force ``icecc`` to be enabled for recipes | ||
886 | using an empty :term:`PARALLEL_MAKE` variable. | ||
887 | |||
888 | Inheriting the ``icecc`` class changes all sstate signatures. | ||
889 | Consequently, if a development team has a dedicated build system that | ||
890 | populates :term:`SSTATE_MIRRORS` and they want to | ||
891 | reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build | ||
892 | system need to either inherit the ``icecc`` class or nobody should. | ||
893 | |||
894 | At the distribution level, you can inherit the ``icecc`` class to be | ||
895 | sure that all builders start with the same sstate signatures. After | ||
896 | inheriting the class, you can then disable the feature by setting the | ||
897 | :term:`ICECC_DISABLED` variable to "1" as follows: | ||
898 | :: | ||
899 | |||
900 | INHERIT_DISTRO_append = " icecc" | ||
901 | ICECC_DISABLED ??= "1" | ||
902 | |||
903 | This practice | ||
904 | makes sure everyone is using the same signatures but also requires | ||
905 | individuals that do want to use Icecream to enable the feature | ||
906 | individually as follows in your ``local.conf`` file: | ||
907 | :: | ||
908 | |||
909 | ICECC_DISABLED = "" | ||
910 | |||
911 | .. _ref-classes-image: | ||
912 | |||
913 | ``image.bbclass`` | ||
914 | ================= | ||
915 | |||
916 | The ``image`` class helps support creating images in different formats. | ||
917 | First, the root filesystem is created from packages using one of the | ||
918 | ``rootfs*.bbclass`` files (depending on the package format used) and | ||
919 | then one or more image files are created. | ||
920 | |||
921 | - The ``IMAGE_FSTYPES`` variable controls the types of images to | ||
922 | generate. | ||
923 | |||
924 | - The ``IMAGE_INSTALL`` variable controls the list of packages to | ||
925 | install into the image. | ||
926 | |||
927 | For information on customizing images, see the | ||
928 | ":ref:`usingpoky-extend-customimage`" section | ||
929 | in the Yocto Project Development Tasks Manual. For information on how | ||
930 | images are created, see the | ||
931 | ":ref:`images-dev-environment`" section in the | ||
932 | Yocto Project Overview and Concpets Manual. | ||
933 | |||
934 | .. _ref-classes-image-buildinfo: | ||
935 | |||
936 | ``image-buildinfo.bbclass`` | ||
937 | =========================== | ||
938 | |||
939 | The ``image-buildinfo`` class writes information to the target | ||
940 | filesystem on ``/etc/build``. | ||
941 | |||
942 | .. _ref-classes-image_types: | ||
943 | |||
944 | ``image_types.bbclass`` | ||
945 | ======================= | ||
946 | |||
947 | The ``image_types`` class defines all of the standard image output types | ||
948 | that you can enable through the | ||
949 | :term:`IMAGE_FSTYPES` variable. You can use this | ||
950 | class as a reference on how to add support for custom image output | ||
951 | types. | ||
952 | |||
953 | By default, the :ref:`image <ref-classes-image>` class automatically | ||
954 | enables the ``image_types`` class. The ``image`` class uses the | ||
955 | ``IMGCLASSES`` variable as follows: | ||
956 | :: | ||
957 | |||
958 | IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" | ||
959 | IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}" | ||
960 | IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}" | ||
961 | IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}" | ||
962 | IMGCLASSES += "image_types_wic" | ||
963 | IMGCLASSES += "rootfs-postcommands" | ||
964 | IMGCLASSES += "image-postinst-intercepts" | ||
965 | inherit ${IMGCLASSES} | ||
966 | |||
967 | The ``image_types`` class also handles conversion and compression of images. | ||
968 | |||
969 | .. note:: | ||
970 | |||
971 | To build a VMware VMDK image, you need to add "wic.vmdk" to | ||
972 | IMAGE_FSTYPES | ||
973 | . This would also be similar for Virtual Box Virtual Disk Image | ||
974 | ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images. | ||
975 | |||
976 | .. _ref-classes-image-live: | ||
977 | |||
978 | ``image-live.bbclass`` | ||
979 | ====================== | ||
980 | |||
981 | This class controls building "live" (i.e. HDDIMG and ISO) images. Live | ||
982 | images contain syslinux for legacy booting, as well as the bootloader | ||
983 | specified by :term:`EFI_PROVIDER` if | ||
984 | :term:`MACHINE_FEATURES` contains "efi". | ||
985 | |||
986 | Normally, you do not use this class directly. Instead, you add "live" to | ||
987 | :term:`IMAGE_FSTYPES`. | ||
988 | |||
989 | .. _ref-classes-image-mklibs: | ||
990 | |||
991 | ``image-mklibs.bbclass`` | ||
992 | ======================== | ||
993 | |||
994 | The ``image-mklibs`` class enables the use of the ``mklibs`` utility | ||
995 | during the :ref:`ref-tasks-rootfs` task, which optimizes | ||
996 | the size of libraries contained in the image. | ||
997 | |||
998 | By default, the class is enabled in the ``local.conf.template`` using | ||
999 | the :term:`USER_CLASSES` variable as follows: | ||
1000 | :: | ||
1001 | |||
1002 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | ||
1003 | |||
1004 | .. _ref-classes-image-prelink: | ||
1005 | |||
1006 | ``image-prelink.bbclass`` | ||
1007 | ========================= | ||
1008 | |||
1009 | The ``image-prelink`` class enables the use of the ``prelink`` utility | ||
1010 | during the :ref:`ref-tasks-rootfs` task, which optimizes | ||
1011 | the dynamic linking of shared libraries to reduce executable startup | ||
1012 | time. | ||
1013 | |||
1014 | By default, the class is enabled in the ``local.conf.template`` using | ||
1015 | the :term:`USER_CLASSES` variable as follows: | ||
1016 | :: | ||
1017 | |||
1018 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | ||
1019 | |||
1020 | .. _ref-classes-insane: | ||
1021 | |||
1022 | ``insane.bbclass`` | ||
1023 | ================== | ||
1024 | |||
1025 | The ``insane`` class adds a step to the package generation process so | ||
1026 | that output quality assurance checks are generated by the OpenEmbedded | ||
1027 | build system. A range of checks are performed that check the build's | ||
1028 | output for common problems that show up during runtime. Distribution | ||
1029 | policy usually dictates whether to include this class. | ||
1030 | |||
1031 | You can configure the sanity checks so that specific test failures | ||
1032 | either raise a warning or an error message. Typically, failures for new | ||
1033 | tests generate a warning. Subsequent failures for the same test would | ||
1034 | then generate an error message once the metadata is in a known and good | ||
1035 | condition. See the "`QA Error and Warning Messages <#ref-qa-checks>`__" | ||
1036 | Chapter for a list of all the warning and error messages you might | ||
1037 | encounter using a default configuration. | ||
1038 | |||
1039 | Use the :term:`WARN_QA` and | ||
1040 | :term:`ERROR_QA` variables to control the behavior of | ||
1041 | these checks at the global level (i.e. in your custom distro | ||
1042 | configuration). However, to skip one or more checks in recipes, you | ||
1043 | should use :term:`INSANE_SKIP`. For example, to skip | ||
1044 | the check for symbolic link ``.so`` files in the main package of a | ||
1045 | recipe, add the following to the recipe. You need to realize that the | ||
1046 | package name override, in this example ``${PN}``, must be used: | ||
1047 | :: | ||
1048 | |||
1049 | INSANE_SKIP_${PN} += "dev-so" | ||
1050 | |||
1051 | Please keep in mind that the QA checks | ||
1052 | exist in order to detect real or potential problems in the packaged | ||
1053 | output. So exercise caution when disabling these checks. | ||
1054 | |||
1055 | The following list shows the tests you can list with the ``WARN_QA`` and | ||
1056 | ``ERROR_QA`` variables: | ||
1057 | |||
1058 | - ``already-stripped:`` Checks that produced binaries have not | ||
1059 | already been stripped prior to the build system extracting debug | ||
1060 | symbols. It is common for upstream software projects to default to | ||
1061 | stripping debug symbols for output binaries. In order for debugging | ||
1062 | to work on the target using ``-dbg`` packages, this stripping must be | ||
1063 | disabled. | ||
1064 | |||
1065 | - ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit | ||
1066 | size, and endianness of any binaries to ensure they match the target | ||
1067 | architecture. This test fails if any binaries do not match the type | ||
1068 | since there would be an incompatibility. The test could indicate that | ||
1069 | the wrong compiler or compiler options have been used. Sometimes | ||
1070 | software, like bootloaders, might need to bypass this check. | ||
1071 | |||
1072 | - ``buildpaths:`` Checks for paths to locations on the build host | ||
1073 | inside the output files. Currently, this test triggers too many false | ||
1074 | positives and thus is not normally enabled. | ||
1075 | |||
1076 | - ``build-deps:`` Determines if a build-time dependency that is | ||
1077 | specified through :term:`DEPENDS`, explicit | ||
1078 | :term:`RDEPENDS`, or task-level dependencies exists | ||
1079 | to match any runtime dependency. This determination is particularly | ||
1080 | useful to discover where runtime dependencies are detected and added | ||
1081 | during packaging. If no explicit dependency has been specified within | ||
1082 | the metadata, at the packaging stage it is too late to ensure that | ||
1083 | the dependency is built, and thus you can end up with an error when | ||
1084 | the package is installed into the image during the | ||
1085 | :ref:`ref-tasks-rootfs` task because the auto-detected | ||
1086 | dependency was not satisfied. An example of this would be where the | ||
1087 | :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically | ||
1088 | adds a dependency on the ``initscripts-functions`` package to | ||
1089 | packages that install an initscript that refers to | ||
1090 | ``/etc/init.d/functions``. The recipe should really have an explicit | ||
1091 | ``RDEPENDS`` for the package in question on ``initscripts-functions`` | ||
1092 | so that the OpenEmbedded build system is able to ensure that the | ||
1093 | ``initscripts`` recipe is actually built and thus the | ||
1094 | ``initscripts-functions`` package is made available. | ||
1095 | |||
1096 | - ``compile-host-path:`` Checks the | ||
1097 | :ref:`ref-tasks-compile` log for indications that | ||
1098 | paths to locations on the build host were used. Using such paths | ||
1099 | might result in host contamination of the build output. | ||
1100 | |||
1101 | - ``debug-deps:`` Checks that all packages except ``-dbg`` packages | ||
1102 | do not depend on ``-dbg`` packages, which would cause a packaging | ||
1103 | bug. | ||
1104 | |||
1105 | - ``debug-files:`` Checks for ``.debug`` directories in anything but | ||
1106 | the ``-dbg`` package. The debug files should all be in the ``-dbg`` | ||
1107 | package. Thus, anything packaged elsewhere is incorrect packaging. | ||
1108 | |||
1109 | - ``dep-cmp:`` Checks for invalid version comparison statements in | ||
1110 | runtime dependency relationships between packages (i.e. in | ||
1111 | :term:`RDEPENDS`, | ||
1112 | :term:`RRECOMMENDS`, | ||
1113 | :term:`RSUGGESTS`, | ||
1114 | :term:`RPROVIDES`, | ||
1115 | :term:`RREPLACES`, and | ||
1116 | :term:`RCONFLICTS` variable values). Any invalid | ||
1117 | comparisons might trigger failures or undesirable behavior when | ||
1118 | passed to the package manager. | ||
1119 | |||
1120 | - ``desktop:`` Runs the ``desktop-file-validate`` program against any | ||
1121 | ``.desktop`` files to validate their contents against the | ||
1122 | specification for ``.desktop`` files. | ||
1123 | |||
1124 | - ``dev-deps:`` Checks that all packages except ``-dev`` or | ||
1125 | ``-staticdev`` packages do not depend on ``-dev`` packages, which | ||
1126 | would be a packaging bug. | ||
1127 | |||
1128 | - ``dev-so:`` Checks that the ``.so`` symbolic links are in the | ||
1129 | ``-dev`` package and not in any of the other packages. In general, | ||
1130 | these symlinks are only useful for development purposes. Thus, the | ||
1131 | ``-dev`` package is the correct location for them. Some very rare | ||
1132 | cases do exist for dynamically loaded modules where these symlinks | ||
1133 | are needed instead in the main package. | ||
1134 | |||
1135 | - ``file-rdeps:`` Checks that file-level dependencies identified by | ||
1136 | the OpenEmbedded build system at packaging time are satisfied. For | ||
1137 | example, a shell script might start with the line ``#!/bin/bash``. | ||
1138 | This line would translate to a file dependency on ``/bin/bash``. Of | ||
1139 | the three package managers that the OpenEmbedded build system | ||
1140 | supports, only RPM directly handles file-level dependencies, | ||
1141 | resolving them automatically to packages providing the files. | ||
1142 | However, the lack of that functionality in the other two package | ||
1143 | managers does not mean the dependencies do not still need resolving. | ||
1144 | This QA check attempts to ensure that explicitly declared | ||
1145 | :term:`RDEPENDS` exist to handle any file-level | ||
1146 | dependency detected in packaged files. | ||
1147 | |||
1148 | - ``files-invalid:`` Checks for :term:`FILES` variable | ||
1149 | values that contain "//", which is invalid. | ||
1150 | |||
1151 | - ``host-user-contaminated:`` Checks that no package produced by the | ||
1152 | recipe contains any files outside of ``/home`` with a user or group | ||
1153 | ID that matches the user running BitBake. A match usually indicates | ||
1154 | that the files are being installed with an incorrect UID/GID, since | ||
1155 | target IDs are independent from host IDs. For additional information, | ||
1156 | see the section describing the | ||
1157 | :ref:`ref-tasks-install` task. | ||
1158 | |||
1159 | - ``incompatible-license:`` Report when packages are excluded from | ||
1160 | being created due to being marked with a license that is in | ||
1161 | :term:`INCOMPATIBLE_LICENSE`. | ||
1162 | |||
1163 | - ``install-host-path:`` Checks the | ||
1164 | :ref:`ref-tasks-install` log for indications that | ||
1165 | paths to locations on the build host were used. Using such paths | ||
1166 | might result in host contamination of the build output. | ||
1167 | |||
1168 | - ``installed-vs-shipped:`` Reports when files have been installed | ||
1169 | within ``do_install`` but have not been included in any package by | ||
1170 | way of the :term:`FILES` variable. Files that do not | ||
1171 | appear in any package cannot be present in an image later on in the | ||
1172 | build process. Ideally, all installed files should be packaged or not | ||
1173 | installed at all. These files can be deleted at the end of | ||
1174 | ``do_install`` if the files are not needed in any package. | ||
1175 | |||
1176 | - ``invalid-chars:`` Checks that the recipe metadata variables | ||
1177 | :term:`DESCRIPTION`, | ||
1178 | :term:`SUMMARY`, :term:`LICENSE`, and | ||
1179 | :term:`SECTION` do not contain non-UTF-8 characters. | ||
1180 | Some package managers do not support such characters. | ||
1181 | |||
1182 | - ``invalid-packageconfig:`` Checks that no undefined features are | ||
1183 | being added to :term:`PACKAGECONFIG`. For | ||
1184 | example, any name "foo" for which the following form does not exist: | ||
1185 | :: | ||
1186 | |||
1187 | PACKAGECONFIG[foo] = "..." | ||
1188 | |||
1189 | - ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` | ||
1190 | file containing these paths is incorrect since ``libtool`` adds the | ||
1191 | correct sysroot prefix when using the files automatically itself. | ||
1192 | |||
1193 | - ``ldflags:`` Ensures that the binaries were linked with the | ||
1194 | :term:`LDFLAGS` options provided by the build system. | ||
1195 | If this test fails, check that the ``LDFLAGS`` variable is being | ||
1196 | passed to the linker command. | ||
1197 | |||
1198 | - ``libdir:`` Checks for libraries being installed into incorrect | ||
1199 | (possibly hardcoded) installation paths. For example, this test will | ||
1200 | catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is | ||
1201 | "lib32". Another example is when recipes install | ||
1202 | ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". | ||
1203 | |||
1204 | - ``libexec:`` Checks if a package contains files in | ||
1205 | ``/usr/libexec``. This check is not performed if the ``libexecdir`` | ||
1206 | variable has been set explicitly to ``/usr/libexec``. | ||
1207 | |||
1208 | - ``packages-list:`` Checks for the same package being listed | ||
1209 | multiple times through the :term:`PACKAGES` variable | ||
1210 | value. Installing the package in this manner can cause errors during | ||
1211 | packaging. | ||
1212 | |||
1213 | - ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an | ||
1214 | invalid format. | ||
1215 | |||
1216 | - ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an | ||
1217 | invalid format. | ||
1218 | |||
1219 | - ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify | ||
1220 | 'link' where the specified target already exists. | ||
1221 | |||
1222 | - ``perms:`` Currently, this check is unused but reserved. | ||
1223 | |||
1224 | - ``pkgconfig:`` Checks ``.pc`` files for any | ||
1225 | :term:`TMPDIR`/:term:`WORKDIR` paths. | ||
1226 | Any ``.pc`` file containing these paths is incorrect since | ||
1227 | ``pkg-config`` itself adds the correct sysroot prefix when the files | ||
1228 | are accessed. | ||
1229 | |||
1230 | - ``pkgname:`` Checks that all packages in | ||
1231 | :term:`PACKAGES` have names that do not contain | ||
1232 | invalid characters (i.e. characters other than 0-9, a-z, ., +, and | ||
1233 | -). | ||
1234 | |||
1235 | - ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is | ||
1236 | undefined during :ref:`ref-tasks-package`. | ||
1237 | |||
1238 | - ``pkgvarcheck:`` Checks through the variables | ||
1239 | :term:`RDEPENDS`, | ||
1240 | :term:`RRECOMMENDS`, | ||
1241 | :term:`RSUGGESTS`, | ||
1242 | :term:`RCONFLICTS`, | ||
1243 | :term:`RPROVIDES`, | ||
1244 | :term:`RREPLACES`, :term:`FILES`, | ||
1245 | :term:`ALLOW_EMPTY`, ``pkg_preinst``, | ||
1246 | ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if | ||
1247 | there are variable sets that are not package-specific. Using these | ||
1248 | variables without a package suffix is bad practice, and might | ||
1249 | unnecessarily complicate dependencies of other packages within the | ||
1250 | same recipe or have other unintended consequences. | ||
1251 | |||
1252 | - ``pn-overrides:`` Checks that a recipe does not have a name | ||
1253 | (:term:`PN`) value that appears in | ||
1254 | :term:`OVERRIDES`. If a recipe is named such that | ||
1255 | its ``PN`` value matches something already in ``OVERRIDES`` (e.g. | ||
1256 | ``PN`` happens to be the same as :term:`MACHINE` or | ||
1257 | :term:`DISTRO`), it can have unexpected consequences. | ||
1258 | For example, assignments such as ``FILES_${PN} = "xyz"`` effectively | ||
1259 | turn into ``FILES = "xyz"``. | ||
1260 | |||
1261 | - ``rpaths:`` Checks for rpaths in the binaries that contain build | ||
1262 | system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` | ||
1263 | options are being passed to the linker commands and your binaries | ||
1264 | have potential security issues. | ||
1265 | |||
1266 | - ``split-strip:`` Reports that splitting or stripping debug symbols | ||
1267 | from binaries has failed. | ||
1268 | |||
1269 | - ``staticdev:`` Checks for static library files (``*.a``) in | ||
1270 | non-``staticdev`` packages. | ||
1271 | |||
1272 | - ``symlink-to-sysroot:`` Checks for symlinks in packages that point | ||
1273 | into :term:`TMPDIR` on the host. Such symlinks will | ||
1274 | work on the host, but are clearly invalid when running on the target. | ||
1275 | |||
1276 | - ``textrel:`` Checks for ELF binaries that contain relocations in | ||
1277 | their ``.text`` sections, which can result in a performance impact at | ||
1278 | runtime. See the explanation for the | ||
1279 | ```ELF binary`` <#qa-issue-textrel>`__ message for more information | ||
1280 | regarding runtime performance issues. | ||
1281 | |||
1282 | - ``unlisted-pkg-lics:`` Checks that all declared licenses applying | ||
1283 | for a package are also declared on the recipe level (i.e. any license | ||
1284 | in ``LICENSE_*`` should appear in :term:`LICENSE`). | ||
1285 | |||
1286 | - ``useless-rpaths:`` Checks for dynamic library load paths (rpaths) | ||
1287 | in the binaries that by default on a standard system are searched by | ||
1288 | the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will | ||
1289 | not cause any breakage, they do waste space and are unnecessary. | ||
1290 | |||
1291 | - ``var-undefined:`` Reports when variables fundamental to packaging | ||
1292 | (i.e. :term:`WORKDIR`, | ||
1293 | :term:`DEPLOY_DIR`, :term:`D`, | ||
1294 | :term:`PN`, and :term:`PKGD`) are undefined | ||
1295 | during :ref:`ref-tasks-package`. | ||
1296 | |||
1297 | - ``version-going-backwards:`` If Build History is enabled, reports | ||
1298 | when a package being written out has a lower version than the | ||
1299 | previously written package under the same name. If you are placing | ||
1300 | output packages into a feed and upgrading packages on a target system | ||
1301 | using that feed, the version of a package going backwards can result | ||
1302 | in the target system not correctly upgrading to the "new" version of | ||
1303 | the package. | ||
1304 | |||
1305 | .. note:: | ||
1306 | |||
1307 | If you are not using runtime package management on your target | ||
1308 | system, then you do not need to worry about this situation. | ||
1309 | |||
1310 | - ``xorg-driver-abi:`` Checks that all packages containing Xorg | ||
1311 | drivers have ABI dependencies. The ``xserver-xorg`` recipe provides | ||
1312 | driver ABI names. All drivers should depend on the ABI versions that | ||
1313 | they have been built against. Driver recipes that include | ||
1314 | ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will | ||
1315 | automatically get these versions. Consequently, you should only need | ||
1316 | to explicitly add dependencies to binary driver recipes. | ||
1317 | |||
1318 | .. _ref-classes-insserv: | ||
1319 | |||
1320 | ``insserv.bbclass`` | ||
1321 | =================== | ||
1322 | |||
1323 | The ``insserv`` class uses the ``insserv`` utility to update the order | ||
1324 | of symbolic links in ``/etc/rc?.d/`` within an image based on | ||
1325 | dependencies specified by LSB headers in the ``init.d`` scripts | ||
1326 | themselves. | ||
1327 | |||
1328 | .. _ref-classes-kernel: | ||
1329 | |||
1330 | ``kernel.bbclass`` | ||
1331 | ================== | ||
1332 | |||
1333 | The ``kernel`` class handles building Linux kernels. The class contains | ||
1334 | code to build all kernel trees. All needed headers are staged into the | ||
1335 | ``STAGING_KERNEL_DIR`` directory to allow out-of-tree module builds | ||
1336 | using the :ref:`module <ref-classes-module>` class. | ||
1337 | |||
1338 | This means that each built kernel module is packaged separately and | ||
1339 | inter-module dependencies are created by parsing the ``modinfo`` output. | ||
1340 | If all modules are required, then installing the ``kernel-modules`` | ||
1341 | package installs all packages with modules and various other kernel | ||
1342 | packages such as ``kernel-vmlinux``. | ||
1343 | |||
1344 | The ``kernel`` class contains logic that allows you to embed an initial | ||
1345 | RAM filesystem (initramfs) image when you build the kernel image. For | ||
1346 | information on how to build an initramfs, see the | ||
1347 | ":ref:`building-an-initramfs-image`" section in | ||
1348 | the Yocto Project Development Tasks Manual. | ||
1349 | |||
1350 | Various other classes are used by the ``kernel`` and ``module`` classes | ||
1351 | internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`, | ||
1352 | :ref:`module-base <ref-classes-module-base>`, and | ||
1353 | :ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes. | ||
1354 | |||
1355 | .. _ref-classes-kernel-arch: | ||
1356 | |||
1357 | ``kernel-arch.bbclass`` | ||
1358 | ======================= | ||
1359 | |||
1360 | The ``kernel-arch`` class sets the ``ARCH`` environment variable for | ||
1361 | Linux kernel compilation (including modules). | ||
1362 | |||
1363 | .. _ref-classes-kernel-devicetree: | ||
1364 | |||
1365 | ``kernel-devicetree.bbclass`` | ||
1366 | ============================= | ||
1367 | |||
1368 | The ``kernel-devicetree`` class, which is inherited by the | ||
1369 | :ref:`kernel <ref-classes-kernel>` class, supports device tree | ||
1370 | generation. | ||
1371 | |||
1372 | .. _ref-classes-kernel-fitimage: | ||
1373 | |||
1374 | ``kernel-fitimage.bbclass`` | ||
1375 | =========================== | ||
1376 | |||
1377 | The ``kernel-fitimage`` class provides support to pack a kernel Image, | ||
1378 | device trees and a RAM disk into a single FIT image. In theory, a FIT | ||
1379 | image can support any number of kernels, RAM disks and device-trees. | ||
1380 | However, ``kernel-fitimage`` currently only supports | ||
1381 | limited usescases: just one kernel image, an optional RAM disk, and | ||
1382 | any number of device tree. | ||
1383 | |||
1384 | To create a FIT image, it is required that :term:`KERNEL_CLASSES` | ||
1385 | is set to "kernel-fitimage" and :term:`KERNEL_IMAGETYPE` | ||
1386 | is set to "fitImage". | ||
1387 | |||
1388 | The options for the device tree compiler passed to mkimage -D feature | ||
1389 | when creating the FIT image are specified using the | ||
1390 | :term:`UBOOT_MKIMAGE_DTCOPTS` variable. | ||
1391 | |||
1392 | Only a single kernel can be added to the FIT image created by | ||
1393 | ``kernel-fitimage`` and the kernel image in FIT is mandatory. The | ||
1394 | address where the kernel image is to be loaded by U-boot is | ||
1395 | specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by | ||
1396 | :term:`UBOOT_ENTRYPOINT`. | ||
1397 | |||
1398 | Multiple device trees can be added to the FIT image created by | ||
1399 | ``kernel-fitimage`` and the device tree is optional. | ||
1400 | The address where the device tree is to be loaded by U-boot is | ||
1401 | specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays | ||
1402 | and by `:term:`UBOOT_DTB_LOADADDRESS` for device tree binaries. | ||
1403 | |||
1404 | Only a single RAM disk can be added to the FIT image created by | ||
1405 | ``kernel-fitimage`` and the RAM disk in FIT is optional. | ||
1406 | The address where the RAM disk image is to be loaded by U-boot | ||
1407 | is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by | ||
1408 | :term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when | ||
1409 | :term:`INITRAMFS_IMAGE` is specified. | ||
1410 | |||
1411 | The FIT image generated by ``kernel-fitimage`` class is signed when the | ||
1412 | variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`, | ||
1413 | :term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set | ||
1414 | appropriately. The default values used for :term:`FIT_HASH_ALG` and | ||
1415 | :term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and | ||
1416 | "rsa2048" respectively. | ||
1417 | |||
1418 | |||
1419 | .. _ref-classes-kernel-grub: | ||
1420 | |||
1421 | ``kernel-grub.bbclass`` | ||
1422 | ======================= | ||
1423 | |||
1424 | The ``kernel-grub`` class updates the boot area and the boot menu with | ||
1425 | the kernel as the priority boot mechanism while installing a RPM to | ||
1426 | update the kernel on a deployed target. | ||
1427 | |||
1428 | .. _ref-classes-kernel-module-split: | ||
1429 | |||
1430 | ``kernel-module-split.bbclass`` | ||
1431 | =============================== | ||
1432 | |||
1433 | The ``kernel-module-split`` class provides common functionality for | ||
1434 | splitting Linux kernel modules into separate packages. | ||
1435 | |||
1436 | .. _ref-classes-kernel-uboot: | ||
1437 | |||
1438 | ``kernel-uboot.bbclass`` | ||
1439 | ======================== | ||
1440 | |||
1441 | The ``kernel-uboot`` class provides support for building from | ||
1442 | vmlinux-style kernel sources. | ||
1443 | |||
1444 | .. _ref-classes-kernel-uimage: | ||
1445 | |||
1446 | ``kernel-uimage.bbclass`` | ||
1447 | ========================= | ||
1448 | |||
1449 | The ``kernel-uimage`` class provides support to pack uImage. | ||
1450 | |||
1451 | .. _ref-classes-kernel-yocto: | ||
1452 | |||
1453 | ``kernel-yocto.bbclass`` | ||
1454 | ======================== | ||
1455 | |||
1456 | The ``kernel-yocto`` class provides common functionality for building | ||
1457 | from linux-yocto style kernel source repositories. | ||
1458 | |||
1459 | .. _ref-classes-kernelsrc: | ||
1460 | |||
1461 | ``kernelsrc.bbclass`` | ||
1462 | ===================== | ||
1463 | |||
1464 | The ``kernelsrc`` class sets the Linux kernel source and version. | ||
1465 | |||
1466 | .. _ref-classes-lib_package: | ||
1467 | |||
1468 | ``lib_package.bbclass`` | ||
1469 | ======================= | ||
1470 | |||
1471 | The ``lib_package`` class supports recipes that build libraries and | ||
1472 | produce executable binaries, where those binaries should not be | ||
1473 | installed by default along with the library. Instead, the binaries are | ||
1474 | added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to | ||
1475 | make their installation optional. | ||
1476 | |||
1477 | .. _ref-classes-libc*: | ||
1478 | |||
1479 | ``libc*.bbclass`` | ||
1480 | ================= | ||
1481 | |||
1482 | The ``libc*`` classes support recipes that build packages with ``libc``: | ||
1483 | |||
1484 | - The ``libc-common`` class provides common support for building with | ||
1485 | ``libc``. | ||
1486 | |||
1487 | - The ``libc-package`` class supports packaging up ``glibc`` and | ||
1488 | ``eglibc``. | ||
1489 | |||
1490 | .. _ref-classes-license: | ||
1491 | |||
1492 | ``license.bbclass`` | ||
1493 | =================== | ||
1494 | |||
1495 | The ``license`` class provides license manifest creation and license | ||
1496 | exclusion. This class is enabled by default using the default value for | ||
1497 | the :term:`INHERIT_DISTRO` variable. | ||
1498 | |||
1499 | .. _ref-classes-linux-kernel-base: | ||
1500 | |||
1501 | ``linux-kernel-base.bbclass`` | ||
1502 | ============================= | ||
1503 | |||
1504 | The ``linux-kernel-base`` class provides common functionality for | ||
1505 | recipes that build out of the Linux kernel source tree. These builds | ||
1506 | goes beyond the kernel itself. For example, the Perf recipe also | ||
1507 | inherits this class. | ||
1508 | |||
1509 | .. _ref-classes-linuxloader: | ||
1510 | |||
1511 | ``linuxloader.bbclass`` | ||
1512 | ======================= | ||
1513 | |||
1514 | Provides the function ``linuxloader()``, which gives the value of the | ||
1515 | dynamic loader/linker provided on the platform. This value is used by a | ||
1516 | number of other classes. | ||
1517 | |||
1518 | .. _ref-classes-logging: | ||
1519 | |||
1520 | ``logging.bbclass`` | ||
1521 | =================== | ||
1522 | |||
1523 | The ``logging`` class provides the standard shell functions used to log | ||
1524 | messages for various BitBake severity levels (i.e. ``bbplain``, | ||
1525 | ``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``). | ||
1526 | |||
1527 | This class is enabled by default since it is inherited by the ``base`` | ||
1528 | class. | ||
1529 | |||
1530 | .. _ref-classes-meta: | ||
1531 | |||
1532 | ``meta.bbclass`` | ||
1533 | ================ | ||
1534 | |||
1535 | The ``meta`` class is inherited by recipes that do not build any output | ||
1536 | packages themselves, but act as a "meta" target for building other | ||
1537 | recipes. | ||
1538 | |||
1539 | .. _ref-classes-metadata_scm: | ||
1540 | |||
1541 | ``metadata_scm.bbclass`` | ||
1542 | ======================== | ||
1543 | |||
1544 | The ``metadata_scm`` class provides functionality for querying the | ||
1545 | branch and revision of a Source Code Manager (SCM) repository. | ||
1546 | |||
1547 | The :ref:`base <ref-classes-base>` class uses this class to print the | ||
1548 | revisions of each layer before starting every build. The | ||
1549 | ``metadata_scm`` class is enabled by default because it is inherited by | ||
1550 | the ``base`` class. | ||
1551 | |||
1552 | .. _ref-classes-migrate_localcount: | ||
1553 | |||
1554 | ``migrate_localcount.bbclass`` | ||
1555 | ============================== | ||
1556 | |||
1557 | The ``migrate_localcount`` class verifies a recipe's localcount data and | ||
1558 | increments it appropriately. | ||
1559 | |||
1560 | .. _ref-classes-mime: | ||
1561 | |||
1562 | ``mime.bbclass`` | ||
1563 | ================ | ||
1564 | |||
1565 | The ``mime`` class generates the proper post-install and post-remove | ||
1566 | (postinst/postrm) scriptlets for packages that install MIME type files. | ||
1567 | These scriptlets call ``update-mime-database`` to add the MIME types to | ||
1568 | the shared database. | ||
1569 | |||
1570 | .. _ref-classes-mirrors: | ||
1571 | |||
1572 | ``mirrors.bbclass`` | ||
1573 | =================== | ||
1574 | |||
1575 | The ``mirrors`` class sets up some standard | ||
1576 | :term:`MIRRORS` entries for source code mirrors. These | ||
1577 | mirrors provide a fall-back path in case the upstream source specified | ||
1578 | in :term:`SRC_URI` within recipes is unavailable. | ||
1579 | |||
1580 | This class is enabled by default since it is inherited by the | ||
1581 | :ref:`base <ref-classes-base>` class. | ||
1582 | |||
1583 | .. _ref-classes-module: | ||
1584 | |||
1585 | ``module.bbclass`` | ||
1586 | ================== | ||
1587 | |||
1588 | The ``module`` class provides support for building out-of-tree Linux | ||
1589 | kernel modules. The class inherits the | ||
1590 | :ref:`module-base <ref-classes-module-base>` and | ||
1591 | :ref:`kernel-module-split <ref-classes-kernel-module-split>` classes, | ||
1592 | and implements the :ref:`ref-tasks-compile` and | ||
1593 | :ref:`ref-tasks-install` tasks. The class provides | ||
1594 | everything needed to build and package a kernel module. | ||
1595 | |||
1596 | For general information on out-of-tree Linux kernel modules, see the | ||
1597 | ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" | ||
1598 | section in the Yocto Project Linux Kernel Development Manual. | ||
1599 | |||
1600 | .. _ref-classes-module-base: | ||
1601 | |||
1602 | ``module-base.bbclass`` | ||
1603 | ======================= | ||
1604 | |||
1605 | The ``module-base`` class provides the base functionality for building | ||
1606 | Linux kernel modules. Typically, a recipe that builds software that | ||
1607 | includes one or more kernel modules and has its own means of building | ||
1608 | the module inherits this class as opposed to inheriting the | ||
1609 | :ref:`module <ref-classes-module>` class. | ||
1610 | |||
1611 | .. _ref-classes-multilib*: | ||
1612 | |||
1613 | ``multilib*.bbclass`` | ||
1614 | ===================== | ||
1615 | |||
1616 | The ``multilib*`` classes provide support for building libraries with | ||
1617 | different target optimizations or target architectures and installing | ||
1618 | them side-by-side in the same image. | ||
1619 | |||
1620 | For more information on using the Multilib feature, see the | ||
1621 | ":ref:`combining-multiple-versions-library-files-into-one-image`" | ||
1622 | section in the Yocto Project Development Tasks Manual. | ||
1623 | |||
1624 | .. _ref-classes-native: | ||
1625 | |||
1626 | ``native.bbclass`` | ||
1627 | ================== | ||
1628 | |||
1629 | The ``native`` class provides common functionality for recipes that | ||
1630 | build tools to run on the `build host <#hardware-build-system-term>`__ | ||
1631 | (i.e. tools that use the compiler or other tools from the build host). | ||
1632 | |||
1633 | You can create a recipe that builds tools that run natively on the host | ||
1634 | a couple different ways: | ||
1635 | |||
1636 | - Create a myrecipe\ ``-native.bb`` recipe that inherits the ``native`` | ||
1637 | class. If you use this method, you must order the inherit statement | ||
1638 | in the recipe after all other inherit statements so that the | ||
1639 | ``native`` class is inherited last. | ||
1640 | |||
1641 | .. note:: | ||
1642 | |||
1643 | When creating a recipe this way, the recipe name must follow this | ||
1644 | naming convention: | ||
1645 | :: | ||
1646 | |||
1647 | myrecipe-native.bb | ||
1648 | |||
1649 | |||
1650 | Not using this naming convention can lead to subtle problems | ||
1651 | caused by existing code that depends on that naming convention. | ||
1652 | |||
1653 | - Create or modify a target recipe that contains the following: | ||
1654 | :: | ||
1655 | |||
1656 | BBCLASSEXTEND = "native" | ||
1657 | |||
1658 | Inside the | ||
1659 | recipe, use ``_class-native`` and ``_class-target`` overrides to | ||
1660 | specify any functionality specific to the respective native or target | ||
1661 | case. | ||
1662 | |||
1663 | Although applied differently, the ``native`` class is used with both | ||
1664 | methods. The advantage of the second method is that you do not need to | ||
1665 | have two separate recipes (assuming you need both) for native and | ||
1666 | target. All common parts of the recipe are automatically shared. | ||
1667 | |||
1668 | .. _ref-classes-nativesdk: | ||
1669 | |||
1670 | ``nativesdk.bbclass`` | ||
1671 | ===================== | ||
1672 | |||
1673 | The ``nativesdk`` class provides common functionality for recipes that | ||
1674 | wish to build tools to run as part of an SDK (i.e. tools that run on | ||
1675 | :term:`SDKMACHINE`). | ||
1676 | |||
1677 | You can create a recipe that builds tools that run on the SDK machine a | ||
1678 | couple different ways: | ||
1679 | |||
1680 | - Create a ``nativesdk-``\ myrecipe\ ``.bb`` recipe that inherits the | ||
1681 | ``nativesdk`` class. If you use this method, you must order the | ||
1682 | inherit statement in the recipe after all other inherit statements so | ||
1683 | that the ``nativesdk`` class is inherited last. | ||
1684 | |||
1685 | - Create a ``nativesdk`` variant of any recipe by adding the following: | ||
1686 | :: | ||
1687 | |||
1688 | BBCLASSEXTEND = "nativesdk" | ||
1689 | |||
1690 | Inside the | ||
1691 | recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to | ||
1692 | specify any functionality specific to the respective SDK machine or | ||
1693 | target case. | ||
1694 | |||
1695 | .. note:: | ||
1696 | |||
1697 | When creating a recipe, you must follow this naming convention: | ||
1698 | :: | ||
1699 | |||
1700 | nativesdk-myrecipe.bb | ||
1701 | |||
1702 | |||
1703 | Not doing so can lead to subtle problems because code exists that | ||
1704 | depends on the naming convention. | ||
1705 | |||
1706 | Although applied differently, the ``nativesdk`` class is used with both | ||
1707 | methods. The advantage of the second method is that you do not need to | ||
1708 | have two separate recipes (assuming you need both) for the SDK machine | ||
1709 | and the target. All common parts of the recipe are automatically shared. | ||
1710 | |||
1711 | .. _ref-classes-nopackages: | ||
1712 | |||
1713 | ``nopackages.bbclass`` | ||
1714 | ====================== | ||
1715 | |||
1716 | Disables packaging tasks for those recipes and classes where packaging | ||
1717 | is not needed. | ||
1718 | |||
1719 | .. _ref-classes-npm: | ||
1720 | |||
1721 | ``npm.bbclass`` | ||
1722 | =============== | ||
1723 | |||
1724 | Provides support for building Node.js software fetched using the `node | ||
1725 | package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__. | ||
1726 | |||
1727 | .. note:: | ||
1728 | |||
1729 | Currently, recipes inheriting this class must use the | ||
1730 | npm:// | ||
1731 | fetcher to have dependencies fetched and packaged automatically. | ||
1732 | |||
1733 | For information on how to create NPM packages, see the | ||
1734 | ":ref:`dev-manual/dev-manual-common-tasks:creating node package manager (npm) packages`" | ||
1735 | section in the Yocto Project Development Tasks Manual. | ||
1736 | |||
1737 | .. _ref-classes-oelint: | ||
1738 | |||
1739 | ``oelint.bbclass`` | ||
1740 | ================== | ||
1741 | |||
1742 | The ``oelint`` class is an obsolete lint checking tool that exists in | ||
1743 | ``meta/classes`` in the :term:`Source Directory`. | ||
1744 | |||
1745 | A number of classes exist that could be generally useful in OE-Core but | ||
1746 | are never actually used within OE-Core itself. The ``oelint`` class is | ||
1747 | one such example. However, being aware of this class can reduce the | ||
1748 | proliferation of different versions of similar classes across multiple | ||
1749 | layers. | ||
1750 | |||
1751 | .. _ref-classes-own-mirrors: | ||
1752 | |||
1753 | ``own-mirrors.bbclass`` | ||
1754 | ======================= | ||
1755 | |||
1756 | The ``own-mirrors`` class makes it easier to set up your own | ||
1757 | :term:`PREMIRRORS` from which to first fetch source | ||
1758 | before attempting to fetch it from the upstream specified in | ||
1759 | :term:`SRC_URI` within each recipe. | ||
1760 | |||
1761 | To use this class, inherit it globally and specify | ||
1762 | :term:`SOURCE_MIRROR_URL`. Here is an example: | ||
1763 | :: | ||
1764 | |||
1765 | INHERIT += "own-mirrors" | ||
1766 | SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" | ||
1767 | |||
1768 | You can specify only a single URL | ||
1769 | in ``SOURCE_MIRROR_URL``. | ||
1770 | |||
1771 | .. _ref-classes-package: | ||
1772 | |||
1773 | ``package.bbclass`` | ||
1774 | =================== | ||
1775 | |||
1776 | The ``package`` class supports generating packages from a build's | ||
1777 | output. The core generic functionality is in ``package.bbclass``. The | ||
1778 | code specific to particular package types resides in these | ||
1779 | package-specific classes: | ||
1780 | :ref:`package_deb <ref-classes-package_deb>`, | ||
1781 | :ref:`package_rpm <ref-classes-package_rpm>`, | ||
1782 | :ref:`package_ipk <ref-classes-package_ipk>`, and | ||
1783 | :ref:`package_tar <ref-classes-package_tar>`. | ||
1784 | |||
1785 | .. note:: | ||
1786 | |||
1787 | The | ||
1788 | package_tar | ||
1789 | class is broken and not supported. It is recommended that you do not | ||
1790 | use this class. | ||
1791 | |||
1792 | You can control the list of resulting package formats by using the | ||
1793 | ``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf`` | ||
1794 | configuration file, which is located in the :term:`Build Directory`. | ||
1795 | When defining the variable, you can | ||
1796 | specify one or more package types. Since images are generated from | ||
1797 | packages, a packaging class is needed to enable image generation. The | ||
1798 | first class listed in this variable is used for image generation. | ||
1799 | |||
1800 | If you take the optional step to set up a repository (package feed) on | ||
1801 | the development host that can be used by DNF, you can install packages | ||
1802 | from the feed while you are running the image on the target (i.e. | ||
1803 | runtime installation of packages). For more information, see the | ||
1804 | ":ref:`dev-manual/dev-manual-common-tasks:using runtime package management`" | ||
1805 | section in the Yocto Project Development Tasks Manual. | ||
1806 | |||
1807 | The package-specific class you choose can affect build-time performance | ||
1808 | and has space ramifications. In general, building a package with IPK | ||
1809 | takes about thirty percent less time as compared to using RPM to build | ||
1810 | the same or similar package. This comparison takes into account a | ||
1811 | complete build of the package with all dependencies previously built. | ||
1812 | The reason for this discrepancy is because the RPM package manager | ||
1813 | creates and processes more :term:`Metadata` than the IPK package | ||
1814 | manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to | ||
1815 | "package_ipk" if you are building smaller systems. | ||
1816 | |||
1817 | Before making your package manager decision, however, you should | ||
1818 | consider some further things about using RPM: | ||
1819 | |||
1820 | - RPM starts to provide more abilities than IPK due to the fact that it | ||
1821 | processes more Metadata. For example, this information includes | ||
1822 | individual file types, file checksum generation and evaluation on | ||
1823 | install, sparse file support, conflict detection and resolution for | ||
1824 | Multilib systems, ACID style upgrade, and repackaging abilities for | ||
1825 | rollbacks. | ||
1826 | |||
1827 | - For smaller systems, the extra space used for the Berkeley Database | ||
1828 | and the amount of metadata when using RPM can affect your ability to | ||
1829 | perform on-device upgrades. | ||
1830 | |||
1831 | You can find additional information on the effects of the package class | ||
1832 | at these two Yocto Project mailing list links: | ||
1833 | |||
1834 | - https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html | ||
1835 | |||
1836 | - https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html | ||
1837 | |||
1838 | .. _ref-classes-package_deb: | ||
1839 | |||
1840 | ``package_deb.bbclass`` | ||
1841 | ======================= | ||
1842 | |||
1843 | The ``package_deb`` class provides support for creating packages that | ||
1844 | use the Debian (i.e. ``.deb``) file format. The class ensures the | ||
1845 | packages are written out in a ``.deb`` file format to the | ||
1846 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory. | ||
1847 | |||
1848 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1849 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1850 | variable in the ``local.conf`` file. | ||
1851 | |||
1852 | .. _ref-classes-package_ipk: | ||
1853 | |||
1854 | ``package_ipk.bbclass`` | ||
1855 | ======================= | ||
1856 | |||
1857 | The ``package_ipk`` class provides support for creating packages that | ||
1858 | use the IPK (i.e. ``.ipk``) file format. The class ensures the packages | ||
1859 | are written out in a ``.ipk`` file format to the | ||
1860 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory. | ||
1861 | |||
1862 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1863 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1864 | variable in the ``local.conf`` file. | ||
1865 | |||
1866 | .. _ref-classes-package_rpm: | ||
1867 | |||
1868 | ``package_rpm.bbclass`` | ||
1869 | ======================= | ||
1870 | |||
1871 | The ``package_rpm`` class provides support for creating packages that | ||
1872 | use the RPM (i.e. ``.rpm``) file format. The class ensures the packages | ||
1873 | are written out in a ``.rpm`` file format to the | ||
1874 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory. | ||
1875 | |||
1876 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1877 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1878 | variable in the ``local.conf`` file. | ||
1879 | |||
1880 | .. _ref-classes-package_tar: | ||
1881 | |||
1882 | ``package_tar.bbclass`` | ||
1883 | ======================= | ||
1884 | |||
1885 | The ``package_tar`` class provides support for creating tarballs. The | ||
1886 | class ensures the packages are written out in a tarball format to the | ||
1887 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory. | ||
1888 | |||
1889 | This class inherits the :ref:`package <ref-classes-package>` class and | ||
1890 | is enabled through the :term:`PACKAGE_CLASSES` | ||
1891 | variable in the ``local.conf`` file. | ||
1892 | |||
1893 | .. note:: | ||
1894 | |||
1895 | You cannot specify the | ||
1896 | package_tar | ||
1897 | class first using the | ||
1898 | PACKAGE_CLASSES | ||
1899 | variable. You must use | ||
1900 | .deb | ||
1901 | , | ||
1902 | .ipk | ||
1903 | , or | ||
1904 | .rpm | ||
1905 | file formats for your image or SDK. | ||
1906 | |||
1907 | .. _ref-classes-packagedata: | ||
1908 | |||
1909 | ``packagedata.bbclass`` | ||
1910 | ======================= | ||
1911 | |||
1912 | The ``packagedata`` class provides common functionality for reading | ||
1913 | ``pkgdata`` files found in :term:`PKGDATA_DIR`. These | ||
1914 | files contain information about each output package produced by the | ||
1915 | OpenEmbedded build system. | ||
1916 | |||
1917 | This class is enabled by default because it is inherited by the | ||
1918 | :ref:`package <ref-classes-package>` class. | ||
1919 | |||
1920 | .. _ref-classes-packagegroup: | ||
1921 | |||
1922 | ``packagegroup.bbclass`` | ||
1923 | ======================== | ||
1924 | |||
1925 | The ``packagegroup`` class sets default values appropriate for package | ||
1926 | group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and | ||
1927 | so forth). It is highly recommended that all package group recipes | ||
1928 | inherit this class. | ||
1929 | |||
1930 | For information on how to use this class, see the | ||
1931 | ":ref:`usingpoky-extend-customimage-customtasks`" | ||
1932 | section in the Yocto Project Development Tasks Manual. | ||
1933 | |||
1934 | Previously, this class was called the ``task`` class. | ||
1935 | |||
1936 | .. _ref-classes-patch: | ||
1937 | |||
1938 | ``patch.bbclass`` | ||
1939 | ================= | ||
1940 | |||
1941 | The ``patch`` class provides all functionality for applying patches | ||
1942 | during the :ref:`ref-tasks-patch` task. | ||
1943 | |||
1944 | This class is enabled by default because it is inherited by the | ||
1945 | :ref:`base <ref-classes-base>` class. | ||
1946 | |||
1947 | .. _ref-classes-perlnative: | ||
1948 | |||
1949 | ``perlnative.bbclass`` | ||
1950 | ====================== | ||
1951 | |||
1952 | When inherited by a recipe, the ``perlnative`` class supports using the | ||
1953 | native version of Perl built by the build system rather than using the | ||
1954 | version provided by the build host. | ||
1955 | |||
1956 | .. _ref-classes-pixbufcache: | ||
1957 | |||
1958 | ``pixbufcache.bbclass`` | ||
1959 | ======================= | ||
1960 | |||
1961 | The ``pixbufcache`` class generates the proper post-install and | ||
1962 | post-remove (postinst/postrm) scriptlets for packages that install | ||
1963 | pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets | ||
1964 | call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache. | ||
1965 | Since the cache files are architecture-specific, ``update_pixbuf_cache`` | ||
1966 | is run using QEMU if the postinst scriptlets need to be run on the build | ||
1967 | host during image creation. | ||
1968 | |||
1969 | If the pixbuf loaders being installed are in packages other than the | ||
1970 | recipe's main package, set | ||
1971 | :term:`PIXBUF_PACKAGES` to specify the packages | ||
1972 | containing the loaders. | ||
1973 | |||
1974 | .. _ref-classes-pkgconfig: | ||
1975 | |||
1976 | ``pkgconfig.bbclass`` | ||
1977 | ===================== | ||
1978 | |||
1979 | The ``pkgconfig`` class provides a standard way to get header and | ||
1980 | library information by using ``pkg-config``. This class aims to smooth | ||
1981 | integration of ``pkg-config`` into libraries that use it. | ||
1982 | |||
1983 | During staging, BitBake installs ``pkg-config`` data into the | ||
1984 | ``sysroots/`` directory. By making use of sysroot functionality within | ||
1985 | ``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the | ||
1986 | files. | ||
1987 | |||
1988 | .. _ref-classes-populate-sdk: | ||
1989 | |||
1990 | ``populate_sdk.bbclass`` | ||
1991 | ======================== | ||
1992 | |||
1993 | The ``populate_sdk`` class provides support for SDK-only recipes. For | ||
1994 | information on advantages gained when building a cross-development | ||
1995 | toolchain using the :ref:`ref-tasks-populate_sdk` | ||
1996 | task, see the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" | ||
1997 | section in the Yocto Project Application Development and the Extensible | ||
1998 | Software Development Kit (eSDK) manual. | ||
1999 | |||
2000 | .. _ref-classes-populate-sdk-*: | ||
2001 | |||
2002 | ``populate_sdk_*.bbclass`` | ||
2003 | ========================== | ||
2004 | |||
2005 | The ``populate_sdk_*`` classes support SDK creation and consist of the | ||
2006 | following classes: | ||
2007 | |||
2008 | - ``populate_sdk_base``: The base class supporting SDK creation under | ||
2009 | all package managers (i.e. DEB, RPM, and opkg). | ||
2010 | |||
2011 | - ``populate_sdk_deb``: Supports creation of the SDK given the Debian | ||
2012 | package manager. | ||
2013 | |||
2014 | - ``populate_sdk_rpm``: Supports creation of the SDK given the RPM | ||
2015 | package manager. | ||
2016 | |||
2017 | - ``populate_sdk_ipk``: Supports creation of the SDK given the opkg | ||
2018 | (IPK format) package manager. | ||
2019 | |||
2020 | - ``populate_sdk_ext``: Supports extensible SDK creation under all | ||
2021 | package managers. | ||
2022 | |||
2023 | The ``populate_sdk_base`` class inherits the appropriate | ||
2024 | ``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on | ||
2025 | :term:`IMAGE_PKGTYPE`. | ||
2026 | |||
2027 | The base class ensures all source and destination directories are | ||
2028 | established and then populates the SDK. After populating the SDK, the | ||
2029 | ``populate_sdk_base`` class constructs two sysroots: | ||
2030 | ``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which | ||
2031 | contains the cross-compiler and associated tooling, and the target, | ||
2032 | which contains a target root filesystem that is configured for the SDK | ||
2033 | usage. These two images reside in :term:`SDK_OUTPUT`, | ||
2034 | which consists of the following: | ||
2035 | :: | ||
2036 | |||
2037 | ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs | ||
2038 | ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs | ||
2039 | |||
2040 | Finally, the base populate SDK class creates the toolchain environment | ||
2041 | setup script, the tarball of the SDK, and the installer. | ||
2042 | |||
2043 | The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and | ||
2044 | ``populate_sdk_ipk`` classes each support the specific type of SDK. | ||
2045 | These classes are inherited by and used with the ``populate_sdk_base`` | ||
2046 | class. | ||
2047 | |||
2048 | For more information on the cross-development toolchain generation, see | ||
2049 | the ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`" | ||
2050 | section in the Yocto Project Overview and Concepts Manual. For | ||
2051 | information on advantages gained when building a cross-development | ||
2052 | toolchain using the :ref:`ref-tasks-populate_sdk` | ||
2053 | task, see the | ||
2054 | ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" | ||
2055 | section in the Yocto Project Application Development and the Extensible | ||
2056 | Software Development Kit (eSDK) manual. | ||
2057 | |||
2058 | .. _ref-classes-prexport: | ||
2059 | |||
2060 | ``prexport.bbclass`` | ||
2061 | ==================== | ||
2062 | |||
2063 | The ``prexport`` class provides functionality for exporting | ||
2064 | :term:`PR` values. | ||
2065 | |||
2066 | .. note:: | ||
2067 | |||
2068 | This class is not intended to be used directly. Rather, it is enabled | ||
2069 | when using " | ||
2070 | bitbake-prserv-tool export | ||
2071 | ". | ||
2072 | |||
2073 | .. _ref-classes-primport: | ||
2074 | |||
2075 | ``primport.bbclass`` | ||
2076 | ==================== | ||
2077 | |||
2078 | The ``primport`` class provides functionality for importing | ||
2079 | :term:`PR` values. | ||
2080 | |||
2081 | .. note:: | ||
2082 | |||
2083 | This class is not intended to be used directly. Rather, it is enabled | ||
2084 | when using " | ||
2085 | bitbake-prserv-tool import | ||
2086 | ". | ||
2087 | |||
2088 | .. _ref-classes-prserv: | ||
2089 | |||
2090 | ``prserv.bbclass`` | ||
2091 | ================== | ||
2092 | |||
2093 | The ``prserv`` class provides functionality for using a :ref:`PR | ||
2094 | service <dev-manual/dev-manual-common-tasks:working with a pr service>` in order to | ||
2095 | automatically manage the incrementing of the :term:`PR` | ||
2096 | variable for each recipe. | ||
2097 | |||
2098 | This class is enabled by default because it is inherited by the | ||
2099 | :ref:`package <ref-classes-package>` class. However, the OpenEmbedded | ||
2100 | build system will not enable the functionality of this class unless | ||
2101 | :term:`PRSERV_HOST` has been set. | ||
2102 | |||
2103 | .. _ref-classes-ptest: | ||
2104 | |||
2105 | ``ptest.bbclass`` | ||
2106 | ================= | ||
2107 | |||
2108 | The ``ptest`` class provides functionality for packaging and installing | ||
2109 | runtime tests for recipes that build software that provides these tests. | ||
2110 | |||
2111 | This class is intended to be inherited by individual recipes. However, | ||
2112 | the class' functionality is largely disabled unless "ptest" appears in | ||
2113 | :term:`DISTRO_FEATURES`. See the | ||
2114 | ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" | ||
2115 | section in the Yocto Project Development Tasks Manual for more information | ||
2116 | on ptest. | ||
2117 | |||
2118 | .. _ref-classes-ptest-gnome: | ||
2119 | |||
2120 | ``ptest-gnome.bbclass`` | ||
2121 | ======================= | ||
2122 | |||
2123 | Enables package tests (ptests) specifically for GNOME packages, which | ||
2124 | have tests intended to be executed with ``gnome-desktop-testing``. | ||
2125 | |||
2126 | For information on setting up and running ptests, see the | ||
2127 | ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" | ||
2128 | section in the Yocto Project Development Tasks Manual. | ||
2129 | |||
2130 | .. _ref-classes-python-dir: | ||
2131 | |||
2132 | ``python-dir.bbclass`` | ||
2133 | ====================== | ||
2134 | |||
2135 | The ``python-dir`` class provides the base version, location, and site | ||
2136 | package location for Python. | ||
2137 | |||
2138 | .. _ref-classes-python3native: | ||
2139 | |||
2140 | ``python3native.bbclass`` | ||
2141 | ========================= | ||
2142 | |||
2143 | The ``python3native`` class supports using the native version of Python | ||
2144 | 3 built by the build system rather than support of the version provided | ||
2145 | by the build host. | ||
2146 | |||
2147 | .. _ref-classes-pythonnative: | ||
2148 | |||
2149 | ``pythonnative.bbclass`` | ||
2150 | ======================== | ||
2151 | |||
2152 | When inherited by a recipe, the ``pythonnative`` class supports using | ||
2153 | the native version of Python built by the build system rather than using | ||
2154 | the version provided by the build host. | ||
2155 | |||
2156 | .. _ref-classes-qemu: | ||
2157 | |||
2158 | ``qemu.bbclass`` | ||
2159 | ================ | ||
2160 | |||
2161 | The ``qemu`` class provides functionality for recipes that either need | ||
2162 | QEMU or test for the existence of QEMU. Typically, this class is used to | ||
2163 | run programs for a target system on the build host using QEMU's | ||
2164 | application emulation mode. | ||
2165 | |||
2166 | .. _ref-classes-recipe_sanity: | ||
2167 | |||
2168 | ``recipe_sanity.bbclass`` | ||
2169 | ========================= | ||
2170 | |||
2171 | The ``recipe_sanity`` class checks for the presence of any host system | ||
2172 | recipe prerequisites that might affect the build (e.g. variables that | ||
2173 | are set or software that is present). | ||
2174 | |||
2175 | .. _ref-classes-relocatable: | ||
2176 | |||
2177 | ``relocatable.bbclass`` | ||
2178 | ======================= | ||
2179 | |||
2180 | The ``relocatable`` class enables relocation of binaries when they are | ||
2181 | installed into the sysroot. | ||
2182 | |||
2183 | This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class | ||
2184 | and is used by both the :ref:`cross <ref-classes-cross>` and | ||
2185 | :ref:`native <ref-classes-native>` classes. | ||
2186 | |||
2187 | .. _ref-classes-remove-libtool: | ||
2188 | |||
2189 | ``remove-libtool.bbclass`` | ||
2190 | ========================== | ||
2191 | |||
2192 | The ``remove-libtool`` class adds a post function to the | ||
2193 | :ref:`ref-tasks-install` task to remove all ``.la`` files | ||
2194 | installed by ``libtool``. Removing these files results in them being | ||
2195 | absent from both the sysroot and target packages. | ||
2196 | |||
2197 | If a recipe needs the ``.la`` files to be installed, then the recipe can | ||
2198 | override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: | ||
2199 | :: | ||
2200 | |||
2201 | REMOVE_LIBTOOL_LA = "0" | ||
2202 | |||
2203 | .. note:: | ||
2204 | |||
2205 | The | ||
2206 | remove-libtool | ||
2207 | class is not enabled by default. | ||
2208 | |||
2209 | .. _ref-classes-report-error: | ||
2210 | |||
2211 | ``report-error.bbclass`` | ||
2212 | ======================== | ||
2213 | |||
2214 | The ``report-error`` class supports enabling the :ref:`error reporting | ||
2215 | tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`", | ||
2216 | which allows you to submit build error information to a central database. | ||
2217 | |||
2218 | The class collects debug information for recipe, recipe version, task, | ||
2219 | machine, distro, build system, target system, host distro, branch, | ||
2220 | commit, and log. From the information, report files using a JSON format | ||
2221 | are created and stored in | ||
2222 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. | ||
2223 | |||
2224 | .. _ref-classes-rm-work: | ||
2225 | |||
2226 | ``rm_work.bbclass`` | ||
2227 | =================== | ||
2228 | |||
2229 | The ``rm_work`` class supports deletion of temporary workspace, which | ||
2230 | can ease your hard drive demands during builds. | ||
2231 | |||
2232 | The OpenEmbedded build system can use a substantial amount of disk space | ||
2233 | during the build process. A portion of this space is the work files | ||
2234 | under the ``${TMPDIR}/work`` directory for each recipe. Once the build | ||
2235 | system generates the packages for a recipe, the work files for that | ||
2236 | recipe are no longer needed. However, by default, the build system | ||
2237 | preserves these files for inspection and possible debugging purposes. If | ||
2238 | you would rather have these files deleted to save disk space as the | ||
2239 | build progresses, you can enable ``rm_work`` by adding the following to | ||
2240 | your ``local.conf`` file, which is found in the :term:`Build Directory`. | ||
2241 | :: | ||
2242 | |||
2243 | INHERIT += "rm_work" | ||
2244 | |||
2245 | If you are | ||
2246 | modifying and building source code out of the work directory for a | ||
2247 | recipe, enabling ``rm_work`` will potentially result in your changes to | ||
2248 | the source being lost. To exclude some recipes from having their work | ||
2249 | directories deleted by ``rm_work``, you can add the names of the recipe | ||
2250 | or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which | ||
2251 | can also be set in your ``local.conf`` file. Here is an example: | ||
2252 | :: | ||
2253 | |||
2254 | RM_WORK_EXCLUDE += "busybox glibc" | ||
2255 | |||
2256 | .. _ref-classes-rootfs*: | ||
2257 | |||
2258 | ``rootfs*.bbclass`` | ||
2259 | =================== | ||
2260 | |||
2261 | The ``rootfs*`` classes support creating the root filesystem for an | ||
2262 | image and consist of the following classes: | ||
2263 | |||
2264 | - The ``rootfs-postcommands`` class, which defines filesystem | ||
2265 | post-processing functions for image recipes. | ||
2266 | |||
2267 | - The ``rootfs_deb`` class, which supports creation of root filesystems | ||
2268 | for images built using ``.deb`` packages. | ||
2269 | |||
2270 | - The ``rootfs_rpm`` class, which supports creation of root filesystems | ||
2271 | for images built using ``.rpm`` packages. | ||
2272 | |||
2273 | - The ``rootfs_ipk`` class, which supports creation of root filesystems | ||
2274 | for images built using ``.ipk`` packages. | ||
2275 | |||
2276 | - The ``rootfsdebugfiles`` class, which installs additional files found | ||
2277 | on the build host directly into the root filesystem. | ||
2278 | |||
2279 | The root filesystem is created from packages using one of the | ||
2280 | ``rootfs*.bbclass`` files as determined by the | ||
2281 | :term:`PACKAGE_CLASSES` variable. | ||
2282 | |||
2283 | For information on how root filesystem images are created, see the | ||
2284 | :ref:`image-generation-dev-environment`" | ||
2285 | section in the Yocto Project Overview and Concepts Manual. | ||
2286 | |||
2287 | .. _ref-classes-sanity: | ||
2288 | |||
2289 | ``sanity.bbclass`` | ||
2290 | ================== | ||
2291 | |||
2292 | The ``sanity`` class checks to see if prerequisite software is present | ||
2293 | on the host system so that users can be notified of potential problems | ||
2294 | that might affect their build. The class also performs basic user | ||
2295 | configuration checks from the ``local.conf`` configuration file to | ||
2296 | prevent common mistakes that cause build failures. Distribution policy | ||
2297 | usually determines whether to include this class. | ||
2298 | |||
2299 | .. _ref-classes-scons: | ||
2300 | |||
2301 | ``scons.bbclass`` | ||
2302 | ================= | ||
2303 | |||
2304 | The ``scons`` class supports recipes that need to build software that | ||
2305 | uses the SCons build system. You can use the | ||
2306 | :term:`EXTRA_OESCONS` variable to specify | ||
2307 | additional configuration options you want to pass SCons command line. | ||
2308 | |||
2309 | .. _ref-classes-sdl: | ||
2310 | |||
2311 | ``sdl.bbclass`` | ||
2312 | =============== | ||
2313 | |||
2314 | The ``sdl`` class supports recipes that need to build software that uses | ||
2315 | the Simple DirectMedia Layer (SDL) library. | ||
2316 | |||
2317 | .. _ref-classes-setuptools: | ||
2318 | |||
2319 | ``setuptools.bbclass`` | ||
2320 | ====================== | ||
2321 | |||
2322 | The ``setuptools`` class supports Python version 2.x extensions that use | ||
2323 | build systems based on ``setuptools``. If your recipe uses these build | ||
2324 | systems, the recipe needs to inherit the ``setuptools`` class. | ||
2325 | |||
2326 | .. _ref-classes-setuptools3: | ||
2327 | |||
2328 | ``setuptools3.bbclass`` | ||
2329 | ======================= | ||
2330 | |||
2331 | The ``setuptools3`` class supports Python version 3.x extensions that | ||
2332 | use build systems based on ``setuptools3``. If your recipe uses these | ||
2333 | build systems, the recipe needs to inherit the ``setuptools3`` class. | ||
2334 | |||
2335 | .. _ref-classes-sign_rpm: | ||
2336 | |||
2337 | ``sign_rpm.bbclass`` | ||
2338 | ==================== | ||
2339 | |||
2340 | The ``sign_rpm`` class supports generating signed RPM packages. | ||
2341 | |||
2342 | .. _ref-classes-sip: | ||
2343 | |||
2344 | ``sip.bbclass`` | ||
2345 | =============== | ||
2346 | |||
2347 | The ``sip`` class supports recipes that build or package SIP-based | ||
2348 | Python bindings. | ||
2349 | |||
2350 | .. _ref-classes-siteconfig: | ||
2351 | |||
2352 | ``siteconfig.bbclass`` | ||
2353 | ====================== | ||
2354 | |||
2355 | The ``siteconfig`` class provides functionality for handling site | ||
2356 | configuration. The class is used by the | ||
2357 | :ref:`autotools <ref-classes-autotools>` class to accelerate the | ||
2358 | :ref:`ref-tasks-configure` task. | ||
2359 | |||
2360 | .. _ref-classes-siteinfo: | ||
2361 | |||
2362 | ``siteinfo.bbclass`` | ||
2363 | ==================== | ||
2364 | |||
2365 | The ``siteinfo`` class provides information about the targets that might | ||
2366 | be needed by other classes or recipes. | ||
2367 | |||
2368 | As an example, consider Autotools, which can require tests that must | ||
2369 | execute on the target hardware. Since this is not possible in general | ||
2370 | when cross compiling, site information is used to provide cached test | ||
2371 | results so these tests can be skipped over but still make the correct | ||
2372 | values available. The ``meta/site directory`` contains test results | ||
2373 | sorted into different categories such as architecture, endianness, and | ||
2374 | the ``libc`` used. Site information provides a list of files containing | ||
2375 | data relevant to the current build in the ``CONFIG_SITE`` variable that | ||
2376 | Autotools automatically picks up. | ||
2377 | |||
2378 | The class also provides variables like ``SITEINFO_ENDIANNESS`` and | ||
2379 | ``SITEINFO_BITS`` that can be used elsewhere in the metadata. | ||
2380 | |||
2381 | .. _ref-classes-spdx: | ||
2382 | |||
2383 | ``spdx.bbclass`` | ||
2384 | ================ | ||
2385 | |||
2386 | The ``spdx`` class integrates real-time license scanning, generation of | ||
2387 | SPDX standard output, and verification of license information during the | ||
2388 | build. | ||
2389 | |||
2390 | .. note:: | ||
2391 | |||
2392 | This class is currently at the prototype stage in the 1.6 release. | ||
2393 | |||
2394 | .. _ref-classes-sstate: | ||
2395 | |||
2396 | ``sstate.bbclass`` | ||
2397 | ================== | ||
2398 | |||
2399 | The ``sstate`` class provides support for Shared State (sstate). By | ||
2400 | default, the class is enabled through the | ||
2401 | :term:`INHERIT_DISTRO` variable's default value. | ||
2402 | |||
2403 | For more information on sstate, see the | ||
2404 | ":ref:`overview-manual/overview-manual-concepts:shared state cache`" | ||
2405 | section in the Yocto Project Overview and Concepts Manual. | ||
2406 | |||
2407 | .. _ref-classes-staging: | ||
2408 | |||
2409 | ``staging.bbclass`` | ||
2410 | =================== | ||
2411 | |||
2412 | The ``staging`` class installs files into individual recipe work | ||
2413 | directories for sysroots. The class contains the following key tasks: | ||
2414 | |||
2415 | - The :ref:`ref-tasks-populate_sysroot` task, | ||
2416 | which is responsible for handing the files that end up in the recipe | ||
2417 | sysroots. | ||
2418 | |||
2419 | - The | ||
2420 | :ref:`ref-tasks-prepare_recipe_sysroot` | ||
2421 | task (a "partner" task to the ``populate_sysroot`` task), which | ||
2422 | installs the files into the individual recipe work directories (i.e. | ||
2423 | :term:`WORKDIR`). | ||
2424 | |||
2425 | The code in the ``staging`` class is complex and basically works in two | ||
2426 | stages: | ||
2427 | |||
2428 | - *Stage One:* The first stage addresses recipes that have files they | ||
2429 | want to share with other recipes that have dependencies on the | ||
2430 | originating recipe. Normally these dependencies are installed through | ||
2431 | the :ref:`ref-tasks-install` task into | ||
2432 | ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task | ||
2433 | copies a subset of these files into ``${SYSROOT_DESTDIR}``. This | ||
2434 | subset of files is controlled by the | ||
2435 | :term:`SYSROOT_DIRS`, | ||
2436 | :term:`SYSROOT_DIRS_NATIVE`, and | ||
2437 | :term:`SYSROOT_DIRS_BLACKLIST` | ||
2438 | variables. | ||
2439 | |||
2440 | .. note:: | ||
2441 | |||
2442 | Additionally, a recipe can customize the files further by | ||
2443 | declaring a processing function in the | ||
2444 | SYSROOT_PREPROCESS_FUNCS | ||
2445 | variable. | ||
2446 | |||
2447 | A shared state (sstate) object is built from these files and the | ||
2448 | files are placed into a subdirectory of | ||
2449 | ```tmp/sysroots-components/`` <#structure-build-tmp-sysroots-components>`__. | ||
2450 | The files are scanned for hardcoded paths to the original | ||
2451 | installation location. If the location is found in text files, the | ||
2452 | hardcoded locations are replaced by tokens and a list of the files | ||
2453 | needing such replacements is created. These adjustments are referred | ||
2454 | to as "FIXMEs". The list of files that are scanned for paths is | ||
2455 | controlled by the :term:`SSTATE_SCAN_FILES` | ||
2456 | variable. | ||
2457 | |||
2458 | - *Stage Two:* The second stage addresses recipes that want to use | ||
2459 | something from another recipe and declare a dependency on that recipe | ||
2460 | through the :term:`DEPENDS` variable. The recipe will | ||
2461 | have a | ||
2462 | :ref:`ref-tasks-prepare_recipe_sysroot` | ||
2463 | task and when this task executes, it creates the ``recipe-sysroot`` | ||
2464 | and ``recipe-sysroot-native`` in the recipe work directory (i.e. | ||
2465 | :term:`WORKDIR`). The OpenEmbedded build system | ||
2466 | creates hard links to copies of the relevant files from | ||
2467 | ``sysroots-components`` into the recipe work directory. | ||
2468 | |||
2469 | .. note:: | ||
2470 | |||
2471 | If hard links are not possible, the build system uses actual | ||
2472 | copies. | ||
2473 | |||
2474 | The build system then addresses any "FIXMEs" to paths as defined from | ||
2475 | the list created in the first stage. | ||
2476 | |||
2477 | Finally, any files in ``${bindir}`` within the sysroot that have the | ||
2478 | prefix "``postinst-``" are executed. | ||
2479 | |||
2480 | .. note:: | ||
2481 | |||
2482 | Although such sysroot post installation scripts are not | ||
2483 | recommended for general use, the files do allow some issues such | ||
2484 | as user creation and module indexes to be addressed. | ||
2485 | |||
2486 | Because recipes can have other dependencies outside of ``DEPENDS`` | ||
2487 | (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``), | ||
2488 | the sysroot creation function ``extend_recipe_sysroot`` is also added | ||
2489 | as a pre-function for those tasks whose dependencies are not through | ||
2490 | ``DEPENDS`` but operate similarly. | ||
2491 | |||
2492 | When installing dependencies into the sysroot, the code traverses the | ||
2493 | dependency graph and processes dependencies in exactly the same way | ||
2494 | as the dependencies would or would not be when installed from sstate. | ||
2495 | This processing means, for example, a native tool would have its | ||
2496 | native dependencies added but a target library would not have its | ||
2497 | dependencies traversed or installed. The same sstate dependency code | ||
2498 | is used so that builds should be identical regardless of whether | ||
2499 | sstate was used or not. For a closer look, see the | ||
2500 | ``setscene_depvalid()`` function in the | ||
2501 | :ref:`sstate <ref-classes-sstate>` class. | ||
2502 | |||
2503 | The build system is careful to maintain manifests of the files it | ||
2504 | installs so that any given dependency can be installed as needed. The | ||
2505 | sstate hash of the installed item is also stored so that if it | ||
2506 | changes, the build system can reinstall it. | ||
2507 | |||
2508 | .. _ref-classes-syslinux: | ||
2509 | |||
2510 | ``syslinux.bbclass`` | ||
2511 | ==================== | ||
2512 | |||
2513 | The ``syslinux`` class provides syslinux-specific functions for building | ||
2514 | bootable images. | ||
2515 | |||
2516 | The class supports the following variables: | ||
2517 | |||
2518 | - :term:`INITRD`: Indicates list of filesystem images to | ||
2519 | concatenate and use as an initial RAM disk (initrd). This variable is | ||
2520 | optional. | ||
2521 | |||
2522 | - :term:`ROOTFS`: Indicates a filesystem image to include | ||
2523 | as the root filesystem. This variable is optional. | ||
2524 | |||
2525 | - :term:`AUTO_SYSLINUXMENU`: Enables creating | ||
2526 | an automatic menu when set to "1". | ||
2527 | |||
2528 | - :term:`LABELS`: Lists targets for automatic | ||
2529 | configuration. | ||
2530 | |||
2531 | - :term:`APPEND`: Lists append string overrides for each | ||
2532 | label. | ||
2533 | |||
2534 | - :term:`SYSLINUX_OPTS`: Lists additional options | ||
2535 | to add to the syslinux file. Semicolon characters separate multiple | ||
2536 | options. | ||
2537 | |||
2538 | - :term:`SYSLINUX_SPLASH`: Lists a background | ||
2539 | for the VGA boot menu when you are using the boot menu. | ||
2540 | |||
2541 | - :term:`SYSLINUX_DEFAULT_CONSOLE`: Set | ||
2542 | to "console=ttyX" to change kernel boot default console. | ||
2543 | |||
2544 | - :term:`SYSLINUX_SERIAL`: Sets an alternate | ||
2545 | serial port. Or, turns off serial when the variable is set with an | ||
2546 | empty string. | ||
2547 | |||
2548 | - :term:`SYSLINUX_SERIAL_TTY`: Sets an | ||
2549 | alternate "console=tty..." kernel boot argument. | ||
2550 | |||
2551 | .. _ref-classes-systemd: | ||
2552 | |||
2553 | ``systemd.bbclass`` | ||
2554 | =================== | ||
2555 | |||
2556 | The ``systemd`` class provides support for recipes that install systemd | ||
2557 | unit files. | ||
2558 | |||
2559 | The functionality for this class is disabled unless you have "systemd" | ||
2560 | in :term:`DISTRO_FEATURES`. | ||
2561 | |||
2562 | Under this class, the recipe or Makefile (i.e. whatever the recipe is | ||
2563 | calling during the :ref:`ref-tasks-install` task) | ||
2564 | installs unit files into | ||
2565 | ``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit | ||
2566 | files being installed go into packages other than the main package, you | ||
2567 | need to set :term:`SYSTEMD_PACKAGES` in your | ||
2568 | recipe to identify the packages in which the files will be installed. | ||
2569 | |||
2570 | You should set :term:`SYSTEMD_SERVICE` to the | ||
2571 | name of the service file. You should also use a package name override to | ||
2572 | indicate the package to which the value applies. If the value applies to | ||
2573 | the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here | ||
2574 | is an example from the connman recipe: | ||
2575 | :: | ||
2576 | |||
2577 | SYSTEMD_SERVICE_${PN} = "connman.service" | ||
2578 | |||
2579 | Services are set up to start on boot automatically | ||
2580 | unless you have set | ||
2581 | :term:`SYSTEMD_AUTO_ENABLE` to "disable". | ||
2582 | |||
2583 | For more information on ``systemd``, see the | ||
2584 | ":ref:`dev-manual/dev-manual-common-tasks:selecting an initialization manager`" | ||
2585 | section in the Yocto Project Development Tasks Manual. | ||
2586 | |||
2587 | .. _ref-classes-systemd-boot: | ||
2588 | |||
2589 | ``systemd-boot.bbclass`` | ||
2590 | ======================== | ||
2591 | |||
2592 | The ``systemd-boot`` class provides functions specific to the | ||
2593 | systemd-boot bootloader for building bootable images. This is an | ||
2594 | internal class and is not intended to be used directly. | ||
2595 | |||
2596 | .. note:: | ||
2597 | |||
2598 | The | ||
2599 | systemd-boot | ||
2600 | class is a result from merging the | ||
2601 | gummiboot | ||
2602 | class used in previous Yocto Project releases with the | ||
2603 | systemd | ||
2604 | project. | ||
2605 | |||
2606 | Set the :term:`EFI_PROVIDER` variable to | ||
2607 | "systemd-boot" to use this class. Doing so creates a standalone EFI | ||
2608 | bootloader that is not dependent on systemd. | ||
2609 | |||
2610 | For information on more variables used and supported in this class, see | ||
2611 | the :term:`SYSTEMD_BOOT_CFG`, | ||
2612 | :term:`SYSTEMD_BOOT_ENTRIES`, and | ||
2613 | :term:`SYSTEMD_BOOT_TIMEOUT` variables. | ||
2614 | |||
2615 | You can also see the `Systemd-boot | ||
2616 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__ | ||
2617 | for more information. | ||
2618 | |||
2619 | .. _ref-classes-terminal: | ||
2620 | |||
2621 | ``terminal.bbclass`` | ||
2622 | ==================== | ||
2623 | |||
2624 | The ``terminal`` class provides support for starting a terminal session. | ||
2625 | The :term:`OE_TERMINAL` variable controls which | ||
2626 | terminal emulator is used for the session. | ||
2627 | |||
2628 | Other classes use the ``terminal`` class anywhere a separate terminal | ||
2629 | session needs to be started. For example, the | ||
2630 | :ref:`patch <ref-classes-patch>` class assuming | ||
2631 | :term:`PATCHRESOLVE` is set to "user", the | ||
2632 | :ref:`cml1 <ref-classes-cml1>` class, and the | ||
2633 | :ref:`devshell <ref-classes-devshell>` class all use the ``terminal`` | ||
2634 | class. | ||
2635 | |||
2636 | .. _ref-classes-testimage*: | ||
2637 | |||
2638 | ``testimage*.bbclass`` | ||
2639 | ====================== | ||
2640 | |||
2641 | The ``testimage*`` classes support running automated tests against | ||
2642 | images using QEMU and on actual hardware. The classes handle loading the | ||
2643 | tests and starting the image. To use the classes, you need to perform | ||
2644 | steps to set up the environment. | ||
2645 | |||
2646 | .. note:: | ||
2647 | |||
2648 | Best practices include using | ||
2649 | IMAGE_CLASSES | ||
2650 | rather than | ||
2651 | INHERIT | ||
2652 | to inherit the | ||
2653 | testimage | ||
2654 | class for automated image testing. | ||
2655 | |||
2656 | The tests are commands that run on the target system over ``ssh``. Each | ||
2657 | test is written in Python and makes use of the ``unittest`` module. | ||
2658 | |||
2659 | The ``testimage.bbclass`` runs tests on an image when called using the | ||
2660 | following: | ||
2661 | :: | ||
2662 | |||
2663 | $ bitbake -c testimage image | ||
2664 | |||
2665 | The ``testimage-auto`` class | ||
2666 | runs tests on an image after the image is constructed (i.e. | ||
2667 | :term:`TESTIMAGE_AUTO` must be set to "1"). | ||
2668 | |||
2669 | For information on how to enable, run, and create new tests, see the | ||
2670 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
2671 | section in the Yocto Project Development Tasks Manual. | ||
2672 | |||
2673 | .. _ref-classes-testsdk: | ||
2674 | |||
2675 | ``testsdk.bbclass`` | ||
2676 | =================== | ||
2677 | |||
2678 | This class supports running automated tests against software development | ||
2679 | kits (SDKs). The ``testsdk`` class runs tests on an SDK when called | ||
2680 | using the following: | ||
2681 | :: | ||
2682 | |||
2683 | $ bitbake -c testsdk image | ||
2684 | |||
2685 | .. note:: | ||
2686 | |||
2687 | Best practices include using | ||
2688 | IMAGE_CLASSES | ||
2689 | rather than | ||
2690 | INHERIT | ||
2691 | to inherit the | ||
2692 | testsdk | ||
2693 | class for automated SDK testing. | ||
2694 | |||
2695 | .. _ref-classes-texinfo: | ||
2696 | |||
2697 | ``texinfo.bbclass`` | ||
2698 | =================== | ||
2699 | |||
2700 | This class should be inherited by recipes whose upstream packages invoke | ||
2701 | the ``texinfo`` utilities at build-time. Native and cross recipes are | ||
2702 | made to use the dummy scripts provided by ``texinfo-dummy-native``, for | ||
2703 | improved performance. Target architecture recipes use the genuine | ||
2704 | Texinfo utilities. By default, they use the Texinfo utilities on the | ||
2705 | host system. | ||
2706 | |||
2707 | .. note:: | ||
2708 | |||
2709 | If you want to use the Texinfo recipe shipped with the build system, | ||
2710 | you can remove "texinfo-native" from | ||
2711 | ASSUME_PROVIDED | ||
2712 | and makeinfo from | ||
2713 | SANITY_REQUIRED_UTILITIES | ||
2714 | . | ||
2715 | |||
2716 | .. _ref-classes-tinderclient: | ||
2717 | |||
2718 | ``tinderclient.bbclass`` | ||
2719 | ======================== | ||
2720 | |||
2721 | The ``tinderclient`` class submits build results to an external | ||
2722 | Tinderbox instance. | ||
2723 | |||
2724 | .. note:: | ||
2725 | |||
2726 | This class is currently unmaintained. | ||
2727 | |||
2728 | .. _ref-classes-toaster: | ||
2729 | |||
2730 | ``toaster.bbclass`` | ||
2731 | =================== | ||
2732 | |||
2733 | The ``toaster`` class collects information about packages and images and | ||
2734 | sends them as events that the BitBake user interface can receive. The | ||
2735 | class is enabled when the Toaster user interface is running. | ||
2736 | |||
2737 | This class is not intended to be used directly. | ||
2738 | |||
2739 | .. _ref-classes-toolchain-scripts: | ||
2740 | |||
2741 | ``toolchain-scripts.bbclass`` | ||
2742 | ============================= | ||
2743 | |||
2744 | The ``toolchain-scripts`` class provides the scripts used for setting up | ||
2745 | the environment for installed SDKs. | ||
2746 | |||
2747 | .. _ref-classes-typecheck: | ||
2748 | |||
2749 | ``typecheck.bbclass`` | ||
2750 | ===================== | ||
2751 | |||
2752 | The ``typecheck`` class provides support for validating the values of | ||
2753 | variables set at the configuration level against their defined types. | ||
2754 | The OpenEmbedded build system allows you to define the type of a | ||
2755 | variable using the "type" varflag. Here is an example: | ||
2756 | :: | ||
2757 | |||
2758 | IMAGE_FEATURES[type] = "list" | ||
2759 | |||
2760 | .. _ref-classes-uboot-config: | ||
2761 | |||
2762 | ``uboot-config.bbclass`` | ||
2763 | ======================== | ||
2764 | |||
2765 | The ``uboot-config`` class provides support for U-Boot configuration for | ||
2766 | a machine. Specify the machine in your recipe as follows: | ||
2767 | :: | ||
2768 | |||
2769 | UBOOT_CONFIG ??= <default> | ||
2770 | UBOOT_CONFIG[foo] = "config,images" | ||
2771 | |||
2772 | You can also specify the machine using this method: | ||
2773 | :: | ||
2774 | |||
2775 | UBOOT_MACHINE = "config" | ||
2776 | |||
2777 | See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional | ||
2778 | information. | ||
2779 | |||
2780 | .. _ref-classes-uninative: | ||
2781 | |||
2782 | ``uninative.bbclass`` | ||
2783 | ===================== | ||
2784 | |||
2785 | Attempts to isolate the build system from the host distribution's C | ||
2786 | library in order to make re-use of native shared state artifacts across | ||
2787 | different host distributions practical. With this class enabled, a | ||
2788 | tarball containing a pre-built C library is downloaded at the start of | ||
2789 | the build. In the Poky reference distribution this is enabled by default | ||
2790 | through ``meta/conf/distro/include/yocto-uninative.inc``. Other | ||
2791 | distributions that do not derive from poky can also | ||
2792 | "``require conf/distro/include/yocto-uninative.inc``" to use this. | ||
2793 | Alternatively if you prefer, you can build the uninative-tarball recipe | ||
2794 | yourself, publish the resulting tarball (e.g. via HTTP) and set | ||
2795 | ``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an | ||
2796 | example, see the ``meta/conf/distro/include/yocto-uninative.inc``. | ||
2797 | |||
2798 | The ``uninative`` class is also used unconditionally by the extensible | ||
2799 | SDK. When building the extensible SDK, ``uninative-tarball`` is built | ||
2800 | and the resulting tarball is included within the SDK. | ||
2801 | |||
2802 | .. _ref-classes-update-alternatives: | ||
2803 | |||
2804 | ``update-alternatives.bbclass`` | ||
2805 | =============================== | ||
2806 | |||
2807 | The ``update-alternatives`` class helps the alternatives system when | ||
2808 | multiple sources provide the same command. This situation occurs when | ||
2809 | several programs that have the same or similar function are installed | ||
2810 | with the same name. For example, the ``ar`` command is available from | ||
2811 | the ``busybox``, ``binutils`` and ``elfutils`` packages. The | ||
2812 | ``update-alternatives`` class handles renaming the binaries so that | ||
2813 | multiple packages can be installed without conflicts. The ``ar`` command | ||
2814 | still works regardless of which packages are installed or subsequently | ||
2815 | removed. The class renames the conflicting binary in each package and | ||
2816 | symlinks the highest priority binary during installation or removal of | ||
2817 | packages. | ||
2818 | |||
2819 | To use this class, you need to define a number of variables: | ||
2820 | |||
2821 | - :term:`ALTERNATIVE` | ||
2822 | |||
2823 | - :term:`ALTERNATIVE_LINK_NAME` | ||
2824 | |||
2825 | - :term:`ALTERNATIVE_TARGET` | ||
2826 | |||
2827 | - :term:`ALTERNATIVE_PRIORITY` | ||
2828 | |||
2829 | These variables list alternative commands needed by a package, provide | ||
2830 | pathnames for links, default links for targets, and so forth. For | ||
2831 | details on how to use this class, see the comments in the | ||
2832 | :yocto_git:`update-alternatives.bbclass </cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass>` | ||
2833 | file. | ||
2834 | |||
2835 | .. note:: | ||
2836 | |||
2837 | You can use the | ||
2838 | update-alternatives | ||
2839 | command directly in your recipes. However, this class simplifies | ||
2840 | things in most cases. | ||
2841 | |||
2842 | .. _ref-classes-update-rc.d: | ||
2843 | |||
2844 | ``update-rc.d.bbclass`` | ||
2845 | ======================= | ||
2846 | |||
2847 | The ``update-rc.d`` class uses ``update-rc.d`` to safely install an | ||
2848 | initialization script on behalf of the package. The OpenEmbedded build | ||
2849 | system takes care of details such as making sure the script is stopped | ||
2850 | before a package is removed and started when the package is installed. | ||
2851 | |||
2852 | Three variables control this class: ``INITSCRIPT_PACKAGES``, | ||
2853 | ``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links | ||
2854 | for details. | ||
2855 | |||
2856 | .. _ref-classes-useradd: | ||
2857 | |||
2858 | ``useradd*.bbclass`` | ||
2859 | ==================== | ||
2860 | |||
2861 | The ``useradd*`` classes support the addition of users or groups for | ||
2862 | usage by the package on the target. For example, if you have packages | ||
2863 | that contain system services that should be run under their own user or | ||
2864 | group, you can use these classes to enable creation of the user or | ||
2865 | group. The ``meta-skeleton/recipes-skeleton/useradd/useradd-example.bb`` | ||
2866 | recipe in the :term:`Source Directory` provides a simple | ||
2867 | example that shows how to add three users and groups to two packages. | ||
2868 | See the ``useradd-example.bb`` recipe for more information on how to use | ||
2869 | these classes. | ||
2870 | |||
2871 | The ``useradd_base`` class provides basic functionality for user or | ||
2872 | groups settings. | ||
2873 | |||
2874 | The ``useradd*`` classes support the | ||
2875 | :term:`USERADD_PACKAGES`, | ||
2876 | :term:`USERADD_PARAM`, | ||
2877 | :term:`GROUPADD_PARAM`, and | ||
2878 | :term:`GROUPMEMS_PARAM` variables. | ||
2879 | |||
2880 | The ``useradd-staticids`` class supports the addition of users or groups | ||
2881 | that have static user identification (``uid``) and group identification | ||
2882 | (``gid``) values. | ||
2883 | |||
2884 | The default behavior of the OpenEmbedded build system for assigning | ||
2885 | ``uid`` and ``gid`` values when packages add users and groups during | ||
2886 | package install time is to add them dynamically. This works fine for | ||
2887 | programs that do not care what the values of the resulting users and | ||
2888 | groups become. In these cases, the order of the installation determines | ||
2889 | the final ``uid`` and ``gid`` values. However, if non-deterministic | ||
2890 | ``uid`` and ``gid`` values are a problem, you can override the default, | ||
2891 | dynamic application of these values by setting static values. When you | ||
2892 | set static values, the OpenEmbedded build system looks in | ||
2893 | :term:`BBPATH` for ``files/passwd`` and ``files/group`` | ||
2894 | files for the values. | ||
2895 | |||
2896 | To use static ``uid`` and ``gid`` values, you need to set some | ||
2897 | variables. See the :term:`USERADDEXTENSION`, | ||
2898 | :term:`USERADD_UID_TABLES`, | ||
2899 | :term:`USERADD_GID_TABLES`, and | ||
2900 | :term:`USERADD_ERROR_DYNAMIC` variables. | ||
2901 | You can also see the :ref:`useradd <ref-classes-useradd>` class for | ||
2902 | additional information. | ||
2903 | |||
2904 | .. note:: | ||
2905 | |||
2906 | You do not use the | ||
2907 | useradd-staticids | ||
2908 | class directly. You either enable or disable the class by setting the | ||
2909 | USERADDEXTENSION | ||
2910 | variable. If you enable or disable the class in a configured system, | ||
2911 | TMPDIR | ||
2912 | might contain incorrect | ||
2913 | uid | ||
2914 | and | ||
2915 | gid | ||
2916 | values. Deleting the | ||
2917 | TMPDIR | ||
2918 | directory will correct this condition. | ||
2919 | |||
2920 | .. _ref-classes-utility-tasks: | ||
2921 | |||
2922 | ``utility-tasks.bbclass`` | ||
2923 | ========================= | ||
2924 | |||
2925 | The ``utility-tasks`` class provides support for various "utility" type | ||
2926 | tasks that are applicable to all recipes, such as | ||
2927 | :ref:`ref-tasks-clean` and | ||
2928 | :ref:`ref-tasks-listtasks`. | ||
2929 | |||
2930 | This class is enabled by default because it is inherited by the | ||
2931 | :ref:`base <ref-classes-base>` class. | ||
2932 | |||
2933 | .. _ref-classes-utils: | ||
2934 | |||
2935 | ``utils.bbclass`` | ||
2936 | ================= | ||
2937 | |||
2938 | The ``utils`` class provides some useful Python functions that are | ||
2939 | typically used in inline Python expressions (e.g. ``${@...}``). One | ||
2940 | example use is for ``bb.utils.contains()``. | ||
2941 | |||
2942 | This class is enabled by default because it is inherited by the | ||
2943 | :ref:`base <ref-classes-base>` class. | ||
2944 | |||
2945 | .. _ref-classes-vala: | ||
2946 | |||
2947 | ``vala.bbclass`` | ||
2948 | ================ | ||
2949 | |||
2950 | The ``vala`` class supports recipes that need to build software written | ||
2951 | using the Vala programming language. | ||
2952 | |||
2953 | .. _ref-classes-waf: | ||
2954 | |||
2955 | ``waf.bbclass`` | ||
2956 | =============== | ||
2957 | |||
2958 | The ``waf`` class supports recipes that need to build software that uses | ||
2959 | the Waf build system. You can use the | ||
2960 | :term:`EXTRA_OECONF` or | ||
2961 | :term:`PACKAGECONFIG_CONFARGS` variables | ||
2962 | to specify additional configuration options to be passed on the Waf | ||
2963 | command line. | ||
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index f9bbddd724..1dcd5fdd03 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-classes'> | 6 | <chapter id='ref-classes'> |
6 | <title>Classes</title> | 7 | <title>Classes</title> |
@@ -1742,6 +1743,12 @@ This check was removed for YP 2.3 release | |||
1742 | </note> | 1743 | </note> |
1743 | </para></listitem> | 1744 | </para></listitem> |
1744 | --> | 1745 | --> |
1746 | <listitem><para><emphasis><filename>unlisted-pkg-lics:</filename></emphasis> | ||
1747 | Checks that all declared licenses applying for a package are also | ||
1748 | declared on the recipe level (i.e. any license in | ||
1749 | <filename>LICENSE_*</filename> should appear in | ||
1750 | <link linkend='var-LICENSE'><filename>LICENSE</filename></link>). | ||
1751 | </para></listitem> | ||
1745 | <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis> | 1752 | <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis> |
1746 | Checks for dynamic library load paths (rpaths) in the binaries that | 1753 | Checks for dynamic library load paths (rpaths) in the binaries that |
1747 | by default on a standard system are searched by the linker (e.g. | 1754 | by default on a standard system are searched by the linker (e.g. |
@@ -1873,8 +1880,82 @@ This check was removed for YP 2.3 release | |||
1873 | 1880 | ||
1874 | <para> | 1881 | <para> |
1875 | The <filename>kernel-fitimage</filename> class provides support to | 1882 | The <filename>kernel-fitimage</filename> class provides support to |
1876 | pack zImages. | 1883 | pack a kernel Image, device trees and a RAM disk into a single |
1884 | FIT image. In theory, a FIT image can support any number of kernels, | ||
1885 | RAM disks and device-trees. | ||
1886 | However, <filename>kernel-fitimage</filename> currently only supports | ||
1887 | limited usescases: just one kernel image, an optional RAM disk, and | ||
1888 | any number of device tree. | ||
1889 | </para> | ||
1890 | |||
1891 | <para> | ||
1892 | To create a FIT image, it is required that | ||
1893 | <filename><link linkend='var-KERNEL_CLASSES'>KERNEL_CLASSES</link></filename> | ||
1894 | is set to "kernel-fitimage" and | ||
1895 | <filename><link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link></filename> | ||
1896 | is set to "fitImage". | ||
1897 | </para> | ||
1898 | |||
1899 | <para> | ||
1900 | The options for the device tree compiler passed to mkimage -D feature | ||
1901 | when creating the FIT image are specified using the | ||
1902 | <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename> | ||
1903 | variable. | ||
1904 | </para> | ||
1905 | |||
1906 | <para> | ||
1907 | Only a single kernel can be added to the FIT image created by | ||
1908 | <filename>kernel-fitimage</filename> and the kernel image in FIT is | ||
1909 | mandatory. | ||
1910 | The address where the kernel image is to be loaded by U-boot is | ||
1911 | specified by | ||
1912 | <filename><link linkend='var-UBOOT_LOADADDRESS'>UBOOT_LOADADDRESS</link></filename> | ||
1913 | and the entrypoint by | ||
1914 | <filename><link linkend='var-UBOOT_ENTRYPOINT'>UBOOT_ENTRYPOINT</link></filename>. | ||
1915 | </para> | ||
1916 | |||
1917 | <para> | ||
1918 | Multiple device trees can be added to the FIT image created by | ||
1919 | <filename>kernel-fitimage</filename> and the device tree is optional. | ||
1920 | The address where the device tree is to be loaded by U-boot is | ||
1921 | specified by | ||
1922 | <filename><link linkend='var-UBOOT_DTBO_LOADADDRESS'>UBOOT_DTBO_LOADADDRESS</link></filename> | ||
1923 | for device tree overlays and by | ||
1924 | <filename><link linkend='var-UBOOT_DTB_LOADADDRESS'>UBOOT_DTB_LOADADDRESS</link></filename> | ||
1925 | for device tree binaries. | ||
1926 | </para> | ||
1927 | |||
1928 | <para> | ||
1929 | Only a single RAM disk can be added to the FIT image created by | ||
1930 | <filename>kernel-fitimage</filename> and the RAM disk in FIT is | ||
1931 | optional. | ||
1932 | The address where the RAM disk image is to be loaded by U-boot | ||
1933 | is specified by | ||
1934 | <filename><link linkend='var-UBOOT_RD_LOADADDRESS'>UBOOT_RD_LOADADDRESS</link></filename> | ||
1935 | and the entrypoint by | ||
1936 | <filename><link linkend='var-UBOOT_RD_ENTRYPOINT'>UBOOT_RD_ENTRYPOINT</link></filename>. | ||
1937 | The ramdisk is added to FIT image when | ||
1938 | <filename><link linkend='var-INITRAMFS_IMAGE'>INITRAMFS_IMAGE</link></filename> | ||
1939 | is specified. | ||
1940 | </para> | ||
1941 | |||
1942 | <para> | ||
1943 | The FIT image generated by <filename>kernel-fitimage</filename> class | ||
1944 | is signed when the variables | ||
1945 | <filename><link linkend='var-UBOOT_SIGN_ENABLE'>UBOOT_SIGN_ENABLE</link></filename>, | ||
1946 | <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>, | ||
1947 | <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> | ||
1948 | and | ||
1949 | <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename> | ||
1950 | are set appropriately. | ||
1951 | The default values used for | ||
1952 | <filename><link linkend='var-FIT_HASH_ALG'>FIT_HASH_ALG</link></filename> | ||
1953 | and | ||
1954 | <filename><link linkend='var-FIT_SIGN_ALG'>FIT_SIGN_ALG</link></filename> | ||
1955 | in <filename>kernel-fitimage</filename> are "sha256" and "rsa2048" | ||
1956 | respectively. | ||
1877 | </para> | 1957 | </para> |
1958 | |||
1878 | </section> | 1959 | </section> |
1879 | 1960 | ||
1880 | <section id='ref-classes-kernel-grub'> | 1961 | <section id='ref-classes-kernel-grub'> |
diff --git a/documentation/ref-manual/ref-devtool-reference.rst b/documentation/ref-manual/ref-devtool-reference.rst new file mode 100644 index 0000000000..eaca45ae25 --- /dev/null +++ b/documentation/ref-manual/ref-devtool-reference.rst | |||
@@ -0,0 +1,625 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | *************************** | ||
4 | ``devtool`` Quick Reference | ||
5 | *************************** | ||
6 | |||
7 | The ``devtool`` command-line tool provides a number of features that | ||
8 | help you build, test, and package software. This command is available | ||
9 | alongside the ``bitbake`` command. Additionally, the ``devtool`` command | ||
10 | is a key part of the extensible SDK. | ||
11 | |||
12 | This chapter provides a Quick Reference for the ``devtool`` command. For | ||
13 | more information on how to apply the command when using the extensible | ||
14 | SDK, see the ":doc:`../sdk-manual/sdk-extensible`" chapter in the Yocto | ||
15 | Project Application Development and the Extensible Software Development | ||
16 | Kit (eSDK) manual. | ||
17 | |||
18 | .. _devtool-getting-help: | ||
19 | |||
20 | Getting Help | ||
21 | ============ | ||
22 | |||
23 | The ``devtool`` command line is organized similarly to Git in that it | ||
24 | has a number of sub-commands for each function. You can run | ||
25 | ``devtool --help`` to see all the commands: | ||
26 | :: | ||
27 | |||
28 | $ devtool -h | ||
29 | NOTE: Starting bitbake server... | ||
30 | usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] [--color COLOR] [-h] <subcommand> ... | ||
31 | |||
32 | OpenEmbedded development tool | ||
33 | |||
34 | options: | ||
35 | --basepath BASEPATH Base directory of SDK / build directory | ||
36 | --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it from the metadata | ||
37 | -d, --debug Enable debug output | ||
38 | -q, --quiet Print only errors | ||
39 | --color COLOR Colorize output (where COLOR is auto, always, never) | ||
40 | -h, --help show this help message and exit | ||
41 | |||
42 | subcommands: | ||
43 | Beginning work on a recipe: | ||
44 | add Add a new recipe | ||
45 | modify Modify the source for an existing recipe | ||
46 | upgrade Upgrade an existing recipe | ||
47 | Getting information: | ||
48 | status Show workspace status | ||
49 | latest-version Report the latest version of an existing recipe | ||
50 | check-upgrade-status Report upgradability for multiple (or all) recipes | ||
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 | |||
80 | As directed in the general help output, you can | ||
81 | get more syntax on a specific command by providing the command name and | ||
82 | using "--help": | ||
83 | :: | ||
84 | |||
85 | $ devtool add --help | ||
86 | NOTE: Starting bitbake server... | ||
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] | ||
88 | [--provides PROVIDES] | ||
89 | [recipename] [srctree] [fetchuri] | ||
90 | |||
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. | ||
92 | |||
93 | arguments: | ||
94 | recipename Name for new recipe to add (just name - no version, path or extension). If not specified, will attempt to auto-detect it. | ||
95 | srctree Path to external source tree. If not specified, a subdirectory of /media/build1/poky/build/workspace/sources will be used. | ||
96 | fetchuri Fetch the specified URI and extract it to create the source tree | ||
97 | |||
98 | options: | ||
99 | -h, --help show this help message and exit | ||
100 | --same-dir, -s Build in same directory as source | ||
101 | --no-same-dir Force build in a separate build directory | ||
102 | --fetch URI, -f URI Fetch the specified URI and extract it to create the source tree (deprecated - pass as positional argument instead) | ||
103 | --npm-dev For npm, also fetch devDependencies | ||
104 | --version VERSION, -V VERSION | ||
105 | Version to use within recipe (PV) | ||
106 | --no-git, -g If fetching source, do not set up source tree as a git repository | ||
107 | --srcrev SRCREV, -S SRCREV | ||
108 | Source revision to fetch if fetching from an SCM such as git (default latest) | ||
109 | --autorev, -a When fetching from a git repository, set SRCREV in the recipe to a floating revision instead of fixed | ||
110 | --srcbranch SRCBRANCH, -B SRCBRANCH | ||
111 | Branch in source repository if fetching from an SCM such as git (default master) | ||
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. | ||
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 | ||
118 | |||
119 | .. _devtool-the-workspace-layer-structure: | ||
120 | |||
121 | The Workspace Layer Structure | ||
122 | ============================= | ||
123 | |||
124 | ``devtool`` uses a "Workspace" layer in which to accomplish builds. This | ||
125 | layer is not specific to any single ``devtool`` command but is rather a | ||
126 | common working area used across the tool. | ||
127 | |||
128 | The following figure shows the workspace structure: | ||
129 | |||
130 | .. image:: figures/build-workspace-directory.png | ||
131 | :align: center | ||
132 | :scale: 70% | ||
133 | |||
134 | :: | ||
135 | |||
136 | attic - A directory created if devtool believes it must preserve | ||
137 | anything when you run "devtool reset". For example, if you | ||
138 | run "devtool add", make changes to the recipe, and then | ||
139 | run "devtool reset", devtool takes notice that the file has | ||
140 | been changed and moves it into the attic should you still | ||
141 | want the recipe. | ||
142 | |||
143 | README - Provides information on what is in workspace layer and how to | ||
144 | manage it. | ||
145 | |||
146 | .devtool_md5 - A checksum file used by devtool. | ||
147 | |||
148 | appends - A directory that contains *.bbappend files, which point to | ||
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. | ||
163 | |||
164 | .. _devtool-adding-a-new-recipe-to-the-workspace: | ||
165 | |||
166 | Adding a New Recipe to the Workspace Layer | ||
167 | ========================================== | ||
168 | |||
169 | Use the ``devtool add`` command to add a new recipe to the workspace | ||
170 | layer. The recipe you add should not exist - ``devtool`` creates it for | ||
171 | you. The source files the recipe uses should exist in an external area. | ||
172 | |||
173 | The following example creates and adds a new recipe named ``jackson`` to | ||
174 | a workspace layer the tool creates. The source code built by the recipes | ||
175 | resides in ``/home/user/sources/jackson``: | ||
176 | :: | ||
177 | |||
178 | $ devtool add jackson /home/user/sources/jackson | ||
179 | |||
180 | If you add a recipe and the workspace layer does not exist, the command | ||
181 | creates the layer and populates it as described in "`The Workspace Layer | ||
182 | Structure <#devtool-the-workspace-layer-structure>`__" section. | ||
183 | |||
184 | Running ``devtool add`` when the workspace layer exists causes the tool | ||
185 | to add the recipe, append files, and source files into the existing | ||
186 | workspace layer. The ``.bbappend`` file is created to point to the | ||
187 | external source tree. | ||
188 | |||
189 | .. note:: | ||
190 | |||
191 | If your recipe has runtime dependencies defined, you must be sure | ||
192 | that these packages exist on the target hardware before attempting to | ||
193 | run your application. If dependent packages (e.g. libraries) do not | ||
194 | exist on the target, your application, when run, will fail to find | ||
195 | those functions. For more information, see the | ||
196 | ":ref:`ref-manual/ref-devtool-reference:deploying your software on the target machine`" | ||
197 | section. | ||
198 | |||
199 | By default, ``devtool add`` uses the latest revision (i.e. master) when | ||
200 | unpacking files from a remote URI. In some cases, you might want to | ||
201 | specify a source revision by branch, tag, or commit hash. You can | ||
202 | specify these options when using the ``devtool add`` command: | ||
203 | |||
204 | - To specify a source branch, use the ``--srcbranch`` option: | ||
205 | :: | ||
206 | |||
207 | $ devtool add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson | ||
208 | |||
209 | In the previous example, you are checking out the DISTRO_NAME_NO_CAP | ||
210 | branch. | ||
211 | |||
212 | - To specify a specific tag or commit hash, use the ``--srcrev`` | ||
213 | option: | ||
214 | :: | ||
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 | ||
220 | DISTRO_REL_TAG tag and the commit associated with the | ||
221 | some_commit_hash hash. | ||
222 | |||
223 | .. note:: | ||
224 | |||
225 | If you prefer to use the latest revision every time the recipe is | ||
226 | built, use the options --autorev or -a. | ||
227 | |||
228 | .. _devtool-extracting-the-source-for-an-existing-recipe: | ||
229 | |||
230 | Extracting the Source for an Existing Recipe | ||
231 | ============================================ | ||
232 | |||
233 | Use the ``devtool extract`` command to extract the source for an | ||
234 | existing recipe. When you use this command, you must supply the root | ||
235 | name of the recipe (i.e. no version, paths, or extensions), and you must | ||
236 | supply the directory to which you want the source extracted. | ||
237 | |||
238 | Additional command options let you control the name of a development | ||
239 | branch into which you can checkout the source and whether or not to keep | ||
240 | a temporary directory, which is useful for debugging. | ||
241 | |||
242 | .. _devtool-synchronizing-a-recipes-extracted-source-tree: | ||
243 | |||
244 | Synchronizing a Recipe's Extracted Source Tree | ||
245 | ============================================== | ||
246 | |||
247 | Use the ``devtool sync`` command to synchronize a previously extracted | ||
248 | source tree for an existing recipe. When you use this command, you must | ||
249 | supply the root name of the recipe (i.e. no version, paths, or | ||
250 | extensions), and you must supply the directory to which you want the | ||
251 | source extracted. | ||
252 | |||
253 | Additional command options let you control the name of a development | ||
254 | branch into which you can checkout the source and whether or not to keep | ||
255 | a temporary directory, which is useful for debugging. | ||
256 | |||
257 | .. _devtool-modifying-a-recipe: | ||
258 | |||
259 | Modifying an Existing Recipe | ||
260 | ============================ | ||
261 | |||
262 | Use the ``devtool modify`` command to begin modifying the source of an | ||
263 | existing recipe. This command is very similar to the | ||
264 | ```add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ command | ||
265 | except that it does not physically create the recipe in the workspace | ||
266 | layer because the recipe already exists in an another layer. | ||
267 | |||
268 | The ``devtool modify`` command extracts the source for a recipe, sets it | ||
269 | up as a Git repository if the source had not already been fetched from | ||
270 | Git, checks out a branch for development, and applies any patches from | ||
271 | the recipe as commits on top. You can use the following command to | ||
272 | checkout the source files: | ||
273 | :: | ||
274 | |||
275 | $ devtool modify recipe | ||
276 | |||
277 | Using the above command form, ``devtool`` uses the existing recipe's | ||
278 | :term:`SRC_URI` statement to locate the upstream source, | ||
279 | extracts the source into the default sources location in the workspace. | ||
280 | The default development branch used is "devtool". | ||
281 | |||
282 | .. _devtool-edit-an-existing-recipe: | ||
283 | |||
284 | Edit an Existing Recipe | ||
285 | ======================= | ||
286 | |||
287 | Use the ``devtool edit-recipe`` command to run the default editor, which | ||
288 | is identified using the ``EDITOR`` variable, on the specified recipe. | ||
289 | |||
290 | When you use the ``devtool edit-recipe`` command, you must supply the | ||
291 | root name of the recipe (i.e. no version, paths, or extensions). Also, | ||
292 | the recipe file itself must reside in the workspace as a result of the | ||
293 | ``devtool add`` or ``devtool upgrade`` commands. However, you can | ||
294 | override that requirement by using the "-a" or "--any-recipe" option. | ||
295 | Using either of these options allows you to edit any recipe regardless | ||
296 | of its location. | ||
297 | |||
298 | .. _devtool-updating-a-recipe: | ||
299 | |||
300 | Updating a Recipe | ||
301 | ================= | ||
302 | |||
303 | Use the ``devtool update-recipe`` command to update your recipe with | ||
304 | patches that reflect changes you make to the source files. For example, | ||
305 | if you know you are going to work on some code, you could first use the | ||
306 | ```devtool modify`` <#devtool-modifying-a-recipe>`__ command to extract | ||
307 | the code and set up the workspace. After which, you could modify, | ||
308 | compile, and test the code. | ||
309 | |||
310 | When you are satisfied with the results and you have committed your | ||
311 | changes to the Git repository, you can then run the | ||
312 | ``devtool update-recipe`` to create the patches and update the recipe: | ||
313 | :: | ||
314 | |||
315 | $ devtool update-recipe recipe | ||
316 | |||
317 | If you run the ``devtool update-recipe`` | ||
318 | without committing your changes, the command ignores the changes. | ||
319 | |||
320 | Often, you might want to apply customizations made to your software in | ||
321 | your own layer rather than apply them to the original recipe. If so, you | ||
322 | can use the ``-a`` or ``--append`` option with the | ||
323 | ``devtool update-recipe`` command. These options allow you to specify | ||
324 | the layer into which to write an append file: | ||
325 | :: | ||
326 | |||
327 | $ devtool update-recipe recipe -a base-layer-directory | ||
328 | |||
329 | The ``*.bbappend`` file is created at the | ||
330 | appropriate path within the specified layer directory, which may or may | ||
331 | not be in your ``bblayers.conf`` file. If an append file already exists, | ||
332 | the command updates it appropriately. | ||
333 | |||
334 | .. _devtool-checking-on-the-upgrade-status-of-a-recipe: | ||
335 | |||
336 | Checking on the Upgrade Status of a Recipe | ||
337 | ========================================== | ||
338 | |||
339 | Upstream recipes change over time. Consequently, you might find that you | ||
340 | need to determine if you can upgrade a recipe to a newer version. | ||
341 | |||
342 | To check on the upgrade status of a recipe, use the | ||
343 | ``devtool check-upgrade-status`` command. The command displays a table | ||
344 | of your current recipe versions, the latest upstream versions, the email | ||
345 | address of the recipe's maintainer, and any additional information such | ||
346 | as commit hash strings and reasons you might not be able to upgrade a | ||
347 | particular recipe. | ||
348 | |||
349 | .. note:: | ||
350 | |||
351 | - For the ``oe-core`` layer, recipe maintainers come from the | ||
352 | `maintainers.inc <http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc>`_ | ||
353 | file. | ||
354 | |||
355 | - If the recipe is using the :ref:`bitbake:git-fetcher` | ||
356 | rather than a | ||
357 | tarball, the commit hash points to the commit that matches the | ||
358 | recipe's latest version tag. | ||
359 | |||
360 | As with all ``devtool`` commands, you can get help on the individual | ||
361 | command: | ||
362 | :: | ||
363 | |||
364 | $ devtool check-upgrade-status -h | ||
365 | NOTE: Starting bitbake server... | ||
366 | usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]] | ||
367 | |||
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 | ||
376 | |||
377 | Unless you provide a specific recipe name on the command line, the | ||
378 | command checks all recipes in all configured layers. | ||
379 | |||
380 | Following is a partial example table that reports on all the recipes. | ||
381 | Notice the reported reason for not upgrading the ``base-passwd`` recipe. | ||
382 | In this example, while a new version is available upstream, you do not | ||
383 | want to use it because the dependency on ``cdebconf`` is not easily | ||
384 | satisfied. | ||
385 | |||
386 | .. note:: | ||
387 | |||
388 | When a reason for not upgrading displays, the reason is usually | ||
389 | written into the recipe using the RECIPE_NO_UPDATE_REASON | ||
390 | variable. See the base-passwd.bb recipe for an example. | ||
391 | |||
392 | :: | ||
393 | |||
394 | $ devtool check-upgrade-status ... | ||
395 | NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com> | ||
396 | NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff | ||
397 | NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff . . . | ||
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 | ||
399 | NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> | ||
400 | NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com> | ||
401 | |||
402 | .. _devtool-upgrading-a-recipe: | ||
403 | |||
404 | Upgrading a Recipe | ||
405 | ================== | ||
406 | |||
407 | As software matures, upstream recipes are upgraded to newer versions. As | ||
408 | a developer, you need to keep your local recipes up-to-date with the | ||
409 | upstream version releases. Several methods exist by which you can | ||
410 | upgrade recipes. You can read about them in the ":ref:`gs-upgrading-recipes`" | ||
411 | section of the Yocto Project Development Tasks Manual. This section | ||
412 | overviews the ``devtool upgrade`` command. | ||
413 | |||
414 | Before you upgrade a recipe, you can check on its upgrade status. See | ||
415 | the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section | ||
416 | for more information. | ||
417 | |||
418 | The ``devtool upgrade`` command upgrades an existing recipe to a more | ||
419 | recent version of the recipe upstream. The command puts the upgraded | ||
420 | recipe file along with any associated files into a "workspace" and, if | ||
421 | necessary, extracts the source tree to a specified location. During the | ||
422 | upgrade, patches associated with the recipe are rebased or added as | ||
423 | needed. | ||
424 | |||
425 | When you use the ``devtool upgrade`` command, you must supply the root | ||
426 | name of the recipe (i.e. no version, paths, or extensions), and you must | ||
427 | supply the directory to which you want the source extracted. Additional | ||
428 | command options let you control things such as the version number to | ||
429 | which you want to upgrade (i.e. the :term:`PV`), the source | ||
430 | revision to which you want to upgrade (i.e. the | ||
431 | :term:`SRCREV`), whether or not to apply patches, and so | ||
432 | forth. | ||
433 | |||
434 | You can read more on the ``devtool upgrade`` workflow in the | ||
435 | ":ref:`sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software`" | ||
436 | section in the Yocto Project Application Development and the Extensible | ||
437 | Software Development Kit (eSDK) manual. You can also see an example of | ||
438 | how to use ``devtool upgrade`` in the ":ref:`gs-using-devtool-upgrade`" | ||
439 | section in the Yocto Project Development Tasks Manual. | ||
440 | |||
441 | .. _devtool-resetting-a-recipe: | ||
442 | |||
443 | Resetting a Recipe | ||
444 | ================== | ||
445 | |||
446 | Use the ``devtool reset`` command to remove a recipe and its | ||
447 | configuration (e.g. the corresponding ``.bbappend`` file) from the | ||
448 | workspace layer. Realize that this command deletes the recipe and the | ||
449 | append file. The command does not physically move them for you. | ||
450 | Consequently, you must be sure to physically relocate your updated | ||
451 | recipe and the append file outside of the workspace layer before running | ||
452 | the ``devtool reset`` command. | ||
453 | |||
454 | If the ``devtool reset`` command detects that the recipe or the append | ||
455 | files have been modified, the command preserves the modified files in a | ||
456 | separate "attic" subdirectory under the workspace layer. | ||
457 | |||
458 | Here is an example that resets the workspace directory that contains the | ||
459 | ``mtr`` recipe: | ||
460 | :: | ||
461 | |||
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 | $ | ||
466 | |||
467 | .. _devtool-building-your-recipe: | ||
468 | |||
469 | Building Your Recipe | ||
470 | ==================== | ||
471 | |||
472 | Use the ``devtool build`` command to build your recipe. The | ||
473 | ``devtool build`` command is equivalent to the | ||
474 | ``bitbake -c populate_sysroot`` command. | ||
475 | |||
476 | When you use the ``devtool build`` command, you must supply the root | ||
477 | name of the recipe (i.e. do not provide versions, paths, or extensions). | ||
478 | You can use either the "-s" or the "--disable-parallel-make" options to | ||
479 | disable parallel makes during the build. Here is an example: | ||
480 | :: | ||
481 | |||
482 | $ devtool build recipe | ||
483 | |||
484 | .. _devtool-building-your-image: | ||
485 | |||
486 | Building Your Image | ||
487 | =================== | ||
488 | |||
489 | Use the ``devtool build-image`` command to build an image, extending it | ||
490 | to include packages from recipes in the workspace. Using this command is | ||
491 | useful when you want an image that ready for immediate deployment onto a | ||
492 | device for testing. For proper integration into a final image, you need | ||
493 | to edit your custom image recipe appropriately. | ||
494 | |||
495 | When you use the ``devtool build-image`` command, you must supply the | ||
496 | name of the image. This command has no command line options: | ||
497 | :: | ||
498 | |||
499 | $ devtool build-image image | ||
500 | |||
501 | .. _devtool-deploying-your-software-on-the-target-machine: | ||
502 | |||
503 | Deploying Your Software on the Target Machine | ||
504 | ============================================= | ||
505 | |||
506 | Use the ``devtool deploy-target`` command to deploy the recipe's build | ||
507 | output to the live target machine: | ||
508 | :: | ||
509 | |||
510 | $ devtool deploy-target recipe target | ||
511 | |||
512 | The target is the address of the target machine, which must be running | ||
513 | an SSH server (i.e. ``user@hostname[:destdir]``). | ||
514 | |||
515 | This command deploys all files installed during the | ||
516 | :ref:`ref-tasks-install` task. Furthermore, you do not | ||
517 | need to have package management enabled within the target machine. If | ||
518 | you do, the package manager is bypassed. | ||
519 | |||
520 | .. note:: | ||
521 | |||
522 | The ``deploy-target`` functionality is for development only. You | ||
523 | should never use it to update an image that will be used in | ||
524 | production. | ||
525 | |||
526 | Some conditions exist that could prevent a deployed application from | ||
527 | behaving as expected. When both of the following conditions exist, your | ||
528 | application has the potential to not behave correctly when run on the | ||
529 | target: | ||
530 | |||
531 | - You are deploying a new application to the target and the recipe you | ||
532 | used to build the application had correctly defined runtime | ||
533 | dependencies. | ||
534 | |||
535 | - The target does not physically have the packages on which the | ||
536 | application depends installed. | ||
537 | |||
538 | If both of these conditions exist, your application will not behave as | ||
539 | expected. The reason for this misbehavior is because the | ||
540 | ``devtool deploy-target`` command does not deploy the packages (e.g. | ||
541 | libraries) on which your new application depends. The assumption is that | ||
542 | the packages are already on the target. Consequently, when a runtime | ||
543 | call is made in the application for a dependent function (e.g. a library | ||
544 | call), the function cannot be found. | ||
545 | |||
546 | To be sure you have all the dependencies local to the target, you need | ||
547 | to be sure that the packages are pre-deployed (installed) on the target | ||
548 | before attempting to run your application. | ||
549 | |||
550 | .. _devtool-removing-your-software-from-the-target-machine: | ||
551 | |||
552 | Removing Your Software from the Target Machine | ||
553 | ============================================== | ||
554 | |||
555 | Use the ``devtool undeploy-target`` command to remove deployed build | ||
556 | output from the target machine. For the ``devtool undeploy-target`` | ||
557 | command to work, you must have previously used the | ||
558 | ":ref:`devtool deploy-target <ref-manual/ref-devtool-reference:deploying your software on the target machine>`" | ||
559 | command. | ||
560 | :: | ||
561 | |||
562 | $ devtool undeploy-target recipe target | ||
563 | |||
564 | The target is the | ||
565 | address of the target machine, which must be running an SSH server (i.e. | ||
566 | ``user@hostname``). | ||
567 | |||
568 | .. _devtool-creating-the-workspace: | ||
569 | |||
570 | Creating the Workspace Layer in an Alternative Location | ||
571 | ======================================================= | ||
572 | |||
573 | Use the ``devtool create-workspace`` command to create a new workspace | ||
574 | layer in your :term:`Build Directory`. When you create a | ||
575 | new workspace layer, it is populated with the ``README`` file and the | ||
576 | ``conf`` directory only. | ||
577 | |||
578 | The following example creates a new workspace layer in your current | ||
579 | working and by default names the workspace layer "workspace": | ||
580 | :: | ||
581 | |||
582 | $ devtool create-workspace | ||
583 | |||
584 | You can create a workspace layer anywhere by supplying a pathname with | ||
585 | the command. The following command creates a new workspace layer named | ||
586 | "new-workspace": | ||
587 | :: | ||
588 | |||
589 | $ devtool create-workspace /home/scottrif/new-workspace | ||
590 | |||
591 | .. _devtool-get-the-status-of-the-recipes-in-your-workspace: | ||
592 | |||
593 | Get the Status of the Recipes in Your Workspace | ||
594 | =============================================== | ||
595 | |||
596 | Use the ``devtool status`` command to list the recipes currently in your | ||
597 | workspace. Information includes the paths to their respective external | ||
598 | source trees. | ||
599 | |||
600 | The ``devtool status`` command has no command-line options: | ||
601 | :: | ||
602 | |||
603 | $ devtool status | ||
604 | |||
605 | Following is sample output after using | ||
606 | :ref:`devtool add <ref-manual/ref-devtool-reference:adding a new recipe to the workspace layer>` | ||
607 | to 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 | $ | ||
613 | |||
614 | .. _devtool-search-for-available-target-recipes: | ||
615 | |||
616 | Search for Available Target Recipes | ||
617 | =================================== | ||
618 | |||
619 | Use the ``devtool search`` command to search for available target | ||
620 | recipes. The command matches the recipe name, package name, description, | ||
621 | and installed files. The command displays the recipe name as a result of | ||
622 | a match. | ||
623 | |||
624 | When you use the ``devtool search`` command, you must supply a keyword. | ||
625 | The command uses the keyword when searching for a match. | ||
diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml index 11f7399c5a..6c3ccc3034 100644 --- a/documentation/ref-manual/ref-devtool-reference.xml +++ b/documentation/ref-manual/ref-devtool-reference.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-devtool-reference'> | 6 | <chapter id='ref-devtool-reference'> |
6 | <title><filename>devtool</filename> Quick Reference</title> | 7 | <title><filename>devtool</filename> Quick Reference</title> |
diff --git a/documentation/ref-manual/ref-features.rst b/documentation/ref-manual/ref-features.rst new file mode 100644 index 0000000000..ae5a0e3b24 --- /dev/null +++ b/documentation/ref-manual/ref-features.rst | |||
@@ -0,0 +1,353 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******** | ||
4 | Features | ||
5 | ******** | ||
6 | |||
7 | This chapter provides a reference of shipped machine and distro features | ||
8 | you can include as part of your image, a reference on image features you | ||
9 | can select, and a reference on feature backfilling. | ||
10 | |||
11 | Features provide a mechanism for working out which packages should be | ||
12 | included in the generated images. Distributions can select which | ||
13 | features they want to support through the ``DISTRO_FEATURES`` variable, | ||
14 | which is set or appended to in a distribution's configuration file such | ||
15 | as ``poky.conf``, ``poky-tiny.conf``, ``poky-lsb.conf`` and so forth. | ||
16 | Machine features are set in the ``MACHINE_FEATURES`` variable, which is | ||
17 | set in the machine configuration file and specifies the hardware | ||
18 | features for a given machine. | ||
19 | |||
20 | These two variables combine to work out which kernel modules, utilities, | ||
21 | and other packages to include. A given distribution can support a | ||
22 | selected subset of features so some machine features might not be | ||
23 | included if the distribution itself does not support them. | ||
24 | |||
25 | One method you can use to determine which recipes are checking to see if | ||
26 | a particular feature is contained or not is to ``grep`` through the | ||
27 | :term:`Metadata` for the feature. Here is an example that | ||
28 | discovers the recipes whose build is potentially changed based on a | ||
29 | given feature: | ||
30 | :: | ||
31 | |||
32 | $ cd poky | ||
33 | $ git grep 'contains.*MACHINE_FEATURES.*feature' | ||
34 | |||
35 | .. _ref-features-machine: | ||
36 | |||
37 | Machine Features | ||
38 | ================ | ||
39 | |||
40 | The items below are features you can use with | ||
41 | :term:`MACHINE_FEATURES`. Features do not have a | ||
42 | one-to-one correspondence to packages, and they can go beyond simply | ||
43 | controlling the installation of a package or packages. Sometimes a | ||
44 | feature can influence how certain recipes are built. For example, a | ||
45 | feature might determine whether a particular configure option is | ||
46 | specified within the :ref:`ref-tasks-configure` task | ||
47 | for a particular recipe. | ||
48 | |||
49 | This feature list only represents features as shipped with the Yocto | ||
50 | Project metadata: | ||
51 | |||
52 | - *acpi:* Hardware has ACPI (x86/x86_64 only) | ||
53 | |||
54 | - *alsa:* Hardware has ALSA audio drivers | ||
55 | |||
56 | - *apm:* Hardware uses APM (or APM emulation) | ||
57 | |||
58 | - *bluetooth:* Hardware has integrated BT | ||
59 | |||
60 | - *efi:* Support for booting through EFI | ||
61 | |||
62 | - *ext2:* Hardware HDD or Microdrive | ||
63 | |||
64 | - *keyboard:* Hardware has a keyboard | ||
65 | |||
66 | - *pcbios:* Support for booting through BIOS | ||
67 | |||
68 | - *pci:* Hardware has a PCI bus | ||
69 | |||
70 | - *pcmcia:* Hardware has PCMCIA or CompactFlash sockets | ||
71 | |||
72 | - *phone:* Mobile phone (voice) support | ||
73 | |||
74 | - *qvga:* Machine has a QVGA (320x240) display | ||
75 | |||
76 | - *rtc:* Machine has a Real-Time Clock | ||
77 | |||
78 | - *screen:* Hardware has a screen | ||
79 | |||
80 | - *serial:* Hardware has serial support (usually RS232) | ||
81 | |||
82 | - *touchscreen:* Hardware has a touchscreen | ||
83 | |||
84 | - *usbgadget:* Hardware is USB gadget device capable | ||
85 | |||
86 | - *usbhost:* Hardware is USB Host capable | ||
87 | |||
88 | - *vfat:* FAT file system support | ||
89 | |||
90 | - *wifi:* Hardware has integrated WiFi | ||
91 | |||
92 | .. _ref-features-distro: | ||
93 | |||
94 | Distro Features | ||
95 | =============== | ||
96 | |||
97 | The items below are features you can use with | ||
98 | :term:`DISTRO_FEATURES` to enable features across | ||
99 | your distribution. Features do not have a one-to-one correspondence to | ||
100 | packages, and they can go beyond simply controlling the installation of | ||
101 | a package or packages. In most cases, the presence or absence of a | ||
102 | feature translates to the appropriate option supplied to the configure | ||
103 | script during the :ref:`ref-tasks-configure` task for | ||
104 | the recipes that optionally support the feature. | ||
105 | |||
106 | Some distro features are also machine features. These select features | ||
107 | make sense to be controlled both at the machine and distribution | ||
108 | configuration level. See the | ||
109 | :term:`COMBINED_FEATURES` variable for more | ||
110 | information. | ||
111 | |||
112 | This list only represents features as shipped with the Yocto Project | ||
113 | metadata: | ||
114 | |||
115 | - *alsa:* Include ALSA support (OSS compatibility kernel modules | ||
116 | installed if available). | ||
117 | |||
118 | - *api-documentation:* Enables generation of API documentation during | ||
119 | recipe builds. The resulting documentation is added to SDK tarballs | ||
120 | when the ``bitbake -c populate_sdk`` command is used. See the | ||
121 | ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding api documentation to the standard sdk`" | ||
122 | section in the Yocto Project Application Development and the | ||
123 | Extensible Software Development Kit (eSDK) manual. | ||
124 | |||
125 | - *bluetooth:* Include bluetooth support (integrated BT only). | ||
126 | |||
127 | - *cramfs:* Include CramFS support. | ||
128 | |||
129 | - *directfb:* Include DirectFB support. | ||
130 | |||
131 | - *ext2:* Include tools for supporting for devices with internal | ||
132 | HDD/Microdrive for storing files (instead of Flash only devices). | ||
133 | |||
134 | - *ipsec:* Include IPSec support. | ||
135 | |||
136 | - *ipv6:* Include IPv6 support. | ||
137 | |||
138 | - *keyboard:* Include keyboard support (e.g. keymaps will be loaded | ||
139 | during boot). | ||
140 | |||
141 | - *ldconfig:* Include support for ldconfig and ``ld.so.conf`` on the | ||
142 | target. | ||
143 | |||
144 | - *nfs:* Include NFS client support (for mounting NFS exports on | ||
145 | device). | ||
146 | |||
147 | - *opengl:* Include the Open Graphics Library, which is a | ||
148 | cross-language, multi-platform application programming interface used | ||
149 | for rendering two and three-dimensional graphics. | ||
150 | |||
151 | - *pci:* Include PCI bus support. | ||
152 | |||
153 | - *pcmcia:* Include PCMCIA/CompactFlash support. | ||
154 | |||
155 | - *ppp:* Include PPP dialup support. | ||
156 | |||
157 | - *ptest:* Enables building the package tests where supported by | ||
158 | individual recipes. For more information on package tests, see the | ||
159 | ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" section | ||
160 | in the Yocto Project Development Tasks Manual. | ||
161 | |||
162 | - *smbfs:* Include SMB networks client support (for mounting | ||
163 | Samba/Microsoft Windows shares on device). | ||
164 | |||
165 | - *systemd:* Include support for this ``init`` manager, which is a full | ||
166 | replacement of for ``init`` with parallel starting of services, | ||
167 | reduced shell overhead, and other features. This ``init`` manager is | ||
168 | used by many distributions. | ||
169 | |||
170 | - *usbgadget:* Include USB Gadget Device support (for USB | ||
171 | networking/serial/storage). | ||
172 | |||
173 | - *usbhost:* Include USB Host support (allows to connect external | ||
174 | keyboard, mouse, storage, network etc). | ||
175 | |||
176 | - *usrmerge:* Merges the ``/bin``, ``/sbin``, ``/lib``, and ``/lib64`` | ||
177 | directories into their respective counterparts in the ``/usr`` | ||
178 | directory to provide better package and application compatibility. | ||
179 | |||
180 | - *wayland:* Include the Wayland display server protocol and the | ||
181 | library that supports it. | ||
182 | |||
183 | - *wifi:* Include WiFi support (integrated only). | ||
184 | |||
185 | - *x11:* Include the X server and libraries. | ||
186 | |||
187 | .. _ref-features-image: | ||
188 | |||
189 | Image Features | ||
190 | ============== | ||
191 | |||
192 | The contents of images generated by the OpenEmbedded build system can be | ||
193 | controlled by the :term:`IMAGE_FEATURES` and | ||
194 | :term:`EXTRA_IMAGE_FEATURES` variables that | ||
195 | you typically configure in your image recipes. Through these variables, | ||
196 | you can add several different predefined packages such as development | ||
197 | utilities or packages with debug information needed to investigate | ||
198 | application problems or profile applications. | ||
199 | |||
200 | The following image features are available for all images: | ||
201 | |||
202 | - *allow-empty-password:* Allows Dropbear and OpenSSH to accept root | ||
203 | logins and logins from accounts having an empty password string. | ||
204 | |||
205 | - *dbg-pkgs:* Installs debug symbol packages for all packages installed | ||
206 | in a given image. | ||
207 | |||
208 | - *debug-tweaks:* Makes an image suitable for development (e.g. allows | ||
209 | root logins without passwords and enables post-installation logging). | ||
210 | See the 'allow-empty-password', 'empty-root-password', and | ||
211 | 'post-install-logging' features in this list for additional | ||
212 | information. | ||
213 | |||
214 | - *dev-pkgs:* Installs development packages (headers and extra library | ||
215 | links) for all packages installed in a given image. | ||
216 | |||
217 | - *doc-pkgs:* Installs documentation packages for all packages | ||
218 | installed in a given image. | ||
219 | |||
220 | - *empty-root-password:* Sets the root password to an empty string, | ||
221 | which allows logins with a blank password. | ||
222 | |||
223 | - *package-management:* Installs package management tools and preserves | ||
224 | the package manager database. | ||
225 | |||
226 | - *post-install-logging:* Enables logging postinstall script runs to | ||
227 | the ``/var/log/postinstall.log`` file on first boot of the image on | ||
228 | the target system. | ||
229 | |||
230 | .. note:: | ||
231 | |||
232 | To make the | ||
233 | /var/log | ||
234 | directory on the target persistent, use the | ||
235 | VOLATILE_LOG_DIR | ||
236 | variable by setting it to "no". | ||
237 | |||
238 | - *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes. | ||
239 | |||
240 | - *read-only-rootfs:* Creates an image whose root filesystem is | ||
241 | read-only. See the | ||
242 | ":ref:`dev-manual/dev-manual-common-tasks:creating a read-only root filesystem`" | ||
243 | section in the Yocto Project Development Tasks Manual for more | ||
244 | information. | ||
245 | |||
246 | - *splash:* Enables showing a splash screen during boot. By default, | ||
247 | this screen is provided by ``psplash``, which does allow | ||
248 | customization. If you prefer to use an alternative splash screen | ||
249 | package, you can do so by setting the ``SPLASH`` variable to a | ||
250 | different package name (or names) within the image recipe or at the | ||
251 | distro configuration level. | ||
252 | |||
253 | - *staticdev-pkgs:* Installs static development packages, which are | ||
254 | static libraries (i.e. ``*.a`` files), for all packages installed in | ||
255 | a given image. | ||
256 | |||
257 | Some image features are available only when you inherit the | ||
258 | :ref:`core-image <ref-classes-core-image>` class. The current list of | ||
259 | these valid features is as follows: | ||
260 | |||
261 | - *hwcodecs:* Installs hardware acceleration codecs. | ||
262 | |||
263 | - *nfs-server:* Installs an NFS server. | ||
264 | |||
265 | - *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and | ||
266 | ``LTTng``. For general information on user-space tools, see the | ||
267 | :doc:`../sdk-manual/sdk-manual` manual. | ||
268 | |||
269 | - *ssh-server-dropbear:* Installs the Dropbear minimal SSH server. | ||
270 | |||
271 | - *ssh-server-openssh:* Installs the OpenSSH SSH server, which is more | ||
272 | full-featured than Dropbear. Note that if both the OpenSSH SSH server | ||
273 | and the Dropbear minimal SSH server are present in | ||
274 | ``IMAGE_FEATURES``, then OpenSSH will take precedence and Dropbear | ||
275 | will not be installed. | ||
276 | |||
277 | - *tools-debug:* Installs debugging tools such as ``strace`` and | ||
278 | ``gdb``. For information on GDB, see the | ||
279 | ":ref:`platdev-gdb-remotedebug`" section | ||
280 | in the Yocto Project Development Tasks Manual. For information on | ||
281 | tracing and profiling, see the :doc:`../profile-manual/profile-manual`. | ||
282 | |||
283 | - *tools-sdk:* Installs a full SDK that runs on the device. | ||
284 | |||
285 | - *tools-testapps:* Installs device testing tools (e.g. touchscreen | ||
286 | debugging). | ||
287 | |||
288 | - *x11:* Installs the X server. | ||
289 | |||
290 | - *x11-base:* Installs the X server with a minimal environment. | ||
291 | |||
292 | - *x11-sato:* Installs the OpenedHand Sato environment. | ||
293 | |||
294 | .. _ref-features-backfill: | ||
295 | |||
296 | Feature Backfilling | ||
297 | =================== | ||
298 | |||
299 | Sometimes it is necessary in the OpenEmbedded build system to extend | ||
300 | :term:`MACHINE_FEATURES` or | ||
301 | :term:`DISTRO_FEATURES` to control functionality | ||
302 | that was previously enabled and not able to be disabled. For these | ||
303 | cases, we need to add an additional feature item to appear in one of | ||
304 | these variables, but we do not want to force developers who have | ||
305 | existing values of the variables in their configuration to add the new | ||
306 | feature in order to retain the same overall level of functionality. | ||
307 | Thus, the OpenEmbedded build system has a mechanism to automatically | ||
308 | "backfill" these added features into existing distro or machine | ||
309 | configurations. You can see the list of features for which this is done | ||
310 | by finding the | ||
311 | :term:`DISTRO_FEATURES_BACKFILL` and | ||
312 | :term:`MACHINE_FEATURES_BACKFILL` | ||
313 | variables in the ``meta/conf/bitbake.conf`` file. | ||
314 | |||
315 | Because such features are backfilled by default into all configurations | ||
316 | as described in the previous paragraph, developers who wish to disable | ||
317 | the new features need to be able to selectively prevent the backfilling | ||
318 | from occurring. They can do this by adding the undesired feature or | ||
319 | features to the | ||
320 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | ||
321 | or | ||
322 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` | ||
323 | variables for distro features and machine features respectively. | ||
324 | |||
325 | Here are two examples to help illustrate feature backfilling: | ||
326 | |||
327 | - *The "pulseaudio" distro feature option*: Previously, PulseAudio | ||
328 | support was enabled within the Qt and GStreamer frameworks. Because | ||
329 | of this, the feature is backfilled and thus enabled for all distros | ||
330 | through the ``DISTRO_FEATURES_BACKFILL`` variable in the | ||
331 | ``meta/conf/bitbake.conf`` file. However, your distro needs to | ||
332 | disable the feature. You can disable the feature without affecting | ||
333 | other existing distro configurations that need PulseAudio support by | ||
334 | adding "pulseaudio" to ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` in | ||
335 | your distro's ``.conf`` file. Adding the feature to this variable | ||
336 | when it also exists in the ``DISTRO_FEATURES_BACKFILL`` variable | ||
337 | prevents the build system from adding the feature to your | ||
338 | configuration's ``DISTRO_FEATURES``, effectively disabling the | ||
339 | feature for that particular distro. | ||
340 | |||
341 | - *The "rtc" machine feature option*: Previously, real time clock (RTC) | ||
342 | support was enabled for all target devices. Because of this, the | ||
343 | feature is backfilled and thus enabled for all machines through the | ||
344 | ``MACHINE_FEATURES_BACKFILL`` variable in the | ||
345 | ``meta/conf/bitbake.conf`` file. However, your target device does not | ||
346 | have this capability. You can disable RTC support for your device | ||
347 | without affecting other machines that need RTC support by adding the | ||
348 | feature to your machine's ``MACHINE_FEATURES_BACKFILL_CONSIDERED`` | ||
349 | list in the machine's ``.conf`` file. Adding the feature to this | ||
350 | variable when it also exists in the ``MACHINE_FEATURES_BACKFILL`` | ||
351 | variable prevents the build system from adding the feature to your | ||
352 | configuration's ``MACHINE_FEATURES``, effectively disabling RTC | ||
353 | support for that particular machine. | ||
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml index 294b297c20..8cab5ec3a8 100644 --- a/documentation/ref-manual/ref-features.xml +++ b/documentation/ref-manual/ref-features.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-features'> | 6 | <chapter id='ref-features'> |
6 | <title>Features</title> | 7 | <title>Features</title> |
diff --git a/documentation/ref-manual/ref-images.rst b/documentation/ref-manual/ref-images.rst new file mode 100644 index 0000000000..c88d4d75ca --- /dev/null +++ b/documentation/ref-manual/ref-images.rst | |||
@@ -0,0 +1,139 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ****** | ||
4 | Images | ||
5 | ****** | ||
6 | |||
7 | The OpenEmbedded build system provides several example images to satisfy | ||
8 | different needs. When you issue the ``bitbake`` command you provide a | ||
9 | "top-level" recipe that essentially begins the build for the type of | ||
10 | image you want. | ||
11 | |||
12 | .. note:: | ||
13 | |||
14 | Building an image without GNU General Public License Version 3 | ||
15 | (GPLv3), GNU Lesser General Public License Version 3 (LGPLv3), and | ||
16 | the GNU Affero General Public License Version 3 (AGPL-3.0) components | ||
17 | is only supported for minimal and base images. Furthermore, if you | ||
18 | are going to build an image using non-GPLv3 and similarly licensed | ||
19 | components, you must make the following changes in the | ||
20 | local.conf | ||
21 | file before using the BitBake command to build the minimal or base | ||
22 | image: | ||
23 | :: | ||
24 | |||
25 | 1. Comment out the EXTRA_IMAGE_FEATURES line | ||
26 | 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" | ||
27 | |||
28 | |||
29 | From within the ``poky`` Git repository, you can use the following | ||
30 | command to display the list of directories within the :term:`Source Directory` | ||
31 | that contain image recipe files: :: | ||
32 | |||
33 | $ ls meta*/recipes*/images/*.bb | ||
34 | |||
35 | Following is a list of supported recipes: | ||
36 | |||
37 | - ``build-appliance-image``: An example virtual machine that contains | ||
38 | all the pieces required to run builds using the build system as well | ||
39 | as the build system itself. You can boot and run the image using | ||
40 | either the `VMware | ||
41 | Player <http://www.vmware.com/products/player/overview.html>`__ or | ||
42 | `VMware | ||
43 | Workstation <http://www.vmware.com/products/workstation/overview.html>`__. | ||
44 | For more information on this image, see the :yocto_home:`Build | ||
45 | Appliance </software-item/build-appliance>` page | ||
46 | on the Yocto Project website. | ||
47 | |||
48 | - ``core-image-base``: A console-only image that fully supports the | ||
49 | target device hardware. | ||
50 | |||
51 | - ``core-image-clutter``: An image with support for the Open GL-based | ||
52 | toolkit Clutter, which enables development of rich and animated | ||
53 | graphical user interfaces. | ||
54 | |||
55 | - ``core-image-full-cmdline``: A console-only image with more | ||
56 | full-featured Linux system functionality installed. | ||
57 | |||
58 | - ``core-image-lsb``: An image that conforms to the Linux Standard Base | ||
59 | (LSB) specification. This image requires a distribution configuration | ||
60 | that enables LSB compliance (e.g. ``poky-lsb``). If you build | ||
61 | ``core-image-lsb`` without that configuration, the image will not be | ||
62 | LSB-compliant. | ||
63 | |||
64 | - ``core-image-lsb-dev``: A ``core-image-lsb`` image that is suitable | ||
65 | for development work using the host. The image includes headers and | ||
66 | libraries you can use in a host development environment. This image | ||
67 | requires a distribution configuration that enables LSB compliance | ||
68 | (e.g. ``poky-lsb``). If you build ``core-image-lsb-dev`` without that | ||
69 | configuration, the image will not be LSB-compliant. | ||
70 | |||
71 | - ``core-image-lsb-sdk``: A ``core-image-lsb`` that includes everything | ||
72 | in the cross-toolchain but also includes development headers and | ||
73 | libraries to form a complete standalone SDK. This image requires a | ||
74 | distribution configuration that enables LSB compliance (e.g. | ||
75 | ``poky-lsb``). If you build ``core-image-lsb-sdk`` without that | ||
76 | configuration, the image will not be LSB-compliant. This image is | ||
77 | suitable for development using the target. | ||
78 | |||
79 | - ``core-image-minimal``: A small image just capable of allowing a | ||
80 | device to boot. | ||
81 | |||
82 | - ``core-image-minimal-dev``: A ``core-image-minimal`` image suitable | ||
83 | for development work using the host. The image includes headers and | ||
84 | libraries you can use in a host development environment. | ||
85 | |||
86 | - ``core-image-minimal-initramfs``: A ``core-image-minimal`` image that | ||
87 | has the Minimal RAM-based Initial Root Filesystem (initramfs) as part | ||
88 | of the kernel, which allows the system to find the first "init" | ||
89 | program more efficiently. See the | ||
90 | :term:`PACKAGE_INSTALL` variable for | ||
91 | additional information helpful when working with initramfs images. | ||
92 | |||
93 | - ``core-image-minimal-mtdutils``: A ``core-image-minimal`` image that | ||
94 | has support for the Minimal MTD Utilities, which let the user | ||
95 | interact with the MTD subsystem in the kernel to perform operations | ||
96 | on flash devices. | ||
97 | |||
98 | - ``core-image-rt``: A ``core-image-minimal`` image plus a real-time | ||
99 | test suite and tools appropriate for real-time use. | ||
100 | |||
101 | - ``core-image-rt-sdk``: A ``core-image-rt`` image that includes | ||
102 | everything in the cross-toolchain. The image also includes | ||
103 | development headers and libraries to form a complete stand-alone SDK | ||
104 | and is suitable for development using the target. | ||
105 | |||
106 | - ``core-image-sato``: An image with Sato support, a mobile environment | ||
107 | and visual style that works well with mobile devices. The image | ||
108 | supports X11 with a Sato theme and applications such as a terminal, | ||
109 | editor, file manager, media player, and so forth. | ||
110 | |||
111 | - ``core-image-sato-dev``: A ``core-image-sato`` image suitable for | ||
112 | development using the host. The image includes libraries needed to | ||
113 | build applications on the device itself, testing and profiling tools, | ||
114 | and debug symbols. This image was formerly ``core-image-sdk``. | ||
115 | |||
116 | - ``core-image-sato-sdk``: A ``core-image-sato`` image that includes | ||
117 | everything in the cross-toolchain. The image also includes | ||
118 | development headers and libraries to form a complete standalone SDK | ||
119 | and is suitable for development using the target. | ||
120 | |||
121 | - ``core-image-testmaster``: A "master" image designed to be used for | ||
122 | automated runtime testing. Provides a "known good" image that is | ||
123 | deployed to a separate partition so that you can boot into it and use | ||
124 | it to deploy a second image to be tested. You can find more | ||
125 | information about runtime testing in the | ||
126 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
127 | section in the Yocto Project Development Tasks Manual. | ||
128 | |||
129 | - ``core-image-testmaster-initramfs``: A RAM-based Initial Root | ||
130 | Filesystem (initramfs) image tailored for use with the | ||
131 | ``core-image-testmaster`` image. | ||
132 | |||
133 | - ``core-image-weston``: A very basic Wayland image with a terminal. | ||
134 | This image provides the Wayland protocol libraries and the reference | ||
135 | Weston compositor. For more information, see the | ||
136 | ":ref:`dev-manual/dev-manual-common-tasks:using wayland and weston`" | ||
137 | section in the Yocto Project Development Tasks Manual. | ||
138 | |||
139 | - ``core-image-x11``: A very basic X11 image with a terminal. | ||
diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml index 1f96186c6e..6f10a6fd2a 100644 --- a/documentation/ref-manual/ref-images.xml +++ b/documentation/ref-manual/ref-images.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-images'> | 6 | <chapter id='ref-images'> |
6 | <title>Images</title> | 7 | <title>Images</title> |
@@ -8,7 +9,7 @@ | |||
8 | <para> | 9 | <para> |
9 | The OpenEmbedded build system provides several example | 10 | The OpenEmbedded build system provides several example |
10 | images to satisfy different needs. | 11 | images to satisfy different needs. |
11 | When you issue the <filename>bitbake</filename> command you provide a “top-level” recipe | 12 | When you issue the <filename>bitbake</filename> command you provide a "top-level" recipe |
12 | that essentially begins the build for the type of image you want. | 13 | that essentially begins the build for the type of image you want. |
13 | </para> | 14 | </para> |
14 | 15 | ||
@@ -99,7 +100,7 @@ | |||
99 | <listitem><para id='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename>: | 100 | <listitem><para id='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename>: |
100 | A <filename>core-image-minimal</filename> image that has the Minimal RAM-based | 101 | A <filename>core-image-minimal</filename> image that has the Minimal RAM-based |
101 | Initial Root Filesystem (initramfs) as part of the kernel, | 102 | Initial Root Filesystem (initramfs) as part of the kernel, |
102 | which allows the system to find the first “init” program more efficiently. | 103 | which allows the system to find the first "init" program more efficiently. |
103 | See the | 104 | See the |
104 | <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link> | 105 | <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link> |
105 | variable for additional information helpful when working with | 106 | variable for additional information helpful when working with |
diff --git a/documentation/ref-manual/ref-kickstart.rst b/documentation/ref-manual/ref-kickstart.rst new file mode 100644 index 0000000000..45222de05b --- /dev/null +++ b/documentation/ref-manual/ref-kickstart.rst | |||
@@ -0,0 +1,212 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******************************************* | ||
4 | OpenEmbedded Kickstart (``.wks``) Reference | ||
5 | ******************************************* | ||
6 | |||
7 | .. _openembedded-kickstart-wks-reference: | ||
8 | |||
9 | Introduction | ||
10 | ============ | ||
11 | |||
12 | The current Wic implementation supports only the basic kickstart | ||
13 | partitioning commands: ``partition`` (or ``part`` for short) and | ||
14 | ``bootloader``. | ||
15 | |||
16 | .. note:: | ||
17 | |||
18 | Future updates will implement more commands and options. If you use | ||
19 | anything that is not specifically supported, results can be | ||
20 | unpredictable. | ||
21 | |||
22 | This chapter provides a reference on the available kickstart commands. | ||
23 | The information lists the commands, their syntax, and meanings. | ||
24 | Kickstart commands are based on the Fedora kickstart versions but with | ||
25 | modifications to reflect Wic capabilities. You can see the original | ||
26 | documentation for those commands at the following link: | ||
27 | http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html | ||
28 | |||
29 | Command: part or partition | ||
30 | ========================== | ||
31 | |||
32 | Either of these commands creates a partition on the system and uses the | ||
33 | following syntax: | ||
34 | :: | ||
35 | |||
36 | part [mntpoint] | ||
37 | partition [mntpoint] | ||
38 | |||
39 | If you do not | ||
40 | provide mntpoint, Wic creates a partition but does not mount it. | ||
41 | |||
42 | The ``mntpoint`` is where the partition is mounted and must be in one of | ||
43 | the following forms: | ||
44 | |||
45 | - ``/path``: For example, "/", "/usr", or "/home" | ||
46 | |||
47 | - ``swap``: The created partition is used as swap space | ||
48 | |||
49 | Specifying a mntpoint causes the partition to automatically be mounted. | ||
50 | Wic achieves this by adding entries to the filesystem table (fstab) | ||
51 | during image generation. In order for Wic to generate a valid fstab, you | ||
52 | must also provide one of the ``--ondrive``, ``--ondisk``, or | ||
53 | ``--use-uuid`` partition options as part of the command. | ||
54 | |||
55 | .. note:: | ||
56 | |||
57 | The mount program must understand the PARTUUID syntax you use with | ||
58 | --use-uuid | ||
59 | and non-root | ||
60 | mountpoint | ||
61 | , including swap. The busybox versions of these application are | ||
62 | currently excluded. | ||
63 | |||
64 | Here is an example that uses "/" as the mountpoint. The command uses | ||
65 | ``--ondisk`` to force the partition onto the ``sdb`` disk: part / | ||
66 | --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 | ||
67 | |||
68 | Here is a list that describes other supported options you can use with | ||
69 | the ``part`` and ``partition`` commands: | ||
70 | |||
71 | - ``--size``: The minimum partition size in MBytes. Specify an | ||
72 | integer value such as 500. Do not append the number with "MB". You do | ||
73 | not need this option if you use ``--source``. | ||
74 | |||
75 | - ``--fixed-size``: The exact partition size in MBytes. You cannot | ||
76 | specify with ``--size``. An error occurs when assembling the disk | ||
77 | image if the partition data is larger than ``--fixed-size``. | ||
78 | |||
79 | - ``--source``: This option is a Wic-specific option that names the | ||
80 | source of the data that populates the partition. The most common | ||
81 | value for this option is "rootfs", but you can use any value that | ||
82 | maps to a valid source plugin. For information on the source plugins, | ||
83 | see the ":ref:`dev-manual/dev-manual-common-tasks:using the wic plugin interface`" | ||
84 | section in the Yocto Project Development Tasks Manual. | ||
85 | |||
86 | If you use ``--source rootfs``, Wic creates a partition as large as | ||
87 | needed and fills it with the contents of the root filesystem pointed | ||
88 | to by the ``-r`` command-line option or the equivalent rootfs derived | ||
89 | from the ``-e`` command-line option. The filesystem type used to | ||
90 | create the partition is driven by the value of the ``--fstype`` | ||
91 | option specified for the partition. See the entry on ``--fstype`` | ||
92 | that follows for more information. | ||
93 | |||
94 | If you use ``--source plugin-name``, Wic creates a partition as large | ||
95 | as needed and fills it with the contents of the partition that is | ||
96 | generated by the specified plugin name using the data pointed to by | ||
97 | the ``-r`` command-line option or the equivalent rootfs derived from | ||
98 | the ``-e`` command-line option. Exactly what those contents are and | ||
99 | filesystem type used are dependent on the given plugin | ||
100 | implementation. | ||
101 | |||
102 | If you do not use the ``--source`` option, the ``wic`` command | ||
103 | creates an empty partition. Consequently, you must use the ``--size`` | ||
104 | option to specify the size of the empty partition. | ||
105 | |||
106 | - ``--ondisk`` or ``--ondrive``: Forces the partition to be created | ||
107 | on a particular disk. | ||
108 | |||
109 | - ``--fstype``: Sets the file system type for the partition. Valid | ||
110 | values are: | ||
111 | |||
112 | - ``ext4`` | ||
113 | |||
114 | - ``ext3`` | ||
115 | |||
116 | - ``ext2`` | ||
117 | |||
118 | - ``btrfs`` | ||
119 | |||
120 | - ``squashfs`` | ||
121 | |||
122 | - ``swap`` | ||
123 | |||
124 | - ``--fsoptions``: Specifies a free-form string of options to be used | ||
125 | when mounting the filesystem. This string is copied into the | ||
126 | ``/etc/fstab`` file of the installed system and should be enclosed in | ||
127 | quotes. If not specified, the default string is "defaults". | ||
128 | |||
129 | - ``--label label``: Specifies the label to give to the filesystem to | ||
130 | be made on the partition. If the given label is already in use by | ||
131 | another filesystem, a new label is created for the partition. | ||
132 | |||
133 | - ``--active``: Marks the partition as active. | ||
134 | |||
135 | - ``--align (in KBytes)``: This option is a Wic-specific option that | ||
136 | says to start partitions on boundaries given x KBytes. | ||
137 | |||
138 | - ``--no-table``: This option is a Wic-specific option. Using the | ||
139 | option reserves space for the partition and causes it to become | ||
140 | populated. However, the partition is not added to the partition | ||
141 | table. | ||
142 | |||
143 | - ``--exclude-path``: This option is a Wic-specific option that | ||
144 | excludes the given relative path from the resulting image. This | ||
145 | option is only effective with the rootfs source plugin. | ||
146 | |||
147 | - ``--extra-space``: This option is a Wic-specific option that adds | ||
148 | extra space after the space filled by the content of the partition. | ||
149 | The final size can exceed the size specified by the ``--size`` | ||
150 | option. The default value is 10 Mbytes. | ||
151 | |||
152 | - ``--overhead-factor``: This option is a Wic-specific option that | ||
153 | multiplies the size of the partition by the option's value. You must | ||
154 | supply a value greater than or equal to "1". The default value is | ||
155 | "1.3". | ||
156 | |||
157 | - ``--part-name``: This option is a Wic-specific option that | ||
158 | specifies a name for GPT partitions. | ||
159 | |||
160 | - ``--part-type``: This option is a Wic-specific option that | ||
161 | specifies the partition type globally unique identifier (GUID) for | ||
162 | GPT partitions. You can find the list of partition type GUIDs at | ||
163 | http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs. | ||
164 | |||
165 | - ``--use-uuid``: This option is a Wic-specific option that causes | ||
166 | Wic to generate a random GUID for the partition. The generated | ||
167 | identifier is used in the bootloader configuration to specify the | ||
168 | root partition. | ||
169 | |||
170 | - ``--uuid``: This option is a Wic-specific option that specifies the | ||
171 | partition UUID. | ||
172 | |||
173 | - ``--fsuuid``: This option is a Wic-specific option that specifies | ||
174 | the filesystem UUID. You can generate or modify | ||
175 | :term:`WKS_FILE` with this option if a preconfigured | ||
176 | filesystem UUID is added to the kernel command line in the bootloader | ||
177 | configuration before you run Wic. | ||
178 | |||
179 | - ``--system-id``: This option is a Wic-specific option that | ||
180 | specifies the partition system ID, which is a one byte long, | ||
181 | hexadecimal parameter with or without the 0x prefix. | ||
182 | |||
183 | - ``--mkfs-extraopts``: This option specifies additional options to | ||
184 | pass to the ``mkfs`` utility. Some default options for certain | ||
185 | filesystems do not take effect. See Wic's help on kickstart (i.e. | ||
186 | ``wic help kickstart``). | ||
187 | |||
188 | Command: bootloader | ||
189 | =================== | ||
190 | |||
191 | This command specifies how the bootloader should be configured and | ||
192 | supports the following options: | ||
193 | |||
194 | .. note:: | ||
195 | |||
196 | Bootloader functionality and boot partitions are implemented by the | ||
197 | various | ||
198 | --source | ||
199 | plugins that implement bootloader functionality. The bootloader | ||
200 | command essentially provides a means of modifying bootloader | ||
201 | configuration. | ||
202 | |||
203 | - ``--timeout``: Specifies the number of seconds before the | ||
204 | bootloader times out and boots the default option. | ||
205 | |||
206 | - ``--append``: Specifies kernel parameters. These parameters will be | ||
207 | added to the syslinux ``APPEND`` or ``grub`` kernel command line. | ||
208 | |||
209 | - ``--configfile``: Specifies a user-defined configuration file for | ||
210 | the bootloader. You can provide a full pathname for the file or a | ||
211 | file that exists in the ``canned-wks`` folder. This option overrides | ||
212 | all other bootloader options. | ||
diff --git a/documentation/ref-manual/ref-kickstart.xml b/documentation/ref-manual/ref-kickstart.xml index 1128bd50d0..45db1c0ff8 100644 --- a/documentation/ref-manual/ref-kickstart.xml +++ b/documentation/ref-manual/ref-kickstart.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-kickstart'> | 6 | <chapter id='ref-kickstart'> |
6 | <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title> | 7 | <title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title> |
diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl index c58dd905b9..3181f618e2 100644 --- a/documentation/ref-manual/ref-manual-customization.xsl +++ b/documentation/ref-manual/ref-manual-customization.xsl | |||
@@ -1,4 +1,6 @@ | |||
1 | <?xml version='1.0'?> | 1 | <?xml version='1.0'?> |
2 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
3 | |||
2 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> | 4 | <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> |
3 | 5 | ||
4 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> | 6 | <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> |
diff --git a/documentation/ref-manual/ref-manual.rst b/documentation/ref-manual/ref-manual.rst new file mode 100644 index 0000000000..a106af21d8 --- /dev/null +++ b/documentation/ref-manual/ref-manual.rst | |||
@@ -0,0 +1,31 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ============================== | ||
4 | Yocto Project Reference Manual | ||
5 | ============================== | ||
6 | |||
7 | | | ||
8 | |||
9 | .. toctree:: | ||
10 | :caption: Table of Contents | ||
11 | :numbered: | ||
12 | |||
13 | ref-system-requirements | ||
14 | ref-terms | ||
15 | ref-release-process | ||
16 | migration | ||
17 | ref-structure | ||
18 | ref-classes | ||
19 | ref-tasks | ||
20 | ref-devtool-reference | ||
21 | ref-kickstart | ||
22 | ref-qa-checks | ||
23 | ref-images | ||
24 | ref-features | ||
25 | ref-variables | ||
26 | ref-varlocality | ||
27 | faq | ||
28 | resources | ||
29 | history | ||
30 | |||
31 | .. include:: /boilerplate.rst | ||
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml index 1b82a41a7d..9a914f19cf 100755 --- a/documentation/ref-manual/ref-manual.xml +++ b/documentation/ref-manual/ref-manual.xml | |||
@@ -128,28 +128,8 @@ | |||
128 | </revision> | 128 | </revision> |
129 | <revision> | 129 | <revision> |
130 | <revnumber>3.1</revnumber> | 130 | <revnumber>3.1</revnumber> |
131 | <date>April 2020</date> | ||
132 | <revremark>Released with the Yocto Project 3.1 Release.</revremark> | ||
133 | </revision> | ||
134 | <revision> | ||
135 | <revnumber>3.1.1</revnumber> | ||
136 | <date>June 2020</date> | ||
137 | <revremark>Released with the Yocto Project 3.1.1 Release.</revremark> | ||
138 | </revision> | ||
139 | <revision> | ||
140 | <revnumber>3.1.2</revnumber> | ||
141 | <date>August 2020</date> | ||
142 | <revremark>Released with the Yocto Project 3.1.2 Release.</revremark> | ||
143 | </revision> | ||
144 | <revision> | ||
145 | <revnumber>3.1.3</revnumber> | ||
146 | <date>October 2020</date> | ||
147 | <revremark>Released with the Yocto Project 3.1.3 Release.</revremark> | ||
148 | </revision> | ||
149 | <revision> | ||
150 | <revnumber>3.1.4</revnumber> | ||
151 | <date>&REL_MONTH_YEAR;</date> | 131 | <date>&REL_MONTH_YEAR;</date> |
152 | <revremark>Released with the Yocto Project 3.1.4 Release.</revremark> | 132 | <revremark>Released with the Yocto Project 3.1 Release.</revremark> |
153 | </revision> | 133 | </revision> |
154 | </revhistory> | 134 | </revhistory> |
155 | 135 | ||
diff --git a/documentation/ref-manual/ref-qa-checks.rst b/documentation/ref-manual/ref-qa-checks.rst new file mode 100644 index 0000000000..3e76ac1509 --- /dev/null +++ b/documentation/ref-manual/ref-qa-checks.rst | |||
@@ -0,0 +1,533 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ***************************** | ||
4 | QA Error and Warning Messages | ||
5 | ***************************** | ||
6 | |||
7 | .. _qa-introduction: | ||
8 | |||
9 | Introduction | ||
10 | ============ | ||
11 | |||
12 | When building a recipe, the OpenEmbedded build system performs various | ||
13 | QA checks on the output to ensure that common issues are detected and | ||
14 | reported. Sometimes when you create a new recipe to build new software, | ||
15 | it will build with no problems. When this is not the case, or when you | ||
16 | have QA issues building any software, it could take a little time to | ||
17 | resolve them. | ||
18 | |||
19 | While it is tempting to ignore a QA message or even to disable QA | ||
20 | checks, it is best to try and resolve any reported QA issues. This | ||
21 | chapter provides a list of the QA messages and brief explanations of the | ||
22 | issues you could encounter so that you can properly resolve problems. | ||
23 | |||
24 | The next section provides a list of all QA error and warning messages | ||
25 | based on a default configuration. Each entry provides the message or | ||
26 | error form along with an explanation. | ||
27 | |||
28 | .. note:: | ||
29 | |||
30 | - At the end of each message, the name of the associated QA test (as | ||
31 | listed in the ":ref:`insane.bbclass <ref-classes-insane>`" | ||
32 | section) appears within square brackets. | ||
33 | |||
34 | - As mentioned, this list of error and warning messages is for QA | ||
35 | checks only. The list does not cover all possible build errors or | ||
36 | warnings you could encounter. | ||
37 | |||
38 | - Because some QA checks are disabled by default, this list does not | ||
39 | include all possible QA check errors and warnings. | ||
40 | |||
41 | .. _qa-errors-and-warnings: | ||
42 | |||
43 | Errors and Warnings | ||
44 | =================== | ||
45 | |||
46 | - ``<packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]`` | ||
47 | |||
48 | The specified package contains files in ``/usr/libexec`` when the | ||
49 | distro configuration uses a different path for ``<libexecdir>`` By | ||
50 | default, ``<libexecdir>`` is ``$prefix/libexec``. However, this | ||
51 | default can be changed (e.g. ``${libdir}``). | ||
52 | |||
53 | |||
54 | |||
55 | - ``package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]`` | ||
56 | |||
57 | The specified binary produced by the recipe contains dynamic library | ||
58 | load paths (rpaths) that contain build system paths such as | ||
59 | :term:`TMPDIR`, which are incorrect for the target and | ||
60 | could potentially be a security issue. Check for bad ``-rpath`` | ||
61 | options being passed to the linker in your | ||
62 | :ref:`ref-tasks-compile` log. Depending on the build | ||
63 | system used by the software being built, there might be a configure | ||
64 | option to disable rpath usage completely within the build of the | ||
65 | software. | ||
66 | |||
67 | |||
68 | |||
69 | - ``<packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]`` | ||
70 | |||
71 | The specified binary produced by the recipe contains dynamic library | ||
72 | load paths (rpaths) that on a standard system are searched by default | ||
73 | by the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths | ||
74 | will not cause any breakage, they do waste space and are unnecessary. | ||
75 | Depending on the build system used by the software being built, there | ||
76 | might be a configure option to disable rpath usage completely within | ||
77 | the build of the software. | ||
78 | |||
79 | |||
80 | |||
81 | - ``<packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]`` | ||
82 | |||
83 | A file-level dependency has been identified from the specified | ||
84 | package on the specified files, but there is no explicit | ||
85 | corresponding entry in :term:`RDEPENDS`. If | ||
86 | particular files are required at runtime then ``RDEPENDS`` should be | ||
87 | declared in the recipe to ensure the packages providing them are | ||
88 | built. | ||
89 | |||
90 | |||
91 | |||
92 | - ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]`` | ||
93 | |||
94 | A runtime dependency exists between the two specified packages, but | ||
95 | there is nothing explicit within the recipe to enable the | ||
96 | OpenEmbedded build system to ensure that dependency is satisfied. | ||
97 | This condition is usually triggered by an | ||
98 | :term:`RDEPENDS` value being added at the packaging | ||
99 | stage rather than up front, which is usually automatic based on the | ||
100 | contents of the package. In most cases, you should change the recipe | ||
101 | to add an explicit ``RDEPENDS`` for the dependency. | ||
102 | |||
103 | |||
104 | |||
105 | - ``non -dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]`` | ||
106 | |||
107 | Symlink ``.so`` files are for development only, and should therefore | ||
108 | go into the ``-dev`` package. This situation might occur if you add | ||
109 | ``*.so*`` rather than ``*.so.*`` to a non-dev package. Change | ||
110 | :term:`FILES` (and possibly | ||
111 | :term:`PACKAGES`) such that the specified ``.so`` | ||
112 | file goes into an appropriate ``-dev`` package. | ||
113 | |||
114 | |||
115 | |||
116 | - ``non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]`` | ||
117 | |||
118 | Static ``.a`` library files should go into a ``-staticdev`` package. | ||
119 | Change :term:`FILES` (and possibly | ||
120 | :term:`PACKAGES`) such that the specified ``.a`` file | ||
121 | goes into an appropriate ``-staticdev`` package. | ||
122 | |||
123 | |||
124 | |||
125 | - ``<packagename>: found library in wrong location [libdir]`` | ||
126 | |||
127 | The specified file may have been installed into an incorrect | ||
128 | (possibly hardcoded) installation path. For example, this test will | ||
129 | catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is | ||
130 | "lib32". Another example is when recipes install | ||
131 | ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". False | ||
132 | positives occasionally exist. For these cases add "libdir" to | ||
133 | :term:`INSANE_SKIP` for the package. | ||
134 | |||
135 | |||
136 | |||
137 | - ``non debug package contains .debug directory: <packagename> path <path> [debug-files]`` | ||
138 | |||
139 | The specified package contains a ``.debug`` directory, which should | ||
140 | not appear in anything but the ``-dbg`` package. This situation might | ||
141 | occur if you add a path which contains a ``.debug`` directory and do | ||
142 | not explicitly add the ``.debug`` directory to the ``-dbg`` package. | ||
143 | If this is the case, add the ``.debug`` directory explicitly to | ||
144 | ``FILES_${PN}-dbg``. See :term:`FILES` for additional | ||
145 | information on ``FILES``. | ||
146 | |||
147 | |||
148 | |||
149 | - ``Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]`` | ||
150 | |||
151 | By default, the OpenEmbedded build system checks the Executable and | ||
152 | Linkable Format (ELF) type, bit size, and endianness of any binaries | ||
153 | to ensure they match the target architecture. This test fails if any | ||
154 | binaries do not match the type since there would be an | ||
155 | incompatibility. The test could indicate that the wrong compiler or | ||
156 | compiler options have been used. Sometimes software, like | ||
157 | bootloaders, might need to bypass this check. If the file you receive | ||
158 | the error for is firmware that is not intended to be executed within | ||
159 | the target operating system or is intended to run on a separate | ||
160 | processor within the device, you can add "arch" to | ||
161 | :term:`INSANE_SKIP` for the package. Another | ||
162 | option is to check the :ref:`ref-tasks-compile` log | ||
163 | and verify that the compiler options being used are correct. | ||
164 | |||
165 | |||
166 | |||
167 | - ``Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]`` | ||
168 | |||
169 | By default, the OpenEmbedded build system checks the Executable and | ||
170 | Linkable Format (ELF) type, bit size, and endianness of any binaries | ||
171 | to ensure they match the target architecture. This test fails if any | ||
172 | binaries do not match the type since there would be an | ||
173 | incompatibility. The test could indicate that the wrong compiler or | ||
174 | compiler options have been used. Sometimes software, like | ||
175 | bootloaders, might need to bypass this check. If the file you receive | ||
176 | the error for is firmware that is not intended to be executed within | ||
177 | the target operating system or is intended to run on a separate | ||
178 | processor within the device, you can add "arch" to | ||
179 | :term:`INSANE_SKIP` for the package. Another | ||
180 | option is to check the :ref:`ref-tasks-compile` log | ||
181 | and verify that the compiler options being used are correct. | ||
182 | |||
183 | |||
184 | |||
185 | - ``Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]`` | ||
186 | |||
187 | By default, the OpenEmbedded build system checks the Executable and | ||
188 | Linkable Format (ELF) type, bit size, and endianness of any binaries | ||
189 | to ensure they match the target architecture. This test fails if any | ||
190 | binaries do not match the type since there would be an | ||
191 | incompatibility. The test could indicate that the wrong compiler or | ||
192 | compiler options have been used. Sometimes software, like | ||
193 | bootloaders, might need to bypass this check. If the file you receive | ||
194 | the error for is firmware that is not intended to be executed within | ||
195 | the target operating system or is intended to run on a separate | ||
196 | processor within the device, you can add "arch" to | ||
197 | :term:`INSANE_SKIP` for the package. Another | ||
198 | option is to check the :ref:`ref-tasks-compile` log | ||
199 | and verify that the compiler options being used are correct. | ||
200 | |||
201 | |||
202 | |||
203 | - ``ELF binary '<file>' has relocations in .text [textrel]`` | ||
204 | |||
205 | The specified ELF binary contains relocations in its ``.text`` | ||
206 | sections. This situation can result in a performance impact at | ||
207 | runtime. | ||
208 | |||
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 | ||
211 | software that reads :term:`CFLAGS` when you build it, | ||
212 | you could add the following to your recipe: | ||
213 | :: | ||
214 | |||
215 | CFLAGS_append = " -fPIC " | ||
216 | |||
217 | For more information on text relocations at runtime, see | ||
218 | http://www.akkadia.org/drepper/textrelocs.html. | ||
219 | |||
220 | |||
221 | |||
222 | - ``No GNU_HASH in the elf binary: '<file>' [ldflags]`` | ||
223 | |||
224 | This indicates that binaries produced when building the recipe have | ||
225 | not been linked with the :term:`LDFLAGS` options | ||
226 | provided by the build system. Check to be sure that the ``LDFLAGS`` | ||
227 | variable is being passed to the linker command. A common workaround | ||
228 | for this situation is to pass in ``LDFLAGS`` using | ||
229 | :term:`TARGET_CC_ARCH` within the recipe as | ||
230 | follows: | ||
231 | :: | ||
232 | |||
233 | TARGET_CC_ARCH += "${LDFLAGS}" | ||
234 | |||
235 | |||
236 | |||
237 | - ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]`` | ||
238 | |||
239 | The specified package contains an Xorg driver, but does not have a | ||
240 | corresponding ABI package dependency. The xserver-xorg recipe | ||
241 | provides driver ABI names. All drivers should depend on the ABI | ||
242 | versions that they have been built against. Driver recipes that | ||
243 | include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will | ||
244 | automatically get these versions. Consequently, you should only need | ||
245 | to explicitly add dependencies to binary driver recipes. | ||
246 | |||
247 | |||
248 | |||
249 | - ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]`` | ||
250 | |||
251 | The ``/usr/share/info/dir`` should not be packaged. Add the following | ||
252 | line to your :ref:`ref-tasks-install` task or to your | ||
253 | ``do_install_append`` within the recipe as follows: | ||
254 | :: | ||
255 | |||
256 | rm ${D}${infodir}/dir | ||
257 | |||
258 | |||
259 | - ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]`` | ||
260 | |||
261 | The specified symlink points into :term:`TMPDIR` on the | ||
262 | host. Such symlinks will work on the host. However, they are clearly | ||
263 | invalid when running on the target. You should either correct the | ||
264 | symlink to use a relative path or remove the symlink. | ||
265 | |||
266 | |||
267 | |||
268 | - ``<file> failed sanity test (workdir) in path <path> [la]`` | ||
269 | |||
270 | The specified ``.la`` file contains :term:`TMPDIR` | ||
271 | paths. Any ``.la`` file containing these paths is incorrect since | ||
272 | ``libtool`` adds the correct sysroot prefix when using the files | ||
273 | automatically itself. | ||
274 | |||
275 | |||
276 | |||
277 | - ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]`` | ||
278 | |||
279 | The specified ``.pc`` file contains | ||
280 | :term:`TMPDIR`\ ``/``\ :term:`WORKDIR` | ||
281 | paths. Any ``.pc`` file containing these paths is incorrect since | ||
282 | ``pkg-config`` itself adds the correct sysroot prefix when the files | ||
283 | are accessed. | ||
284 | |||
285 | |||
286 | |||
287 | - ``<packagename> rdepends on <debug_packagename> [debug-deps]`` | ||
288 | |||
289 | A dependency exists between the specified non-dbg package (i.e. a | ||
290 | package whose name does not end in ``-dbg``) and a package that is a | ||
291 | ``dbg`` package. The ``dbg`` packages contain debug symbols and are | ||
292 | brought in using several different methods: | ||
293 | |||
294 | - Using the ``dbg-pkgs`` | ||
295 | :term:`IMAGE_FEATURES` value. | ||
296 | |||
297 | - Using :term:`IMAGE_INSTALL`. | ||
298 | |||
299 | - As a dependency of another ``dbg`` package that was brought in | ||
300 | using one of the above methods. | ||
301 | |||
302 | The dependency might have been automatically added because the | ||
303 | ``dbg`` package erroneously contains files that it should not contain | ||
304 | (e.g. a non-symlink ``.so`` file) or it might have been added | ||
305 | manually (e.g. by adding to :term:`RDEPENDS`). | ||
306 | |||
307 | |||
308 | |||
309 | - ``<packagename> rdepends on <dev_packagename> [dev-deps]`` | ||
310 | |||
311 | A dependency exists between the specified non-dev package (a package | ||
312 | whose name does not end in ``-dev``) and a package that is a ``dev`` | ||
313 | package. The ``dev`` packages contain development headers and are | ||
314 | usually brought in using several different methods: | ||
315 | |||
316 | - Using the ``dev-pkgs`` | ||
317 | :term:`IMAGE_FEATURES` value. | ||
318 | |||
319 | - Using :term:`IMAGE_INSTALL`. | ||
320 | |||
321 | - As a dependency of another ``dev`` package that was brought in | ||
322 | using one of the above methods. | ||
323 | |||
324 | The dependency might have been automatically added (because the | ||
325 | ``dev`` package erroneously contains files that it should not have | ||
326 | (e.g. a non-symlink ``.so`` file) or it might have been added | ||
327 | manually (e.g. by adding to :term:`RDEPENDS`). | ||
328 | |||
329 | |||
330 | |||
331 | - ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]`` | ||
332 | |||
333 | If you are adding a versioned dependency relationship to one of the | ||
334 | dependency variables (:term:`RDEPENDS`, | ||
335 | :term:`RRECOMMENDS`, | ||
336 | :term:`RSUGGESTS`, | ||
337 | :term:`RPROVIDES`, | ||
338 | :term:`RREPLACES`, or | ||
339 | :term:`RCONFLICTS`), you must only use the named | ||
340 | comparison operators. Change the versioned dependency values you are | ||
341 | adding to match those listed in the message. | ||
342 | |||
343 | |||
344 | |||
345 | - ``<recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path]`` | ||
346 | |||
347 | The log for the :ref:`ref-tasks-compile` task | ||
348 | indicates that paths on the host were searched for files, which is | ||
349 | not appropriate when cross-compiling. Look for "is unsafe for | ||
350 | cross-compilation" or "CROSS COMPILE Badness" in the specified log | ||
351 | file. | ||
352 | |||
353 | |||
354 | |||
355 | - ``<recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path]`` | ||
356 | |||
357 | The log for the :ref:`ref-tasks-install` task | ||
358 | indicates that paths on the host were searched for files, which is | ||
359 | not appropriate when cross-compiling. Look for "is unsafe for | ||
360 | cross-compilation" or "CROSS COMPILE Badness" in the specified log | ||
361 | file. | ||
362 | |||
363 | |||
364 | |||
365 | - ``This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>'`` | ||
366 | |||
367 | The log for the :ref:`ref-tasks-configure` task | ||
368 | indicates that paths on the host were searched for files, which is | ||
369 | not appropriate when cross-compiling. Look for "is unsafe for | ||
370 | cross-compilation" or "CROSS COMPILE Badness" in the specified log | ||
371 | file. | ||
372 | |||
373 | |||
374 | |||
375 | - ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]`` | ||
376 | |||
377 | The convention within the OpenEmbedded build system (sometimes | ||
378 | enforced by the package manager itself) is to require that package | ||
379 | names are all lower case and to allow a restricted set of characters. | ||
380 | If your recipe name does not match this, or you add packages to | ||
381 | :term:`PACKAGES` that do not conform to the | ||
382 | convention, then you will receive this error. Rename your recipe. Or, | ||
383 | if you have added a non-conforming package name to ``PACKAGES``, | ||
384 | change the package name appropriately. | ||
385 | |||
386 | |||
387 | |||
388 | - ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]`` | ||
389 | |||
390 | The configure script is reporting that the specified options are | ||
391 | unrecognized. This situation could be because the options were | ||
392 | previously valid but have been removed from the configure script. Or, | ||
393 | there was a mistake when the options were added and there is another | ||
394 | option that should be used instead. If you are unsure, consult the | ||
395 | upstream build documentation, the ``./configure --help`` output, and | ||
396 | the upstream change log or release notes. Once you have worked out | ||
397 | what the appropriate change is, you can update | ||
398 | :term:`EXTRA_OECONF`, | ||
399 | :term:`PACKAGECONFIG_CONFARGS`, or the | ||
400 | individual :term:`PACKAGECONFIG` option values | ||
401 | accordingly. | ||
402 | |||
403 | |||
404 | |||
405 | - ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]`` | ||
406 | |||
407 | The specified recipe has a name (:term:`PN`) value that | ||
408 | appears in :term:`OVERRIDES`. If a recipe is named | ||
409 | such that its ``PN`` value matches something already in ``OVERRIDES`` | ||
410 | (e.g. ``PN`` happens to be the same as :term:`MACHINE` | ||
411 | or :term:`DISTRO`), it can have unexpected | ||
412 | consequences. For example, assignments such as | ||
413 | ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``. | ||
414 | Rename your recipe (or if ``PN`` is being set explicitly, change the | ||
415 | ``PN`` value) so that the conflict does not occur. See | ||
416 | :term:`FILES` for additional information. | ||
417 | |||
418 | |||
419 | |||
420 | - ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]`` | ||
421 | |||
422 | Certain variables (:term:`RDEPENDS`, | ||
423 | :term:`RRECOMMENDS`, | ||
424 | :term:`RSUGGESTS`, | ||
425 | :term:`RCONFLICTS`, | ||
426 | :term:`RPROVIDES`, | ||
427 | :term:`RREPLACES`, :term:`FILES`, | ||
428 | ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and | ||
429 | :term:`ALLOW_EMPTY`) should always be set specific | ||
430 | to a package (i.e. they should be set with a package name override | ||
431 | such as ``RDEPENDS_${PN} = "value"`` rather than | ||
432 | ``RDEPENDS = "value"``). If you receive this error, correct any | ||
433 | assignments to these variables within your recipe. | ||
434 | |||
435 | |||
436 | |||
437 | - ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]`` | ||
438 | |||
439 | Produced binaries have already been stripped prior to the build | ||
440 | system extracting debug symbols. It is common for upstream software | ||
441 | projects to default to stripping debug symbols for output binaries. | ||
442 | In order for debugging to work on the target using ``-dbg`` packages, | ||
443 | this stripping must be disabled. | ||
444 | |||
445 | Depending on the build system used by the software being built, | ||
446 | disabling this stripping could be as easy as specifying an additional | ||
447 | configure option. If not, disabling stripping might involve patching | ||
448 | the build scripts. In the latter case, look for references to "strip" | ||
449 | or "STRIP", or the "-s" or "-S" command-line options being specified | ||
450 | on the linker command line (possibly through the compiler command | ||
451 | line if preceded with "-Wl,"). | ||
452 | |||
453 | .. note:: | ||
454 | |||
455 | Disabling stripping here does not mean that the final packaged | ||
456 | binaries will be unstripped. Once the OpenEmbedded build system | ||
457 | splits out debug symbols to the | ||
458 | -dbg | ||
459 | package, it will then strip the symbols from the binaries. | ||
460 | |||
461 | |||
462 | |||
463 | - ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]`` | ||
464 | |||
465 | Package names must appear only once in the | ||
466 | :term:`PACKAGES` variable. You might receive this | ||
467 | error if you are attempting to add a package to ``PACKAGES`` that is | ||
468 | already in the variable's value. | ||
469 | |||
470 | |||
471 | |||
472 | - ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]`` | ||
473 | |||
474 | The string "//" is invalid in a Unix path. Correct all occurrences | ||
475 | where this string appears in a :term:`FILES` variable so | ||
476 | that there is only a single "/". | ||
477 | |||
478 | |||
479 | |||
480 | - ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]`` | ||
481 | |||
482 | Files have been installed within the | ||
483 | :ref:`ref-tasks-install` task but have not been | ||
484 | included in any package by way of the :term:`FILES` | ||
485 | variable. Files that do not appear in any package cannot be present | ||
486 | in an image later on in the build process. You need to do one of the | ||
487 | following: | ||
488 | |||
489 | - Add the files to ``FILES`` for the package you want them to appear | ||
490 | in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main | ||
491 | package). | ||
492 | |||
493 | - Delete the files at the end of the ``do_install`` task if the | ||
494 | files are not needed in any package. | ||
495 | |||
496 | |||
497 | |||
498 | - ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later`` | ||
499 | |||
500 | This message means that both ``<oldpackage>`` and ``<newpackage>`` | ||
501 | provide the specified shared library. You can expect this message | ||
502 | when a recipe has been renamed. However, if that is not the case, the | ||
503 | message might indicate that a private version of a library is being | ||
504 | erroneously picked up as the provider for a common library. If that | ||
505 | is the case, you should add the library's ``.so`` file name to | ||
506 | :term:`PRIVATE_LIBS` in the recipe that provides | ||
507 | the private version of the library. | ||
508 | |||
509 | - ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]`` | ||
510 | |||
511 | The :term:`LICENSE` of the recipe should be a superset | ||
512 | of all the licenses of all packages produced by this recipe. In other | ||
513 | words, any license in ``LICENSE_*`` should also appear in | ||
514 | :term:`LICENSE`. | ||
515 | |||
516 | |||
517 | |||
518 | Configuring and Disabling QA Checks | ||
519 | =================================== | ||
520 | |||
521 | You can configure the QA checks globally so that specific check failures | ||
522 | either raise a warning or an error message, using the | ||
523 | :term:`WARN_QA` and :term:`ERROR_QA` | ||
524 | variables, respectively. You can also disable checks within a particular | ||
525 | recipe using :term:`INSANE_SKIP`. For information on | ||
526 | how to work with the QA checks, see the | ||
527 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | ||
528 | |||
529 | .. note:: | ||
530 | |||
531 | Please keep in mind that the QA checks exist in order to detect real | ||
532 | or potential problems in the packaged output. So exercise caution | ||
533 | when disabling these checks. | ||
diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml index 515106ae68..0071e4a55d 100644 --- a/documentation/ref-manual/ref-qa-checks.xml +++ b/documentation/ref-manual/ref-qa-checks.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-qa-checks'> | 6 | <chapter id='ref-qa-checks'> |
6 | <title>QA Error and Warning Messages</title> | 7 | <title>QA Error and Warning Messages</title> |
@@ -1170,6 +1171,31 @@ can be found then it should be implemented. I can't find one at the moment. | |||
1170 | </listitem> | 1171 | </listitem> |
1171 | </itemizedlist> | 1172 | </itemizedlist> |
1172 | </para> | 1173 | </para> |
1174 | |||
1175 | <para> | ||
1176 | <itemizedlist> | ||
1177 | <listitem> | ||
1178 | <para id='qa-issue-unlisted-pkg-lics'> | ||
1179 | <code> | ||
1180 | LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics] | ||
1181 | </code> | ||
1182 | </para> | ||
1183 | |||
1184 | <para> | ||
1185 | The <link linkend='var-LICENSE'><filename>LICENSE</filename></link> | ||
1186 | of the recipe should be a superset of all the licenses of | ||
1187 | all packages produced by this recipe. | ||
1188 | In other words, any license in <filename>LICENSE_*</filename> | ||
1189 | should also appear in | ||
1190 | <link linkend='var-LICENSE'><filename>LICENSE</filename></link>. | ||
1191 | </para> | ||
1192 | |||
1193 | <para> | ||
1194 | | ||
1195 | </para> | ||
1196 | </listitem> | ||
1197 | </itemizedlist> | ||
1198 | </para> | ||
1173 | </section> | 1199 | </section> |
1174 | 1200 | ||
1175 | <section id='configuring-and-disabling-qa-checks'> | 1201 | <section id='configuring-and-disabling-qa-checks'> |
diff --git a/documentation/ref-manual/ref-release-process.rst b/documentation/ref-manual/ref-release-process.rst new file mode 100644 index 0000000000..be041e7254 --- /dev/null +++ b/documentation/ref-manual/ref-release-process.rst | |||
@@ -0,0 +1,193 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ***************************************************** | ||
4 | Yocto Project Releases and the Stable Release Process | ||
5 | ***************************************************** | ||
6 | |||
7 | The Yocto Project release process is predictable and consists of both | ||
8 | major and minor (point) releases. This brief chapter provides | ||
9 | information on how releases are named, their life cycle, and their | ||
10 | stability. | ||
11 | |||
12 | Major and Minor Release Cadence | ||
13 | =============================== | ||
14 | |||
15 | The Yocto Project delivers major releases (e.g. DISTRO) using a six | ||
16 | month cadence roughly timed each April and October of the year. | ||
17 | Following are examples of some major YP releases with their codenames | ||
18 | also shown. See the "`Major Release | ||
19 | Codenames <#major-release-codenames>`__" section for information on | ||
20 | codenames used with major releases. | ||
21 | |||
22 | - 2.2 (Morty) | ||
23 | - 2.1 (Krogoth) | ||
24 | - 2.0 (Jethro) | ||
25 | |||
26 | While the cadence is never perfect, this timescale facilitates | ||
27 | regular releases that have strong QA cycles while not overwhelming users | ||
28 | with too many new releases. The cadence is predictable and avoids many | ||
29 | major holidays in various geographies. | ||
30 | |||
31 | The Yocto project delivers minor (point) releases on an unscheduled | ||
32 | basis and are usually driven by the accumulation of enough significant | ||
33 | fixes or enhancements to the associated major release. Following are | ||
34 | some example past point releases: | ||
35 | |||
36 | - 2.1.1 | ||
37 | - 2.1.2 | ||
38 | - 2.2.1 | ||
39 | |||
40 | The point release | ||
41 | indicates a point in the major release branch where a full QA cycle and | ||
42 | release process validates the content of the new branch. | ||
43 | |||
44 | .. note:: | ||
45 | |||
46 | Realize that there can be patches merged onto the stable release | ||
47 | branches as and when they become available. | ||
48 | |||
49 | Major Release Codenames | ||
50 | ======================= | ||
51 | |||
52 | Each major release receives a codename that identifies the release in | ||
53 | the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`. | ||
54 | The concept is that branches of :term:`Metadata` with the same | ||
55 | codename are likely to be compatible and thus work together. | ||
56 | |||
57 | .. note:: | ||
58 | |||
59 | Codenames are associated with major releases because a Yocto Project | ||
60 | release number (e.g. DISTRO) could conflict with a given layer or | ||
61 | company versioning scheme. Codenames are unique, interesting, and | ||
62 | easily identifiable. | ||
63 | |||
64 | Releases are given a nominal release version as well but the codename is | ||
65 | used in repositories for this reason. You can find information on Yocto | ||
66 | Project releases and codenames at | ||
67 | https://wiki.yoctoproject.org/wiki/Releases. | ||
68 | |||
69 | Stable Release Process | ||
70 | ====================== | ||
71 | |||
72 | Once released, the release enters the stable release process at which | ||
73 | time a person is assigned as the maintainer for that stable release. | ||
74 | This maintainer monitors activity for the release by investigating and | ||
75 | handling nominated patches and backport activity. Only fixes and | ||
76 | enhancements that have first been applied on the "master" branch (i.e. | ||
77 | the current, in-development branch) are considered for backporting to a | ||
78 | stable release. | ||
79 | |||
80 | .. note:: | ||
81 | |||
82 | The current Yocto Project policy regarding backporting is to consider | ||
83 | bug fixes and security fixes only. Policy dictates that features are | ||
84 | not backported to a stable release. This policy means generic recipe | ||
85 | version upgrades are unlikely to be accepted for backporting. The | ||
86 | exception to this policy occurs when a strong reason exists such as | ||
87 | the fix happens to also be the preferred upstream approach. | ||
88 | |||
89 | Stable release branches have strong maintenance for about a year after | ||
90 | their initial release. Should significant issues be found for any | ||
91 | release regardless of its age, fixes could be backported to older | ||
92 | releases. For issues that are not backported given an older release, | ||
93 | Community LTS trees and branches exist where community members share | ||
94 | patches for older releases. However, these types of patches do not go | ||
95 | through the same release process as do point releases. You can find more | ||
96 | information about stable branch maintenance at | ||
97 | https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance. | ||
98 | |||
99 | Testing and Quality Assurance | ||
100 | ============================= | ||
101 | |||
102 | Part of the Yocto Project development and release process is quality | ||
103 | assurance through the execution of test strategies. Test strategies | ||
104 | provide the Yocto Project team a way to ensure a release is validated. | ||
105 | Additionally, because the test strategies are visible to you as a | ||
106 | developer, you can validate your projects. This section overviews the | ||
107 | available test infrastructure used in the Yocto Project. For information | ||
108 | on how to run available tests on your projects, see the | ||
109 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
110 | section in the Yocto Project Development Tasks Manual. | ||
111 | |||
112 | The QA/testing infrastructure is woven into the project to the point | ||
113 | where core developers take some of it for granted. The infrastructure | ||
114 | consists of the following pieces: | ||
115 | |||
116 | - ``bitbake-selftest``: A standalone command that runs unit tests on | ||
117 | key pieces of BitBake and its fetchers. | ||
118 | |||
119 | - :ref:`sanity.bbclass <ref-classes-sanity>`: This automatically | ||
120 | included class checks the build environment for missing tools (e.g. | ||
121 | ``gcc``) or common misconfigurations such as | ||
122 | :term:`MACHINE` set incorrectly. | ||
123 | |||
124 | - :ref:`insane.bbclass <ref-classes-insane>`: This class checks the | ||
125 | generated output from builds for sanity. For example, if building for | ||
126 | an ARM target, did the build produce ARM binaries. If, for example, | ||
127 | the build produced PPC binaries then there is a problem. | ||
128 | |||
129 | - :ref:`testimage.bbclass <ref-classes-testimage*>`: This class | ||
130 | performs runtime testing of images after they are built. The tests | ||
131 | are usually used with :doc:`QEMU <../dev-manual/dev-manual-qemu>` | ||
132 | to boot the images and check the combined runtime result boot | ||
133 | operation and functions. However, the test can also use the IP | ||
134 | address of a machine to test. | ||
135 | |||
136 | - :ref:`ptest <dev-manual/dev-manual-common-tasks:testing packages with ptest>`: | ||
137 | Runs tests against packages produced during the build for a given | ||
138 | piece of software. The test allows the packages to be be run within a | ||
139 | target image. | ||
140 | |||
141 | - ``oe-selftest``: Tests combination BitBake invocations. These tests | ||
142 | operate outside the OpenEmbedded build system itself. The | ||
143 | ``oe-selftest`` can run all tests by default or can run selected | ||
144 | tests or test suites. | ||
145 | |||
146 | .. note:: | ||
147 | |||
148 | Running | ||
149 | oe-selftest | ||
150 | requires host packages beyond the "Essential" grouping. See the " | ||
151 | Required Packages for the Build Host | ||
152 | " section for more information. | ||
153 | |||
154 | Originally, much of this testing was done manually. However, significant | ||
155 | effort has been made to automate the tests so that more people can use | ||
156 | them and the Yocto Project development team can run them faster and more | ||
157 | efficiently. | ||
158 | |||
159 | The Yocto Project's main Autobuilder (https://autobuilder.yoctoproject.org/) | ||
160 | publicly tests each Yocto Project release's code in the | ||
161 | :term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing | ||
162 | occurs for both the current state of the "master" branch and also for | ||
163 | submitted patches. Testing for submitted patches usually occurs in the | ||
164 | "ross/mut" branch in the ``poky-contrib`` repository (i.e. the | ||
165 | master-under-test branch) or in the "master-next" branch in the ``poky`` | ||
166 | repository. | ||
167 | |||
168 | .. note:: | ||
169 | |||
170 | You can find all these branches in the Yocto Project | ||
171 | Source Repositories | ||
172 | . | ||
173 | |||
174 | Testing within these public branches ensures in a publicly visible way | ||
175 | that all of the main supposed architectures and recipes in OE-Core | ||
176 | successfully build and behave properly. | ||
177 | |||
178 | Various features such as ``multilib``, sub architectures (e.g. ``x32``, | ||
179 | ``poky-tiny``, ``musl``, ``no-x11`` and and so forth), | ||
180 | ``bitbake-selftest``, and ``oe-selftest`` are tested as part of the QA | ||
181 | process of a release. Complete testing and validation for a release | ||
182 | takes the Autobuilder workers several hours. | ||
183 | |||
184 | .. note:: | ||
185 | |||
186 | The Autobuilder workers are non-homogeneous, which means regular | ||
187 | testing across a variety of Linux distributions occurs. The | ||
188 | Autobuilder is limited to only testing QEMU-based setups and not real | ||
189 | hardware. | ||
190 | |||
191 | Finally, in addition to the Autobuilder's tests, the Yocto Project QA | ||
192 | team also performs testing on a variety of platforms, which includes | ||
193 | actual hardware, to ensure expected results. | ||
diff --git a/documentation/ref-manual/ref-release-process.xml b/documentation/ref-manual/ref-release-process.xml index 5efe17417a..87f5308067 100644 --- a/documentation/ref-manual/ref-release-process.xml +++ b/documentation/ref-manual/ref-release-process.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-release-process'> | 6 | <chapter id='ref-release-process'> |
6 | <title>Yocto Project Releases and the Stable Release Process</title> | 7 | <title>Yocto Project Releases and the Stable Release Process</title> |
diff --git a/documentation/ref-manual/ref-structure.rst b/documentation/ref-manual/ref-structure.rst new file mode 100644 index 0000000000..48a443331b --- /dev/null +++ b/documentation/ref-manual/ref-structure.rst | |||
@@ -0,0 +1,890 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ************************** | ||
4 | Source Directory Structure | ||
5 | ************************** | ||
6 | |||
7 | The :term:`Source Directory` consists of numerous files, | ||
8 | directories and subdirectories; understanding their locations and | ||
9 | contents is key to using the Yocto Project effectively. This chapter | ||
10 | describes the Source Directory and gives information about those files | ||
11 | and directories. | ||
12 | |||
13 | For information on how to establish a local Source Directory on your | ||
14 | development system, see the | ||
15 | ":ref:`dev-manual/dev-manual-start:locating yocto project source files`" | ||
16 | section in the Yocto Project Development Tasks Manual. | ||
17 | |||
18 | .. note:: | ||
19 | |||
20 | The OpenEmbedded build system does not support file or directory | ||
21 | names that contain spaces. Be sure that the Source Directory you use | ||
22 | does not contain these types of names. | ||
23 | |||
24 | .. _structure-core: | ||
25 | |||
26 | Top-Level Core Components | ||
27 | ========================= | ||
28 | |||
29 | This section describes the top-level components of the :term:`Source Directory`. | ||
30 | |||
31 | .. _structure-core-bitbake: | ||
32 | |||
33 | ``bitbake/`` | ||
34 | ------------ | ||
35 | |||
36 | This directory includes a copy of BitBake for ease of use. The copy | ||
37 | usually matches the current stable BitBake release from the BitBake | ||
38 | project. BitBake, a :term:`Metadata` interpreter, reads the | ||
39 | Yocto Project Metadata and runs the tasks defined by that data. Failures | ||
40 | are usually caused by errors in your Metadata and not from BitBake | ||
41 | itself; consequently, most users do not need to worry about BitBake. | ||
42 | |||
43 | When you run the ``bitbake`` command, the main BitBake executable (which | ||
44 | resides in the ``bitbake/bin/`` directory) starts. Sourcing the | ||
45 | environment setup script (i.e. :ref:`structure-core-script`) places | ||
46 | the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into | ||
47 | the shell's ``PATH`` environment variable. | ||
48 | |||
49 | For more information on BitBake, see the :doc:`BitBake User Manual | ||
50 | <bitbake:index>`. | ||
51 | |||
52 | .. _structure-core-build: | ||
53 | |||
54 | ``build/`` | ||
55 | ---------- | ||
56 | |||
57 | This directory contains user configuration files and the output | ||
58 | generated by the OpenEmbedded build system in its standard configuration | ||
59 | where the source tree is combined with the output. The :term:`Build Directory` | ||
60 | is created initially when you ``source`` | ||
61 | the OpenEmbedded build environment setup script (i.e. | ||
62 | :ref:`structure-core-script`). | ||
63 | |||
64 | It is also possible to place output and configuration files in a | ||
65 | directory separate from the :term:`Source Directory` by | ||
66 | providing a directory name when you ``source`` the setup script. For | ||
67 | information on separating output from your local Source Directory files | ||
68 | (commonly described as an "out of tree" build), see the | ||
69 | ":ref:`structure-core-script`" section. | ||
70 | |||
71 | .. _handbook: | ||
72 | |||
73 | ``documentation/`` | ||
74 | ------------------ | ||
75 | |||
76 | This directory holds the source for the Yocto Project documentation as | ||
77 | well as templates and tools that allow you to generate PDF and HTML | ||
78 | versions of the manuals. Each manual is contained in its own sub-folder; | ||
79 | for example, the files for this reference manual reside in the | ||
80 | ``ref-manual/`` directory. | ||
81 | |||
82 | .. _structure-core-meta: | ||
83 | |||
84 | ``meta/`` | ||
85 | --------- | ||
86 | |||
87 | This directory contains the minimal, underlying OpenEmbedded-Core | ||
88 | metadata. The directory holds recipes, common classes, and machine | ||
89 | configuration for strictly emulated targets (``qemux86``, ``qemuarm``, | ||
90 | and so forth.) | ||
91 | |||
92 | .. _structure-core-meta-poky: | ||
93 | |||
94 | ``meta-poky/`` | ||
95 | -------------- | ||
96 | |||
97 | Designed above the ``meta/`` content, this directory adds just enough | ||
98 | metadata to define the Poky reference distribution. | ||
99 | |||
100 | .. _structure-core-meta-yocto-bsp: | ||
101 | |||
102 | ``meta-yocto-bsp/`` | ||
103 | ------------------- | ||
104 | |||
105 | This directory contains the Yocto Project reference hardware Board | ||
106 | Support Packages (BSPs). For more information on BSPs, see the | ||
107 | :doc:`../bsp-guide/bsp-guide`. | ||
108 | |||
109 | .. _structure-meta-selftest: | ||
110 | |||
111 | ``meta-selftest/`` | ||
112 | ------------------ | ||
113 | |||
114 | This directory adds additional recipes and append files used by the | ||
115 | OpenEmbedded selftests to verify the behavior of the build system. You | ||
116 | do not have to add this layer to your ``bblayers.conf`` file unless you | ||
117 | want to run the selftests. | ||
118 | |||
119 | .. _structure-meta-skeleton: | ||
120 | |||
121 | ``meta-skeleton/`` | ||
122 | ------------------ | ||
123 | |||
124 | This directory contains template recipes for BSP and kernel development. | ||
125 | |||
126 | .. _structure-core-scripts: | ||
127 | |||
128 | ``scripts/`` | ||
129 | ------------ | ||
130 | |||
131 | This directory contains various integration scripts that implement extra | ||
132 | functionality in the Yocto Project environment (e.g. QEMU scripts). The | ||
133 | :ref:`structure-core-script` script prepends this directory to the | ||
134 | shell's ``PATH`` environment variable. | ||
135 | |||
136 | The ``scripts`` directory has useful scripts that assist in contributing | ||
137 | back to the Yocto Project, such as ``create-pull-request`` and | ||
138 | ``send-pull-request``. | ||
139 | |||
140 | .. _structure-core-script: | ||
141 | |||
142 | ``oe-init-build-env`` | ||
143 | --------------------- | ||
144 | |||
145 | This script sets up the OpenEmbedded build environment. Running this | ||
146 | script with the ``source`` command in a shell makes changes to ``PATH`` | ||
147 | and sets other core BitBake variables based on the current working | ||
148 | directory. You need to run an environment setup script before running | ||
149 | BitBake commands. The script uses other scripts within the ``scripts`` | ||
150 | directory to do the bulk of the work. | ||
151 | |||
152 | When you run this script, your Yocto Project environment is set up, a | ||
153 | :term:`Build Directory` is created, your working | ||
154 | directory becomes the Build Directory, and you are presented with some | ||
155 | simple suggestions as to what to do next, including a list of some | ||
156 | possible targets to build. Here is an example: | ||
157 | :: | ||
158 | |||
159 | $ source oe-init-build-env | ||
160 | |||
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 | |||
173 | The default output of the ``oe-init-build-env`` script is from the | ||
174 | ``conf-notes.txt`` file, which is found in the ``meta-poky`` directory | ||
175 | within the :term:`Source Directory`. If you design a | ||
176 | custom distribution, you can include your own version of this | ||
177 | configuration file to mention the targets defined by your distribution. | ||
178 | See the | ||
179 | ":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" | ||
180 | section in the Yocto Project Development Tasks Manual for more | ||
181 | information. | ||
182 | |||
183 | By default, running this script without a Build Directory argument | ||
184 | creates the ``build/`` directory in your current working directory. If | ||
185 | you provide a Build Directory argument when you ``source`` the script, | ||
186 | you direct the OpenEmbedded build system to create a Build Directory of | ||
187 | your choice. For example, the following command creates a Build | ||
188 | Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: | ||
189 | :: | ||
190 | |||
191 | $ source OE_INIT_FILE ~/mybuilds | ||
192 | |||
193 | The OpenEmbedded build system uses the template configuration files, which | ||
194 | are found by default in the ``meta-poky/conf/`` directory in the Source | ||
195 | Directory. See the | ||
196 | ":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`" | ||
197 | section in the Yocto Project Development Tasks Manual for more | ||
198 | information. | ||
199 | |||
200 | .. note:: | ||
201 | |||
202 | The OpenEmbedded build system does not support file or directory | ||
203 | names that contain spaces. If you attempt to run the | ||
204 | OE_INIT_FILE | ||
205 | script from a Source Directory that contains spaces in either the | ||
206 | filenames or directory names, the script returns an error indicating | ||
207 | no such file or directory. Be sure to use a Source Directory free of | ||
208 | names containing spaces. | ||
209 | |||
210 | .. _structure-basic-top-level: | ||
211 | |||
212 | ``LICENSE, README, and README.hardware`` | ||
213 | ---------------------------------------- | ||
214 | |||
215 | These files are standard top-level files. | ||
216 | |||
217 | .. _structure-build: | ||
218 | |||
219 | The Build Directory - ``build/`` | ||
220 | ================================ | ||
221 | |||
222 | The OpenEmbedded build system creates the :term:`Build Directory` | ||
223 | when you run the build environment setup | ||
224 | script :ref:`structure-core-script`. If you do not give the Build | ||
225 | Directory a specific name when you run the setup script, the name | ||
226 | defaults to ``build/``. | ||
227 | |||
228 | For subsequent parsing and processing, the name of the Build directory | ||
229 | is available via the :term:`TOPDIR` variable. | ||
230 | |||
231 | .. _structure-build-buildhistory: | ||
232 | |||
233 | ``build/buildhistory/`` | ||
234 | ----------------------- | ||
235 | |||
236 | The OpenEmbedded build system creates this directory when you enable | ||
237 | build history via the ``buildhistory`` class file. The directory | ||
238 | organizes build information into image, packages, and SDK | ||
239 | subdirectories. For information on the build history feature, see the | ||
240 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
241 | section in the Yocto Project Development Tasks Manual. | ||
242 | |||
243 | .. _structure-build-conf-local.conf: | ||
244 | |||
245 | ``build/conf/local.conf`` | ||
246 | ------------------------- | ||
247 | |||
248 | This configuration file contains all the local user configurations for | ||
249 | your build environment. The ``local.conf`` file contains documentation | ||
250 | on the various configuration options. Any variable set here overrides | ||
251 | any variable set elsewhere within the environment unless that variable | ||
252 | is hard-coded within a file (e.g. by using '=' instead of '?='). Some | ||
253 | variables are hard-coded for various reasons but such variables are | ||
254 | relatively rare. | ||
255 | |||
256 | At a minimum, you would normally edit this file to select the target | ||
257 | ``MACHINE``, which package types you wish to use | ||
258 | (:term:`PACKAGE_CLASSES`), and the location from | ||
259 | which you want to access downloaded files (``DL_DIR``). | ||
260 | |||
261 | If ``local.conf`` is not present when you start the build, the | ||
262 | OpenEmbedded build system creates it from ``local.conf.sample`` when you | ||
263 | ``source`` the top-level build environment setup script | ||
264 | :ref:`structure-core-script`. | ||
265 | |||
266 | The source ``local.conf.sample`` file used depends on the | ||
267 | ``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` | ||
268 | when you are building from the Yocto Project development environment, | ||
269 | and to ``meta/conf/`` when you are building from the OpenEmbedded-Core | ||
270 | environment. Because the script variable points to the source of the | ||
271 | ``local.conf.sample`` file, this implies that you can configure your | ||
272 | build environment from any layer by setting the variable in the | ||
273 | top-level build environment setup script as follows: | ||
274 | :: | ||
275 | |||
276 | TEMPLATECONF=your_layer/conf | ||
277 | |||
278 | Once the build process gets the sample | ||
279 | file, it uses ``sed`` to substitute final | ||
280 | ``${``\ :term:`OEROOT`\ ``}`` values for all | ||
281 | ``##OEROOT##`` values. | ||
282 | |||
283 | .. note:: | ||
284 | |||
285 | You can see how the | ||
286 | TEMPLATECONF | ||
287 | variable is used by looking at the | ||
288 | scripts/oe-setup-builddir | ||
289 | script in the | ||
290 | Source Directory | ||
291 | . You can find the Yocto Project version of the | ||
292 | local.conf.sample | ||
293 | file in the | ||
294 | meta-poky/conf | ||
295 | directory. | ||
296 | |||
297 | .. _structure-build-conf-bblayers.conf: | ||
298 | |||
299 | ``build/conf/bblayers.conf`` | ||
300 | ---------------------------- | ||
301 | |||
302 | This configuration file defines | ||
303 | :ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`, | ||
304 | which are directory trees, traversed (or walked) by BitBake. The | ||
305 | ``bblayers.conf`` file uses the :term:`BBLAYERS` | ||
306 | variable to list the layers BitBake tries to find. | ||
307 | |||
308 | If ``bblayers.conf`` is not present when you start the build, the | ||
309 | OpenEmbedded build system creates it from ``bblayers.conf.sample`` when | ||
310 | you ``source`` the top-level build environment setup script (i.e. | ||
311 | :ref:`structure-core-script`). | ||
312 | |||
313 | As with the ``local.conf`` file, the source ``bblayers.conf.sample`` | ||
314 | file used depends on the ``$TEMPLATECONF`` script variable, which | ||
315 | defaults to ``meta-poky/conf/`` when you are building from the Yocto | ||
316 | Project development environment, and to ``meta/conf/`` when you are | ||
317 | building from the OpenEmbedded-Core environment. Because the script | ||
318 | variable points to the source of the ``bblayers.conf.sample`` file, this | ||
319 | implies that you can base your build from any layer by setting the | ||
320 | variable in the top-level build environment setup script as follows: | ||
321 | :: | ||
322 | |||
323 | TEMPLATECONF=your_layer/conf | ||
324 | |||
325 | Once the build process gets the sample file, it uses ``sed`` to substitute final | ||
326 | ``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values. | ||
327 | |||
328 | .. note:: | ||
329 | |||
330 | You can see how the | ||
331 | TEMPLATECONF | ||
332 | variable | ||
333 | scripts/oe-setup-builddir | ||
334 | script in the | ||
335 | Source Directory | ||
336 | . You can find the Yocto Project version of the | ||
337 | bblayers.conf.sample | ||
338 | file in the | ||
339 | meta-poky/conf/ | ||
340 | directory. | ||
341 | |||
342 | .. _structure-build-conf-sanity_info: | ||
343 | |||
344 | ``build/cache/sanity_info`` | ||
345 | --------------------------- | ||
346 | |||
347 | This file indicates the state of the sanity checks and is created during | ||
348 | the build. | ||
349 | |||
350 | .. _structure-build-downloads: | ||
351 | |||
352 | ``build/downloads/`` | ||
353 | -------------------- | ||
354 | |||
355 | This directory contains downloaded upstream source tarballs. You can | ||
356 | reuse the directory for multiple builds or move the directory to another | ||
357 | location. You can control the location of this directory through the | ||
358 | ``DL_DIR`` variable. | ||
359 | |||
360 | .. _structure-build-sstate-cache: | ||
361 | |||
362 | ``build/sstate-cache/`` | ||
363 | ----------------------- | ||
364 | |||
365 | This directory contains the shared state cache. You can reuse the | ||
366 | directory for multiple builds or move the directory to another location. | ||
367 | You can control the location of this directory through the | ||
368 | ``SSTATE_DIR`` variable. | ||
369 | |||
370 | .. _structure-build-tmp: | ||
371 | |||
372 | ``build/tmp/`` | ||
373 | -------------- | ||
374 | |||
375 | The OpenEmbedded build system creates and uses this directory for all | ||
376 | the build system's output. The :term:`TMPDIR` variable | ||
377 | points to this directory. | ||
378 | |||
379 | BitBake creates this directory if it does not exist. As a last resort, | ||
380 | to clean up a build and start it from scratch (other than the | ||
381 | downloads), you can remove everything in the ``tmp`` directory or get | ||
382 | rid of the directory completely. If you do, you should also completely | ||
383 | remove the ``build/sstate-cache`` directory. | ||
384 | |||
385 | .. _structure-build-tmp-buildstats: | ||
386 | |||
387 | ``build/tmp/buildstats/`` | ||
388 | ------------------------- | ||
389 | |||
390 | This directory stores the build statistics. | ||
391 | |||
392 | .. _structure-build-tmp-cache: | ||
393 | |||
394 | ``build/tmp/cache/`` | ||
395 | -------------------- | ||
396 | |||
397 | When BitBake parses the metadata (recipes and configuration files), it | ||
398 | caches the results in ``build/tmp/cache/`` to speed up future builds. | ||
399 | The results are stored on a per-machine basis. | ||
400 | |||
401 | During subsequent builds, BitBake checks each recipe (together with, for | ||
402 | example, any files included or appended to it) to see if they have been | ||
403 | modified. Changes can be detected, for example, through file | ||
404 | modification time (mtime) changes and hashing of file contents. If no | ||
405 | changes to the file are detected, then the parsed result stored in the | ||
406 | cache is reused. If the file has changed, it is reparsed. | ||
407 | |||
408 | .. _structure-build-tmp-deploy: | ||
409 | |||
410 | ``build/tmp/deploy/`` | ||
411 | --------------------- | ||
412 | |||
413 | This directory contains any "end result" output from the OpenEmbedded | ||
414 | build process. The :term:`DEPLOY_DIR` variable points | ||
415 | to this directory. For more detail on the contents of the ``deploy`` | ||
416 | directory, see the | ||
417 | ":ref:`images-dev-environment`" and | ||
418 | ":ref:`sdk-dev-environment`" sections in the Yocto | ||
419 | Project Overview and Concepts Manual. | ||
420 | |||
421 | .. _structure-build-tmp-deploy-deb: | ||
422 | |||
423 | ``build/tmp/deploy/deb/`` | ||
424 | ------------------------- | ||
425 | |||
426 | This directory receives any ``.deb`` packages produced by the build | ||
427 | process. The packages are sorted into feeds for different architecture | ||
428 | types. | ||
429 | |||
430 | .. _structure-build-tmp-deploy-rpm: | ||
431 | |||
432 | ``build/tmp/deploy/rpm/`` | ||
433 | ------------------------- | ||
434 | |||
435 | This directory receives any ``.rpm`` packages produced by the build | ||
436 | process. The packages are sorted into feeds for different architecture | ||
437 | types. | ||
438 | |||
439 | .. _structure-build-tmp-deploy-ipk: | ||
440 | |||
441 | ``build/tmp/deploy/ipk/`` | ||
442 | ------------------------- | ||
443 | |||
444 | This directory receives ``.ipk`` packages produced by the build process. | ||
445 | |||
446 | .. _structure-build-tmp-deploy-licenses: | ||
447 | |||
448 | ``build/tmp/deploy/licenses/`` | ||
449 | ------------------------------ | ||
450 | |||
451 | This directory receives package licensing information. For example, the | ||
452 | directory contains sub-directories for ``bash``, ``busybox``, and | ||
453 | ``glibc`` (among others) that in turn contain appropriate ``COPYING`` | ||
454 | license files with other licensing information. For information on | ||
455 | licensing, see the | ||
456 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`" | ||
457 | section in the Yocto Project Development Tasks Manual. | ||
458 | |||
459 | .. _structure-build-tmp-deploy-images: | ||
460 | |||
461 | ``build/tmp/deploy/images/`` | ||
462 | ---------------------------- | ||
463 | |||
464 | This directory is populated with the basic output objects of the build | ||
465 | (think of them as the "generated artifacts" of the build process), | ||
466 | including things like the boot loader image, kernel, root filesystem and | ||
467 | more. If you want to flash the resulting image from a build onto a | ||
468 | device, look here for the necessary components. | ||
469 | |||
470 | Be careful when deleting files in this directory. You can safely delete | ||
471 | old images from this directory (e.g. ``core-image-*``). However, the | ||
472 | kernel (``*zImage*``, ``*uImage*``, etc.), bootloader and other | ||
473 | supplementary files might be deployed here prior to building an image. | ||
474 | Because these files are not directly produced from the image, if you | ||
475 | delete them they will not be automatically re-created when you build the | ||
476 | image again. | ||
477 | |||
478 | If you do accidentally delete files here, you will need to force them to | ||
479 | be re-created. In order to do that, you will need to know the target | ||
480 | that produced them. For example, these commands rebuild and re-create | ||
481 | the kernel files: | ||
482 | :: | ||
483 | |||
484 | $ bitbake -c clean virtual/kernel | ||
485 | $ bitbake virtual/kernel | ||
486 | |||
487 | .. _structure-build-tmp-deploy-sdk: | ||
488 | |||
489 | ``build/tmp/deploy/sdk/`` | ||
490 | ------------------------- | ||
491 | |||
492 | The OpenEmbedded build system creates this directory to hold toolchain | ||
493 | installer scripts which, when executed, install the sysroot that matches | ||
494 | your target hardware. You can find out more about these installers in | ||
495 | the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`" | ||
496 | section in the Yocto Project Application Development and the Extensible | ||
497 | Software Development Kit (eSDK) manual. | ||
498 | |||
499 | .. _structure-build-tmp-sstate-control: | ||
500 | |||
501 | ``build/tmp/sstate-control/`` | ||
502 | ----------------------------- | ||
503 | |||
504 | The OpenEmbedded build system uses this directory for the shared state | ||
505 | manifest files. The shared state code uses these files to record the | ||
506 | files installed by each sstate task so that the files can be removed | ||
507 | when cleaning the recipe or when a newer version is about to be | ||
508 | installed. The build system also uses the manifests to detect and | ||
509 | produce a warning when files from one task are overwriting those from | ||
510 | another. | ||
511 | |||
512 | .. _structure-build-tmp-sysroots-components: | ||
513 | |||
514 | ``build/tmp/sysroots-components/`` | ||
515 | ---------------------------------- | ||
516 | |||
517 | This directory is the location of the sysroot contents that the task | ||
518 | :ref:`ref-tasks-prepare_recipe_sysroot` | ||
519 | links or copies into the recipe-specific sysroot for each recipe listed | ||
520 | in :term:`DEPENDS`. Population of this directory is | ||
521 | handled through shared state, while the path is specified by the | ||
522 | :term:`COMPONENTS_DIR` variable. Apart from a few | ||
523 | unusual circumstances, handling of the ``sysroots-components`` directory | ||
524 | should be automatic, and recipes should not directly reference | ||
525 | ``build/tmp/sysroots-components``. | ||
526 | |||
527 | .. _structure-build-tmp-sysroots: | ||
528 | |||
529 | ``build/tmp/sysroots/`` | ||
530 | ----------------------- | ||
531 | |||
532 | Previous versions of the OpenEmbedded build system used to create a | ||
533 | global shared sysroot per machine along with a native sysroot. Beginning | ||
534 | with the DISTRO version of the Yocto Project, sysroots exist in | ||
535 | recipe-specific :term:`WORKDIR` directories. Thus, the | ||
536 | ``build/tmp/sysroots/`` directory is unused. | ||
537 | |||
538 | .. note:: | ||
539 | |||
540 | The | ||
541 | build/tmp/sysroots/ | ||
542 | directory can still be populated using the | ||
543 | bitbake build-sysroots | ||
544 | command and can be used for compatibility in some cases. However, in | ||
545 | general it is not recommended to populate this directory. Individual | ||
546 | recipe-specific sysroots should be used. | ||
547 | |||
548 | .. _structure-build-tmp-stamps: | ||
549 | |||
550 | ``build/tmp/stamps/`` | ||
551 | --------------------- | ||
552 | |||
553 | This directory holds information that BitBake uses for accounting | ||
554 | purposes to track what tasks have run and when they have run. The | ||
555 | directory is sub-divided by architecture, package name, and version. | ||
556 | Following is an example: | ||
557 | stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do Although | ||
558 | the files in the directory are empty of data, BitBake uses the filenames | ||
559 | and timestamps for tracking purposes. | ||
560 | |||
561 | For information on how BitBake uses stamp files to determine if a task | ||
562 | should be rerun, see the | ||
563 | ":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`" | ||
564 | section in the Yocto Project Overview and Concepts Manual. | ||
565 | |||
566 | .. _structure-build-tmp-log: | ||
567 | |||
568 | ``build/tmp/log/`` | ||
569 | ------------------ | ||
570 | |||
571 | This directory contains general logs that are not otherwise placed using | ||
572 | the package's ``WORKDIR``. Examples of logs are the output from the | ||
573 | ``do_check_pkg`` or ``do_distro_check`` tasks. Running a build does not | ||
574 | necessarily mean this directory is created. | ||
575 | |||
576 | .. _structure-build-tmp-work: | ||
577 | |||
578 | ``build/tmp/work/`` | ||
579 | ------------------- | ||
580 | |||
581 | This directory contains architecture-specific work sub-directories for | ||
582 | packages built by BitBake. All tasks execute from the appropriate work | ||
583 | directory. For example, the source for a particular package is unpacked, | ||
584 | patched, configured and compiled all within its own work directory. | ||
585 | Within the work directory, organization is based on the package group | ||
586 | and version for which the source is being compiled as defined by the | ||
587 | :term:`WORKDIR`. | ||
588 | |||
589 | It is worth considering the structure of a typical work directory. As an | ||
590 | example, consider ``linux-yocto-kernel-3.0`` on the machine ``qemux86`` | ||
591 | built within the Yocto Project. For this package, a work directory of | ||
592 | ``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred | ||
593 | to as the ``WORKDIR``, is created. Within this directory, the source is | ||
594 | unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. | ||
595 | (See the ":ref:`using-a-quilt-workflow`" section in | ||
596 | the Yocto Project Development Tasks Manual for more information.) Within | ||
597 | the ``linux-qemux86-standard-build`` directory, standard Quilt | ||
598 | directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and | ||
599 | standard Quilt commands can be used. | ||
600 | |||
601 | There are other directories generated within ``WORKDIR``. The most | ||
602 | important directory is ``WORKDIR/temp/``, which has log files for each | ||
603 | task (``log.do_*.pid``) and contains the scripts BitBake runs for each | ||
604 | task (``run.do_*.pid``). The ``WORKDIR/image/`` directory is where "make | ||
605 | install" places its output that is then split into sub-packages within | ||
606 | ``WORKDIR/packages-split/``. | ||
607 | |||
608 | .. _structure-build-tmp-work-tunearch-recipename-version: | ||
609 | |||
610 | ``build/tmp/work/tunearch/recipename/version/`` | ||
611 | ----------------------------------------------- | ||
612 | |||
613 | The recipe work directory - ``${WORKDIR}``. | ||
614 | |||
615 | As described earlier in the | ||
616 | "```build/tmp/sysroots/`` <#structure-build-tmp-sysroots>`__" section, | ||
617 | beginning with the DISTRO release of the Yocto Project, the OpenEmbedded | ||
618 | build system builds each recipe in its own work directory (i.e. | ||
619 | :term:`WORKDIR`). The path to the work directory is | ||
620 | constructed using the architecture of the given build (e.g. | ||
621 | :term:`TUNE_PKGARCH`, | ||
622 | :term:`MACHINE_ARCH`, or "allarch"), the recipe | ||
623 | name, and the version of the recipe (i.e. | ||
624 | :term:`PE`\ ``:``\ :term:`PV`\ ``-``\ :term:`PR`). | ||
625 | |||
626 | A number of key subdirectories exist within each recipe work directory: | ||
627 | |||
628 | - ``${WORKDIR}/temp``: Contains the log files of each task executed for | ||
629 | this recipe, the "run" files for each executed task, which contain | ||
630 | the code run, and a ``log.task_order`` file, which lists the order in | ||
631 | which tasks were executed. | ||
632 | |||
633 | - ``${WORKDIR}/image``: Contains the output of the | ||
634 | :ref:`ref-tasks-install` task, which corresponds to | ||
635 | the ``${``\ :term:`D`\ ``}`` variable in that task. | ||
636 | |||
637 | - ``${WORKDIR}/pseudo``: Contains the pseudo database and log for any | ||
638 | tasks executed under pseudo for the recipe. | ||
639 | |||
640 | - ``${WORKDIR}/sysroot-destdir``: Contains the output of the | ||
641 | :ref:`ref-tasks-populate_sysroot` task. | ||
642 | |||
643 | - ``${WORKDIR}/package``: Contains the output of the | ||
644 | :ref:`ref-tasks-package` task before the output is | ||
645 | split into individual packages. | ||
646 | |||
647 | - ``${WORKDIR}/packages-split``: Contains the output of the | ||
648 | ``do_package`` task after the output has been split into individual | ||
649 | packages. Subdirectories exist for each individual package created by | ||
650 | the recipe. | ||
651 | |||
652 | - ``${WORKDIR}/recipe-sysroot``: A directory populated with the target | ||
653 | dependencies of the recipe. This directory looks like the target | ||
654 | filesystem and contains libraries that the recipe might need to link | ||
655 | against (e.g. the C library). | ||
656 | |||
657 | - ``${WORKDIR}/recipe-sysroot-native``: A directory populated with the | ||
658 | native dependencies of the recipe. This directory contains the tools | ||
659 | the recipe needs to build (e.g. the compiler, Autoconf, libtool, and | ||
660 | so forth). | ||
661 | |||
662 | - ``${WORKDIR}/build``: This subdirectory applies only to recipes that | ||
663 | support builds where the source is separate from the build artifacts. | ||
664 | The OpenEmbedded build system uses this directory as a separate build | ||
665 | directory (i.e. ``${``\ :term:`B`\ ``}``). | ||
666 | |||
667 | .. _structure-build-work-shared: | ||
668 | |||
669 | ``build/tmp/work-shared/`` | ||
670 | -------------------------- | ||
671 | |||
672 | For efficiency, the OpenEmbedded build system creates and uses this | ||
673 | directory to hold recipes that share a work directory with other | ||
674 | recipes. In practice, this is only used for ``gcc`` and its variants | ||
675 | (e.g. ``gcc-cross``, ``libgcc``, ``gcc-runtime``, and so forth). | ||
676 | |||
677 | .. _structure-meta: | ||
678 | |||
679 | The Metadata - ``meta/`` | ||
680 | ======================== | ||
681 | |||
682 | As mentioned previously, :term:`Metadata` is the core of the | ||
683 | Yocto Project. Metadata has several important subdivisions: | ||
684 | |||
685 | .. _structure-meta-classes: | ||
686 | |||
687 | ``meta/classes/`` | ||
688 | ----------------- | ||
689 | |||
690 | This directory contains the ``*.bbclass`` files. Class files are used to | ||
691 | abstract common code so it can be reused by multiple packages. Every | ||
692 | package inherits the ``base.bbclass`` file. Examples of other important | ||
693 | classes are ``autotools.bbclass``, which in theory allows any | ||
694 | Autotool-enabled package to work with the Yocto Project with minimal | ||
695 | effort. Another example is ``kernel.bbclass`` that contains common code | ||
696 | and functions for working with the Linux kernel. Functions like image | ||
697 | generation or packaging also have their specific class files such as | ||
698 | ``image.bbclass``, ``rootfs_*.bbclass`` and ``package*.bbclass``. | ||
699 | |||
700 | For reference information on classes, see the | ||
701 | ":ref:`ref-manual/ref-classes:Classes`" chapter. | ||
702 | |||
703 | .. _structure-meta-conf: | ||
704 | |||
705 | ``meta/conf/`` | ||
706 | -------------- | ||
707 | |||
708 | This directory contains the core set of configuration files that start | ||
709 | from ``bitbake.conf`` and from which all other configuration files are | ||
710 | included. See the include statements at the end of the ``bitbake.conf`` | ||
711 | file and you will note that even ``local.conf`` is loaded from there. | ||
712 | While ``bitbake.conf`` sets up the defaults, you can often override | ||
713 | these by using the (``local.conf``) file, machine file or the | ||
714 | distribution configuration file. | ||
715 | |||
716 | .. _structure-meta-conf-machine: | ||
717 | |||
718 | ``meta/conf/machine/`` | ||
719 | ---------------------- | ||
720 | |||
721 | This directory contains all the machine configuration files. If you set | ||
722 | ``MACHINE = "qemux86"``, the OpenEmbedded build system looks for a | ||
723 | ``qemux86.conf`` file in this directory. The ``include`` directory | ||
724 | contains various data common to multiple machines. If you want to add | ||
725 | support for a new machine to the Yocto Project, look in this directory. | ||
726 | |||
727 | .. _structure-meta-conf-distro: | ||
728 | |||
729 | ``meta/conf/distro/`` | ||
730 | --------------------- | ||
731 | |||
732 | The contents of this directory controls any distribution-specific | ||
733 | configurations. For the Yocto Project, the ``defaultsetup.conf`` is the | ||
734 | main file here. This directory includes the versions and the ``SRCDATE`` | ||
735 | definitions for applications that are configured here. An example of an | ||
736 | alternative configuration might be ``poky-bleeding.conf``. Although this | ||
737 | file mainly inherits its configuration from Poky. | ||
738 | |||
739 | .. _structure-meta-conf-machine-sdk: | ||
740 | |||
741 | ``meta/conf/machine-sdk/`` | ||
742 | -------------------------- | ||
743 | |||
744 | The OpenEmbedded build system searches this directory for configuration | ||
745 | files that correspond to the value of | ||
746 | :term:`SDKMACHINE`. By default, 32-bit and 64-bit x86 | ||
747 | files ship with the Yocto Project that support some SDK hosts. However, | ||
748 | it is possible to extend that support to other SDK hosts by adding | ||
749 | additional configuration files in this subdirectory within another | ||
750 | layer. | ||
751 | |||
752 | .. _structure-meta-files: | ||
753 | |||
754 | ``meta/files/`` | ||
755 | --------------- | ||
756 | |||
757 | This directory contains common license files and several text files used | ||
758 | by the build system. The text files contain minimal device information | ||
759 | and lists of files and directories with known permissions. | ||
760 | |||
761 | .. _structure-meta-lib: | ||
762 | |||
763 | ``meta/lib/`` | ||
764 | ------------- | ||
765 | |||
766 | This directory contains OpenEmbedded Python library code used during the | ||
767 | build process. | ||
768 | |||
769 | .. _structure-meta-recipes-bsp: | ||
770 | |||
771 | ``meta/recipes-bsp/`` | ||
772 | --------------------- | ||
773 | |||
774 | This directory contains anything linking to specific hardware or | ||
775 | hardware configuration information such as "u-boot" and "grub". | ||
776 | |||
777 | .. _structure-meta-recipes-connectivity: | ||
778 | |||
779 | ``meta/recipes-connectivity/`` | ||
780 | ------------------------------ | ||
781 | |||
782 | This directory contains libraries and applications related to | ||
783 | communication with other devices. | ||
784 | |||
785 | .. _structure-meta-recipes-core: | ||
786 | |||
787 | ``meta/recipes-core/`` | ||
788 | ---------------------- | ||
789 | |||
790 | This directory contains what is needed to build a basic working Linux | ||
791 | image including commonly used dependencies. | ||
792 | |||
793 | .. _structure-meta-recipes-devtools: | ||
794 | |||
795 | ``meta/recipes-devtools/`` | ||
796 | -------------------------- | ||
797 | |||
798 | This directory contains tools that are primarily used by the build | ||
799 | system. The tools, however, can also be used on targets. | ||
800 | |||
801 | .. _structure-meta-recipes-extended: | ||
802 | |||
803 | ``meta/recipes-extended/`` | ||
804 | -------------------------- | ||
805 | |||
806 | This directory contains non-essential applications that add features | ||
807 | compared to the alternatives in core. You might need this directory for | ||
808 | full tool functionality or for Linux Standard Base (LSB) compliance. | ||
809 | |||
810 | .. _structure-meta-recipes-gnome: | ||
811 | |||
812 | ``meta/recipes-gnome/`` | ||
813 | ----------------------- | ||
814 | |||
815 | This directory contains all things related to the GTK+ application | ||
816 | framework. | ||
817 | |||
818 | .. _structure-meta-recipes-graphics: | ||
819 | |||
820 | ``meta/recipes-graphics/`` | ||
821 | -------------------------- | ||
822 | |||
823 | This directory contains X and other graphically related system | ||
824 | libraries. | ||
825 | |||
826 | .. _structure-meta-recipes-kernel: | ||
827 | |||
828 | ``meta/recipes-kernel/`` | ||
829 | ------------------------ | ||
830 | |||
831 | This directory contains the kernel and generic applications and | ||
832 | libraries that have strong kernel dependencies. | ||
833 | |||
834 | .. _structure-meta-recipes-lsb4: | ||
835 | |||
836 | ``meta/recipes-lsb4/`` | ||
837 | ---------------------- | ||
838 | |||
839 | This directory contains recipes specifically added to support the Linux | ||
840 | Standard Base (LSB) version 4.x. | ||
841 | |||
842 | .. _structure-meta-recipes-multimedia: | ||
843 | |||
844 | ``meta/recipes-multimedia/`` | ||
845 | ---------------------------- | ||
846 | |||
847 | This directory contains codecs and support utilities for audio, images | ||
848 | and video. | ||
849 | |||
850 | .. _structure-meta-recipes-rt: | ||
851 | |||
852 | ``meta/recipes-rt/`` | ||
853 | -------------------- | ||
854 | |||
855 | This directory contains package and image recipes for using and testing | ||
856 | the ``PREEMPT_RT`` kernel. | ||
857 | |||
858 | .. _structure-meta-recipes-sato: | ||
859 | |||
860 | ``meta/recipes-sato/`` | ||
861 | ---------------------- | ||
862 | |||
863 | This directory contains the Sato demo/reference UI/UX and its associated | ||
864 | applications and configuration data. | ||
865 | |||
866 | .. _structure-meta-recipes-support: | ||
867 | |||
868 | ``meta/recipes-support/`` | ||
869 | ------------------------- | ||
870 | |||
871 | This directory contains recipes used by other recipes, but that are not | ||
872 | directly included in images (i.e. dependencies of other recipes). | ||
873 | |||
874 | .. _structure-meta-site: | ||
875 | |||
876 | ``meta/site/`` | ||
877 | -------------- | ||
878 | |||
879 | This directory contains a list of cached results for various | ||
880 | architectures. Because certain "autoconf" test results cannot be | ||
881 | determined when cross-compiling due to the tests not able to run on a | ||
882 | live system, the information in this directory is passed to "autoconf" | ||
883 | for the various architectures. | ||
884 | |||
885 | .. _structure-meta-recipes-txt: | ||
886 | |||
887 | ``meta/recipes.txt`` | ||
888 | -------------------- | ||
889 | |||
890 | This file is a description of the contents of ``recipes-*``. | ||
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml index 27f17dd919..8588e9c2dd 100644 --- a/documentation/ref-manual/ref-structure.xml +++ b/documentation/ref-manual/ref-structure.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-structure'> | 6 | <chapter id='ref-structure'> |
6 | 7 | ||
diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css index 7077e4b70d..622ceb8f7e 100644 --- a/documentation/ref-manual/ref-style.css +++ b/documentation/ref-manual/ref-style.css | |||
@@ -1,4 +1,7 @@ | |||
1 | /* | 1 | /* |
2 | |||
3 | SPDX-License-Identifier: CC-BY-2.0-UK | ||
4 | |||
2 | Generic XHTML / DocBook XHTML CSS Stylesheet. | 5 | Generic XHTML / DocBook XHTML CSS Stylesheet. |
3 | 6 | ||
4 | Browser wrangling and typographic design by | 7 | Browser wrangling and typographic design by |
diff --git a/documentation/ref-manual/ref-system-requirements.rst b/documentation/ref-manual/ref-system-requirements.rst new file mode 100644 index 0000000000..56218e4ebb --- /dev/null +++ b/documentation/ref-manual/ref-system-requirements.rst | |||
@@ -0,0 +1,437 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******************* | ||
4 | System Requirements | ||
5 | ******************* | ||
6 | |||
7 | Welcome to the Yocto Project Reference Manual! This manual provides | ||
8 | reference information for the current release of the Yocto Project, and | ||
9 | is most effectively used after you have an understanding of the basics | ||
10 | of the Yocto Project. The manual is neither meant to be read as a | ||
11 | starting point to the Yocto Project, nor read from start to finish. | ||
12 | Rather, use this manual to find variable definitions, class | ||
13 | descriptions, and so forth as needed during the course of using the | ||
14 | Yocto Project. | ||
15 | |||
16 | For introductory information on the Yocto Project, see the | ||
17 | :yocto_home:`Yocto Project Website <>` and the | ||
18 | ":ref:`overview-manual/overview-manual-development-environment:the yocto project development environment`" | ||
19 | chapter in the Yocto Project Overview and Concepts Manual. | ||
20 | |||
21 | If you want to use the Yocto Project to quickly build an image without | ||
22 | having to understand concepts, work through the | ||
23 | :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. You can find "how-to" | ||
24 | information in the :doc:`../dev-manual/dev-manual`. You can find Yocto Project overview | ||
25 | and conceptual information in the :doc:`../overview-manual/overview-manual`. | ||
26 | |||
27 | .. note:: | ||
28 | |||
29 | For more information about the Yocto Project Documentation set, see | ||
30 | the " | ||
31 | Links and Related Documentation | ||
32 | " section. | ||
33 | |||
34 | .. _detailed-supported-distros: | ||
35 | |||
36 | Supported Linux Distributions | ||
37 | ============================= | ||
38 | |||
39 | Currently, the Yocto Project is supported on the following | ||
40 | distributions: | ||
41 | |||
42 | - Ubuntu 16.04 (LTS) | ||
43 | |||
44 | - Ubuntu 18.04 (LTS) | ||
45 | |||
46 | - Ubuntu 20.04 | ||
47 | |||
48 | - Fedora 30 | ||
49 | |||
50 | - Fedora 31 | ||
51 | |||
52 | - Fedora 32 | ||
53 | |||
54 | - CentOS 7.x | ||
55 | |||
56 | - CentOS 8.x | ||
57 | |||
58 | - Debian GNU/Linux 8.x (Jessie) | ||
59 | |||
60 | - Debian GNU/Linux 9.x (Stretch) | ||
61 | |||
62 | - Debian GNU/Linux 10.x (Buster) | ||
63 | |||
64 | - OpenSUSE Leap 15.1 | ||
65 | |||
66 | |||
67 | .. note:: | ||
68 | |||
69 | - While the Yocto Project Team attempts to ensure all Yocto Project | ||
70 | releases are one hundred percent compatible with each officially | ||
71 | supported Linux distribution, instances might exist where you | ||
72 | encounter a problem while using the Yocto Project on a specific | ||
73 | distribution. | ||
74 | |||
75 | - Yocto Project releases are tested against the stable Linux | ||
76 | distributions in the above list. The Yocto Project should work | ||
77 | on other distributions but validation is not performed against | ||
78 | them. | ||
79 | |||
80 | - In particular, the Yocto Project does not support and currently | ||
81 | has no plans to support rolling-releases or development | ||
82 | distributions due to their constantly changing nature. We welcome | ||
83 | patches and bug reports, but keep in mind that our priority is on | ||
84 | the supported platforms listed below. | ||
85 | |||
86 | - You may use Windows Subsystem For Linux v2 to set up a build host | ||
87 | using Windows 10, but validation is not performed against build | ||
88 | hosts using WSLv2. | ||
89 | |||
90 | - The Yocto Project is not compatible with WSLv1, it is | ||
91 | compatible but not officially supported nor validated with | ||
92 | WSLv2, if you still decide to use WSL please upgrade to WSLv2. | ||
93 | |||
94 | - If you encounter problems, please go to `Yocto Project | ||
95 | Bugzilla <http://bugzilla.yoctoproject.org>`__ and submit a bug. We are | ||
96 | interested in hearing about your experience. For information on | ||
97 | how to submit a bug, see the Yocto Project | ||
98 | :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>` | ||
99 | and the ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`" | ||
100 | section in the Yocto Project Development Tasks Manual. | ||
101 | |||
102 | |||
103 | Required Packages for the Build Host | ||
104 | ==================================== | ||
105 | |||
106 | The list of packages you need on the host development system can be | ||
107 | large when covering all build scenarios using the Yocto Project. This | ||
108 | section describes required packages according to Linux distribution and | ||
109 | function. | ||
110 | |||
111 | .. _ubuntu-packages: | ||
112 | |||
113 | Ubuntu and Debian | ||
114 | ----------------- | ||
115 | |||
116 | The following list shows the required packages by function given a | ||
117 | supported Ubuntu or Debian Linux distribution: | ||
118 | |||
119 | .. note:: | ||
120 | |||
121 | - If your build system has the ``oss4-dev`` package installed, you | ||
122 | might experience QEMU build failures due to the package installing | ||
123 | its own custom ``/usr/include/linux/soundcard.h`` on the Debian | ||
124 | system. If you run into this situation, either of the following | ||
125 | solutions exist: | ||
126 | :: | ||
127 | |||
128 | $ sudo apt-get build-dep qemu | ||
129 | $ sudo apt-get remove oss4-dev | ||
130 | |||
131 | - For Debian-8, ``python3-git`` and ``pylint3`` are no longer | ||
132 | available via ``apt-get``. | ||
133 | :: | ||
134 | |||
135 | $ sudo pip3 install GitPython pylint==1.9.5 | ||
136 | |||
137 | - *Essentials:* Packages needed to build an image on a headless system: | ||
138 | :: | ||
139 | |||
140 | $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; | ||
141 | |||
142 | - *Documentation:* Packages needed if you are going to build out the | ||
143 | Yocto Project documentation manuals: | ||
144 | :: | ||
145 | |||
146 | $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto | ||
147 | |||
148 | Fedora Packages | ||
149 | --------------- | ||
150 | |||
151 | The following list shows the required packages by function given a | ||
152 | supported Fedora Linux distribution: | ||
153 | |||
154 | - *Essentials:* Packages needed to build an image for a headless | ||
155 | system: | ||
156 | :: | ||
157 | |||
158 | $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; | ||
159 | |||
160 | - *Documentation:* Packages needed if you are going to build out the | ||
161 | Yocto Project documentation manuals: | ||
162 | :: | ||
163 | |||
164 | $ sudo dnf install docbook-style-dsssl docbook-style-xsl \ | ||
165 | docbook-dtds docbook-utils fop libxslt dblatex xmlto | ||
166 | |||
167 | openSUSE Packages | ||
168 | ----------------- | ||
169 | |||
170 | The following list shows the required packages by function given a | ||
171 | supported openSUSE Linux distribution: | ||
172 | |||
173 | - *Essentials:* Packages needed to build an image for a headless | ||
174 | system: | ||
175 | :: | ||
176 | |||
177 | $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; | ||
178 | |||
179 | - *Documentation:* Packages needed if you are going to build out the | ||
180 | Yocto Project documentation manuals: $ sudo zypper install dblatex | ||
181 | xmlto | ||
182 | |||
183 | CentOS-7 Packages | ||
184 | ----------------- | ||
185 | |||
186 | The following list shows the required packages by function given a | ||
187 | supported CentOS-7 Linux distribution: | ||
188 | |||
189 | - *Essentials:* Packages needed to build an image for a headless | ||
190 | system: | ||
191 | :: | ||
192 | |||
193 | $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL; | ||
194 | |||
195 | .. note:: | ||
196 | |||
197 | - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is | ||
198 | a collection of packages from Fedora built on RHEL/CentOS for | ||
199 | easy installation of packages not included in enterprise Linux | ||
200 | by default. You need to install these packages separately. | ||
201 | |||
202 | - The ``makecache`` command consumes additional Metadata from | ||
203 | ``epel-release``. | ||
204 | |||
205 | - *Documentation:* Packages needed if you are going to build out the | ||
206 | Yocto Project documentation manuals: | ||
207 | :: | ||
208 | |||
209 | $ sudo yum install docbook-style-dsssl docbook-style-xsl \ | ||
210 | docbook-dtds docbook-utils fop libxslt dblatex xmlto | ||
211 | |||
212 | CentOS-8 Packages | ||
213 | ----------------- | ||
214 | |||
215 | The following list shows the required packages by function given a | ||
216 | supported CentOS-8 Linux distribution: | ||
217 | |||
218 | - *Essentials:* Packages needed to build an image for a headless | ||
219 | system: | ||
220 | :: | ||
221 | |||
222 | $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL; | ||
223 | |||
224 | .. note:: | ||
225 | |||
226 | - Extra Packages for Enterprise Linux (i.e. ``epel-release``) is | ||
227 | a collection of packages from Fedora built on RHEL/CentOS for | ||
228 | easy installation of packages not included in enterprise Linux | ||
229 | by default. You need to install these packages separately. | ||
230 | |||
231 | - The ``PowerTools`` repo provides additional packages such as | ||
232 | ``rpcgen`` and ``texinfo``. | ||
233 | |||
234 | - The ``makecache`` command consumes additional Metadata from | ||
235 | ``epel-release``. | ||
236 | |||
237 | - *Documentation:* Packages needed if you are going to build out the | ||
238 | Yocto Project documentation manuals: | ||
239 | :: | ||
240 | |||
241 | $ sudo dnf install docbook-style-dsssl docbook-style-xsl \\ | ||
242 | docbook-dtds docbook-utils fop libxslt dblatex xmlto | ||
243 | |||
244 | Required Git, tar, Python and gcc Versions | ||
245 | ========================================== | ||
246 | |||
247 | In order to use the build system, your host development system must meet | ||
248 | the following version requirements for Git, tar, and Python: | ||
249 | |||
250 | - Git 1.8.3.1 or greater | ||
251 | |||
252 | - tar 1.28 or greater | ||
253 | |||
254 | - Python 3.5.0 or greater | ||
255 | |||
256 | If your host development system does not meet all these requirements, | ||
257 | you can resolve this by installing a ``buildtools`` tarball that | ||
258 | contains these tools. You can get the tarball one of two ways: download | ||
259 | a pre-built tarball or use BitBake to build the tarball. | ||
260 | |||
261 | In addition, your host development system must meet the following | ||
262 | version requirement for gcc: | ||
263 | |||
264 | - gcc 5.0 or greater | ||
265 | |||
266 | If your host development system does not meet this requirement, you can | ||
267 | resolve this by installing a ``buildtools-extended`` tarball that | ||
268 | contains additional tools, the equivalent of ``buildtools-essential``. | ||
269 | |||
270 | Installing a Pre-Built ``buildtools`` Tarball with ``install-buildtools`` script | ||
271 | -------------------------------------------------------------------------------- | ||
272 | |||
273 | The ``install-buildtools`` script is the easiest of the three methods by | ||
274 | which you can get these tools. It downloads a pre-built buildtools | ||
275 | installer and automatically installs the tools for you: | ||
276 | |||
277 | 1. Execute the ``install-buildtools`` script. Here is an example: | ||
278 | :: | ||
279 | |||
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; | ||
285 | |||
286 | During execution, the buildtools tarball will be downloaded, the | ||
287 | checksum of the download will be verified, the installer will be run | ||
288 | for you, and some basic checks will be run to to make sure the | ||
289 | installation is functional. | ||
290 | |||
291 | To avoid the need of ``sudo`` privileges, the ``install-buildtools`` | ||
292 | script will by default tell the installer to install in: | ||
293 | :: | ||
294 | |||
295 | /path/to/poky/buildtools | ||
296 | |||
297 | If your host development system needs the additional tools provided | ||
298 | in the ``buildtools-extended`` tarball, you can instead execute the | ||
299 | ``install-buildtools`` script with the default parameters: | ||
300 | :: | ||
301 | |||
302 | $ cd poky | ||
303 | $ scripts/install-buildtools | ||
304 | |||
305 | 2. Source the tools environment setup script by using a command like the | ||
306 | following: | ||
307 | :: | ||
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 | ||
312 | use the right file (i.e. i586 or x86_64). | ||
313 | |||
314 | After you have sourced the setup script, the tools are added to | ||
315 | ``PATH`` and any other environment variables required to run the | ||
316 | tools are initialized. The results are working versions versions of | ||
317 | Git, tar, Python and ``chrpath``. And in the case of the | ||
318 | ``buildtools-extended`` tarball, additional working versions of tools | ||
319 | including ``gcc``, ``make`` and the other tools included in | ||
320 | ``packagegroup-core-buildessential``. | ||
321 | |||
322 | Downloading a Pre-Built ``buildtools`` Tarball | ||
323 | ---------------------------------------------- | ||
324 | |||
325 | Downloading and running a pre-built buildtools installer is the easiest | ||
326 | of the two methods by which you can get these tools: | ||
327 | |||
328 | 1. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/ | ||
329 | |||
330 | 2. Execute the installation script. Here is an example for the | ||
331 | traditional installer: | ||
332 | :: | ||
333 | |||
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 | |||
341 | During execution, a prompt appears that allows you to choose the | ||
342 | installation directory. For example, you could choose the following: | ||
343 | /home/your-username/buildtools | ||
344 | |||
345 | 3. Source the tools environment setup script by using a command like the | ||
346 | following: | ||
347 | :: | ||
348 | |||
349 | $ source /home/your_username/buildtools/environment-setup-i586-poky-linux | ||
350 | |||
351 | Of | ||
352 | course, you need to supply your installation directory and be sure to | ||
353 | use the right file (i.e. i585 or x86-64). | ||
354 | |||
355 | After you have sourced the setup script, the tools are added to | ||
356 | ``PATH`` and any other environment variables required to run the | ||
357 | tools are initialized. The results are working versions versions of | ||
358 | Git, tar, Python and ``chrpath``. And in the case of the | ||
359 | ``buildtools-extended`` tarball, additional working versions of tools | ||
360 | including ``gcc``, ``make`` and the other tools included in | ||
361 | ``packagegroup-core-buildessential``. | ||
362 | |||
363 | Building Your Own ``buildtools`` Tarball | ||
364 | ---------------------------------------- | ||
365 | |||
366 | Building and running your own buildtools installer applies only when you | ||
367 | have a build host that can already run BitBake. In this case, you use | ||
368 | that machine to build the ``.sh`` file and then take steps to transfer | ||
369 | and run it on a machine that does not meet the minimal Git, tar, and | ||
370 | Python (or gcc) requirements. | ||
371 | |||
372 | Here are the steps to take to build and run your own buildtools | ||
373 | installer: | ||
374 | |||
375 | 1. On the machine that is able to run BitBake, be sure you have set up | ||
376 | your build environment with the setup script | ||
377 | (:ref:`structure-core-script`). | ||
378 | |||
379 | 2. Run the BitBake command to build the tarball: | ||
380 | :: | ||
381 | |||
382 | $ bitbake buildtools-tarball | ||
383 | |||
384 | or run the BitBake command to build the extended tarball: | ||
385 | :: | ||
386 | |||
387 | $ bitbake buildtools-extended-tarball | ||
388 | |||
389 | .. note:: | ||
390 | |||
391 | The | ||
392 | SDKMACHINE | ||
393 | variable in your | ||
394 | local.conf | ||
395 | file determines whether you build tools for a 32-bit or 64-bit | ||
396 | system. | ||
397 | |||
398 | Once the build completes, you can find the ``.sh`` file that installs | ||
399 | the tools in the ``tmp/deploy/sdk`` subdirectory of the | ||
400 | :term:`Build Directory`. The installer file has the string | ||
401 | "buildtools" (or "buildtools-extended") in the name. | ||
402 | |||
403 | 3. Transfer the ``.sh`` file from the build host to the machine that | ||
404 | does not meet the Git, tar, or Python (or gcc) requirements. | ||
405 | |||
406 | 4. On the machine that does not meet the requirements, run the ``.sh`` | ||
407 | file to install the tools. Here is an example for the traditional | ||
408 | installer: | ||
409 | :: | ||
410 | |||
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 | |||
418 | During execution, a prompt appears that allows you to choose the | ||
419 | installation directory. For example, you could choose the following: | ||
420 | /home/your_username/buildtools | ||
421 | |||
422 | 5. Source the tools environment setup script by using a command like the | ||
423 | following: | ||
424 | :: | ||
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 | ||
429 | use the right file (i.e. i586 or x86_64). | ||
430 | |||
431 | After you have sourced the setup script, the tools are added to | ||
432 | ``PATH`` and any other environment variables required to run the | ||
433 | tools are initialized. The results are working versions versions of | ||
434 | Git, tar, Python and ``chrpath``. And in the case of the | ||
435 | ``buildtools-extended`` tarball, additional working versions of tools | ||
436 | including ``gcc``, ``make`` and the other tools included in | ||
437 | ``packagegroup-core-buildessential``. | ||
diff --git a/documentation/ref-manual/ref-system-requirements.xml b/documentation/ref-manual/ref-system-requirements.xml index c6e1eb9716..ac8b0032db 100644 --- a/documentation/ref-manual/ref-system-requirements.xml +++ b/documentation/ref-manual/ref-system-requirements.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-manual-system-requirements'> | 6 | <chapter id='ref-manual-system-requirements'> |
6 | <title>System Requirements</title> | 7 | <title>System Requirements</title> |
@@ -93,14 +94,12 @@ | |||
93 | <itemizedlist> | 94 | <itemizedlist> |
94 | <listitem><para>Ubuntu 16.04 (LTS)</para></listitem> | 95 | <listitem><para>Ubuntu 16.04 (LTS)</para></listitem> |
95 | <listitem><para>Ubuntu 18.04 (LTS)</para></listitem> | 96 | <listitem><para>Ubuntu 18.04 (LTS)</para></listitem> |
96 | <listitem><para>Ubuntu 19.04</para></listitem> | ||
97 | <listitem><para>Ubuntu 20.04</para></listitem> | 97 | <listitem><para>Ubuntu 20.04</para></listitem> |
98 | <listitem><para>Fedora 28</para></listitem> | ||
99 | <listitem><para>Fedora 29</para></listitem> | ||
100 | <listitem><para>Fedora 30</para></listitem> | 98 | <listitem><para>Fedora 30</para></listitem> |
101 | <listitem><para>Fedora 31</para></listitem> | 99 | <listitem><para>Fedora 31</para></listitem> |
102 | <listitem><para>Fedora 32</para></listitem> | 100 | <listitem><para>Fedora 32</para></listitem> |
103 | <listitem><para>CentOS 7.x</para></listitem> | 101 | <listitem><para>CentOS 7.x</para></listitem> |
102 | <listitem><para>CentOS 8.x</para></listitem> | ||
104 | <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem> | 103 | <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem> |
105 | <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem> | 104 | <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem> |
106 | <listitem><para>Debian GNU/Linux 10.x (Buster)</para></listitem> | 105 | <listitem><para>Debian GNU/Linux 10.x (Buster)</para></listitem> |
diff --git a/documentation/ref-manual/ref-tasks.rst b/documentation/ref-manual/ref-tasks.rst new file mode 100644 index 0000000000..dcdff05dce --- /dev/null +++ b/documentation/ref-manual/ref-tasks.rst | |||
@@ -0,0 +1,875 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ***** | ||
4 | Tasks | ||
5 | ***** | ||
6 | |||
7 | Tasks are units of execution for BitBake. Recipes (``.bb`` files) use | ||
8 | tasks to complete configuring, compiling, and packaging software. This | ||
9 | chapter provides a reference of the tasks defined in the OpenEmbedded | ||
10 | build system. | ||
11 | |||
12 | Normal Recipe Build Tasks | ||
13 | ========================= | ||
14 | |||
15 | The following sections describe normal tasks associated with building a | ||
16 | recipe. For more information on tasks and dependencies, see the | ||
17 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | ||
18 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | ||
19 | BitBake User Manual. | ||
20 | |||
21 | .. _ref-tasks-build: | ||
22 | |||
23 | ``do_build`` | ||
24 | ------------ | ||
25 | |||
26 | The default task for all recipes. This task depends on all other normal | ||
27 | tasks required to build a recipe. | ||
28 | |||
29 | .. _ref-tasks-compile: | ||
30 | |||
31 | ``do_compile`` | ||
32 | -------------- | ||
33 | |||
34 | Compiles the source code. This task runs with the current working | ||
35 | directory set to ``${``\ :term:`B`\ ``}``. | ||
36 | |||
37 | The default behavior of this task is to run the ``oe_runmake`` function | ||
38 | if a makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found. | ||
39 | If no such file is found, the ``do_compile`` task does nothing. | ||
40 | |||
41 | .. _ref-tasks-compile_ptest_base: | ||
42 | |||
43 | ``do_compile_ptest_base`` | ||
44 | ------------------------- | ||
45 | |||
46 | Compiles the runtime test suite included in the software being built. | ||
47 | |||
48 | .. _ref-tasks-configure: | ||
49 | |||
50 | ``do_configure`` | ||
51 | ---------------- | ||
52 | |||
53 | Configures the source by enabling and disabling any build-time and | ||
54 | configuration options for the software being built. The task runs with | ||
55 | the current working directory set to ``${``\ :term:`B`\ ``}``. | ||
56 | |||
57 | The default behavior of this task is to run ``oe_runmake clean`` if a | ||
58 | makefile (``Makefile``, ``makefile``, or ``GNUmakefile``) is found and | ||
59 | :term:`CLEANBROKEN` is not set to "1". If no such | ||
60 | file is found or the ``CLEANBROKEN`` variable is set to "1", the | ||
61 | ``do_configure`` task does nothing. | ||
62 | |||
63 | .. _ref-tasks-configure_ptest_base: | ||
64 | |||
65 | ``do_configure_ptest_base`` | ||
66 | --------------------------- | ||
67 | |||
68 | Configures the runtime test suite included in the software being built. | ||
69 | |||
70 | .. _ref-tasks-deploy: | ||
71 | |||
72 | ``do_deploy`` | ||
73 | ------------- | ||
74 | |||
75 | Writes output files that are to be deployed to | ||
76 | ``${``\ :term:`DEPLOY_DIR_IMAGE`\ ``}``. The | ||
77 | task runs with the current working directory set to | ||
78 | ``${``\ :term:`B`\ ``}``. | ||
79 | |||
80 | Recipes implementing this task should inherit the | ||
81 | :ref:`deploy <ref-classes-deploy>` class and should write the output | ||
82 | to ``${``\ :term:`DEPLOYDIR`\ ``}``, which is not to be | ||
83 | confused with ``${DEPLOY_DIR}``. The ``deploy`` class sets up | ||
84 | ``do_deploy`` as a shared state (sstate) task that can be accelerated | ||
85 | through sstate use. The sstate mechanism takes care of copying the | ||
86 | output from ``${DEPLOYDIR}`` to ``${DEPLOY_DIR_IMAGE}``. | ||
87 | |||
88 | .. note:: | ||
89 | |||
90 | Do not write the output directly to | ||
91 | ${DEPLOY_DIR_IMAGE} | ||
92 | , as this causes the sstate mechanism to malfunction. | ||
93 | |||
94 | The ``do_deploy`` task is not added as a task by default and | ||
95 | consequently needs to be added manually. If you want the task to run | ||
96 | after :ref:`ref-tasks-compile`, you can add it by doing | ||
97 | the following: addtask deploy after do_compile Adding ``do_deploy`` | ||
98 | after other tasks works the same way. | ||
99 | |||
100 | .. note:: | ||
101 | |||
102 | You do not need to add | ||
103 | before do_build | ||
104 | to the | ||
105 | addtask | ||
106 | command (though it is harmless), because the | ||
107 | base | ||
108 | class contains the following: | ||
109 | :: | ||
110 | |||
111 | do_build[recrdeptask] += "do_deploy" | ||
112 | |||
113 | |||
114 | See the " | ||
115 | Dependencies | ||
116 | " section in the BitBake User Manual for more information. | ||
117 | |||
118 | If the ``do_deploy`` task re-executes, any previous output is removed | ||
119 | (i.e. "cleaned"). | ||
120 | |||
121 | .. _ref-tasks-fetch: | ||
122 | |||
123 | ``do_fetch`` | ||
124 | ------------ | ||
125 | |||
126 | Fetches the source code. This task uses the | ||
127 | :term:`SRC_URI` variable and the argument's prefix to | ||
128 | determine the correct :ref:`fetcher <bitbake:bb-fetchers>` | ||
129 | module. | ||
130 | |||
131 | .. _ref-tasks-image: | ||
132 | |||
133 | ``do_image`` | ||
134 | ------------ | ||
135 | |||
136 | Starts the image generation process. The ``do_image`` task runs after | ||
137 | the OpenEmbedded build system has run the | ||
138 | :ref:`ref-tasks-rootfs` task during which packages are | ||
139 | identified for installation into the image and the root filesystem is | ||
140 | created, complete with post-processing. | ||
141 | |||
142 | The ``do_image`` task performs pre-processing on the image through the | ||
143 | :term:`IMAGE_PREPROCESS_COMMAND` and | ||
144 | dynamically generates supporting ``do_image_*`` tasks as needed. | ||
145 | |||
146 | For more information on image creation, see the ":ref:`image-generation-dev-environment`" | ||
147 | section in the Yocto Project Overview and Concepts Manual. | ||
148 | |||
149 | .. _ref-tasks-image-complete: | ||
150 | |||
151 | ``do_image_complete`` | ||
152 | --------------------- | ||
153 | |||
154 | Completes the image generation process. The ``do_image_complete`` task | ||
155 | runs after the OpenEmbedded build system has run the | ||
156 | :ref:`ref-tasks-image` task during which image | ||
157 | pre-processing occurs and through dynamically generated ``do_image_*`` | ||
158 | tasks the image is constructed. | ||
159 | |||
160 | The ``do_image_complete`` task performs post-processing on the image | ||
161 | through the | ||
162 | :term:`IMAGE_POSTPROCESS_COMMAND`. | ||
163 | |||
164 | For more information on image creation, see the | ||
165 | ":ref:`image-generation-dev-environment`" | ||
166 | section in the Yocto Project Overview and Concepts Manual. | ||
167 | |||
168 | .. _ref-tasks-install: | ||
169 | |||
170 | ``do_install`` | ||
171 | -------------- | ||
172 | |||
173 | Copies files that are to be packaged into the holding area | ||
174 | ``${``\ :term:`D`\ ``}``. This task runs with the current | ||
175 | working directory set to ``${``\ :term:`B`\ ``}``, which is the | ||
176 | compilation directory. The ``do_install`` task, as well as other tasks | ||
177 | that either directly or indirectly depend on the installed files (e.g. | ||
178 | :ref:`ref-tasks-package`, ``do_package_write_*``, and | ||
179 | :ref:`ref-tasks-rootfs`), run under | ||
180 | :ref:`fakeroot <overview-manual/overview-manual-concepts:fakeroot and pseudo>`. | ||
181 | |||
182 | .. note:: | ||
183 | |||
184 | When installing files, be careful not to set the owner and group IDs | ||
185 | of the installed files to unintended values. Some methods of copying | ||
186 | files, notably when using the recursive ``cp`` command, can preserve | ||
187 | the UID and/or GID of the original file, which is usually not what | ||
188 | you want. The ``host-user-contaminated`` QA check checks for files | ||
189 | that probably have the wrong ownership. | ||
190 | |||
191 | Safe methods for installing files include the following: | ||
192 | |||
193 | - The ``install`` utility. This utility is the preferred method. | ||
194 | |||
195 | - The ``cp`` command with the "--no-preserve=ownership" option. | ||
196 | |||
197 | - The ``tar`` command with the "--no-same-owner" option. See the | ||
198 | ``bin_package.bbclass`` file in the ``meta/classes`` directory of | ||
199 | the :term:`Source Directory` for an example. | ||
200 | |||
201 | .. _ref-tasks-install_ptest_base: | ||
202 | |||
203 | ``do_install_ptest_base`` | ||
204 | ------------------------- | ||
205 | |||
206 | Copies the runtime test suite files from the compilation directory to a | ||
207 | holding area. | ||
208 | |||
209 | .. _ref-tasks-package: | ||
210 | |||
211 | ``do_package`` | ||
212 | -------------- | ||
213 | |||
214 | Analyzes the content of the holding area | ||
215 | ``${``\ :term:`D`\ ``}`` and splits the content into subsets | ||
216 | based on available packages and files. This task makes use of the | ||
217 | :term:`PACKAGES` and :term:`FILES` | ||
218 | variables. | ||
219 | |||
220 | The ``do_package`` task, in conjunction with the | ||
221 | :ref:`ref-tasks-packagedata` task, also saves some | ||
222 | important package metadata. For additional information, see the | ||
223 | :term:`PKGDESTWORK` variable and the | ||
224 | ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" | ||
225 | section in the Yocto Project Overview and Concepts Manual. | ||
226 | |||
227 | .. _ref-tasks-package_qa: | ||
228 | |||
229 | ``do_package_qa`` | ||
230 | ----------------- | ||
231 | |||
232 | Runs QA checks on packaged files. For more information on these checks, | ||
233 | see the :ref:`insane <ref-classes-insane>` class. | ||
234 | |||
235 | .. _ref-tasks-package_write_deb: | ||
236 | |||
237 | ``do_package_write_deb`` | ||
238 | ------------------------ | ||
239 | |||
240 | Creates Debian packages (i.e. ``*.deb`` files) and places them in the | ||
241 | ``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory in | ||
242 | the package feeds area. For more information, see the | ||
243 | ":ref:`package-feeds-dev-environment`" section in | ||
244 | the Yocto Project Overview and Concepts Manual. | ||
245 | |||
246 | .. _ref-tasks-package_write_ipk: | ||
247 | |||
248 | ``do_package_write_ipk`` | ||
249 | ------------------------ | ||
250 | |||
251 | Creates IPK packages (i.e. ``*.ipk`` files) and places them in the | ||
252 | ``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory in | ||
253 | the package feeds area. For more information, see the | ||
254 | ":ref:`package-feeds-dev-environment`" section in | ||
255 | the Yocto Project Overview and Concepts Manual. | ||
256 | |||
257 | .. _ref-tasks-package_write_rpm: | ||
258 | |||
259 | ``do_package_write_rpm`` | ||
260 | ------------------------ | ||
261 | |||
262 | Creates RPM packages (i.e. ``*.rpm`` files) and places them in the | ||
263 | ``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory in | ||
264 | the package feeds area. For more information, see the | ||
265 | ":ref:`package-feeds-dev-environment`" section in | ||
266 | the Yocto Project Overview and Concepts Manual. | ||
267 | |||
268 | .. _ref-tasks-package_write_tar: | ||
269 | |||
270 | ``do_package_write_tar`` | ||
271 | ------------------------ | ||
272 | |||
273 | Creates tarballs and places them in the | ||
274 | ``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in | ||
275 | the package feeds area. For more information, see the | ||
276 | ":ref:`package-feeds-dev-environment`" section in | ||
277 | the Yocto Project Overview and Concepts Manual. | ||
278 | |||
279 | .. _ref-tasks-packagedata: | ||
280 | |||
281 | ``do_packagedata`` | ||
282 | ------------------ | ||
283 | |||
284 | Saves package metadata generated by the | ||
285 | :ref:`ref-tasks-package` task in | ||
286 | :term:`PKGDATA_DIR` to make it available globally. | ||
287 | |||
288 | .. _ref-tasks-patch: | ||
289 | |||
290 | ``do_patch`` | ||
291 | ------------ | ||
292 | |||
293 | Locates patch files and applies them to the source code. | ||
294 | |||
295 | After fetching and unpacking source files, the build system uses the | ||
296 | recipe's :term:`SRC_URI` statements | ||
297 | to locate and apply patch files to the source code. | ||
298 | |||
299 | .. note:: | ||
300 | |||
301 | The build system uses the | ||
302 | FILESPATH | ||
303 | variable to determine the default set of directories when searching | ||
304 | for patches. | ||
305 | |||
306 | Patch files, by default, are ``*.patch`` and ``*.diff`` files created | ||
307 | and kept in a subdirectory of the directory holding the recipe file. For | ||
308 | example, consider the | ||
309 | :yocto_git:`bluez5 </cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5>` | ||
310 | recipe from the OE-Core layer (i.e. ``poky/meta``): | ||
311 | :: | ||
312 | |||
313 | poky/meta/recipes-connectivity/bluez5 | ||
314 | |||
315 | This recipe has two patch files located here: | ||
316 | :: | ||
317 | |||
318 | poky/meta/recipes-connectivity/bluez5/bluez5 | ||
319 | |||
320 | In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source | ||
321 | and patch files needed to build the package. | ||
322 | |||
323 | .. note:: | ||
324 | |||
325 | In the case for the | ||
326 | bluez5_5.48.bb | ||
327 | recipe, the | ||
328 | SRC_URI | ||
329 | statements are from an include file | ||
330 | bluez5.inc | ||
331 | . | ||
332 | |||
333 | As mentioned earlier, the build system treats files whose file types are | ||
334 | ``.patch`` and ``.diff`` as patch files. However, you can use the | ||
335 | "apply=yes" parameter with the ``SRC_URI`` statement to indicate any | ||
336 | file as a patch file: | ||
337 | :: | ||
338 | |||
339 | SRC_URI = " \\ | ||
340 | git://path_to_repo/some_package \\ | ||
341 | file://file;apply=yes \\ | ||
342 | " | ||
343 | |||
344 | Conversely, if you have a directory full of patch files and you want to | ||
345 | exclude some so that the ``do_patch`` task does not apply them during | ||
346 | the patch phase, you can use the "apply=no" parameter with the | ||
347 | ``SRC_URI`` statement: | ||
348 | :: | ||
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 | |||
356 | In the | ||
357 | previous example, assuming all the files in the directory holding the | ||
358 | patch files end with either ``.patch`` or ``.diff``, every file would be | ||
359 | applied as a patch by default except for the patch_file5 patch. | ||
360 | |||
361 | You can find out more about the patching process in the | ||
362 | ":ref:`patching-dev-environment`" section in | ||
363 | the Yocto Project Overview and Concepts Manual and the | ||
364 | ":ref:`new-recipe-patching-code`" section in the | ||
365 | Yocto Project Development Tasks Manual. | ||
366 | |||
367 | .. _ref-tasks-populate_lic: | ||
368 | |||
369 | ``do_populate_lic`` | ||
370 | ------------------- | ||
371 | |||
372 | Writes license information for the recipe that is collected later when | ||
373 | the image is constructed. | ||
374 | |||
375 | .. _ref-tasks-populate_sdk: | ||
376 | |||
377 | ``do_populate_sdk`` | ||
378 | ------------------- | ||
379 | |||
380 | Creates the file and directory structure for an installable SDK. See the | ||
381 | ":ref:`sdk-generation-dev-environment`" | ||
382 | section in the Yocto Project Overview and Concepts Manual for more | ||
383 | information. | ||
384 | |||
385 | .. _ref-tasks-populate_sdk_ext: | ||
386 | |||
387 | ``do_populate_sdk_ext`` | ||
388 | ----------------------- | ||
389 | |||
390 | Creates the file and directory structure for an installable extensible | ||
391 | SDK (eSDK). See the ":ref:`sdk-generation-dev-environment`" | ||
392 | section in the Yocto Project Overview and Concepts Manual for more | ||
393 | information. | ||
394 | |||
395 | |||
396 | .. _ref-tasks-populate_sysroot: | ||
397 | |||
398 | ``do_populate_sysroot`` | ||
399 | ----------------------- | ||
400 | |||
401 | Stages (copies) a subset of the files installed by the | ||
402 | :ref:`ref-tasks-install` task into the appropriate | ||
403 | sysroot. For information on how to access these files from other | ||
404 | recipes, see the :term:`STAGING_DIR* <STAGING_DIR_HOST>` variables. | ||
405 | Directories that would typically not be needed by other recipes at build | ||
406 | time (e.g. ``/etc``) are not copied by default. | ||
407 | |||
408 | For information on what directories are copied by default, see the | ||
409 | :term:`SYSROOT_DIRS* <SYSROOT_DIRS>` variables. You can change | ||
410 | these variables inside your recipe if you need to make additional (or | ||
411 | fewer) directories available to other recipes at build time. | ||
412 | |||
413 | The ``do_populate_sysroot`` task is a shared state (sstate) task, which | ||
414 | means that the task can be accelerated through sstate use. Realize also | ||
415 | that if the task is re-executed, any previous output is removed (i.e. | ||
416 | "cleaned"). | ||
417 | |||
418 | .. _ref-tasks-prepare_recipe_sysroot: | ||
419 | |||
420 | ``do_prepare_recipe_sysroot`` | ||
421 | ----------------------------- | ||
422 | |||
423 | Installs the files into the individual recipe specific sysroots (i.e. | ||
424 | ``recipe-sysroot`` and ``recipe-sysroot-native`` under | ||
425 | ``${``\ :term:`WORKDIR`\ ``}`` based upon the | ||
426 | dependencies specified by :term:`DEPENDS`). See the | ||
427 | ":ref:`staging <ref-classes-staging>`" class for more information. | ||
428 | |||
429 | .. _ref-tasks-rm_work: | ||
430 | |||
431 | ``do_rm_work`` | ||
432 | -------------- | ||
433 | |||
434 | Removes work files after the OpenEmbedded build system has finished with | ||
435 | them. You can learn more by looking at the | ||
436 | ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section. | ||
437 | |||
438 | .. _ref-tasks-unpack: | ||
439 | |||
440 | ``do_unpack`` | ||
441 | ------------- | ||
442 | |||
443 | Unpacks the source code into a working directory pointed to by | ||
444 | ``${``\ :term:`WORKDIR`\ ``}``. The :term:`S` | ||
445 | variable also plays a role in where unpacked source files ultimately | ||
446 | reside. For more information on how source files are unpacked, see the | ||
447 | ":ref:`source-fetching-dev-environment`" | ||
448 | section in the Yocto Project Overview and Concepts Manual and also see | ||
449 | the ``WORKDIR`` and ``S`` variable descriptions. | ||
450 | |||
451 | Manually Called Tasks | ||
452 | ===================== | ||
453 | |||
454 | These tasks are typically manually triggered (e.g. by using the | ||
455 | ``bitbake -c`` command-line option): | ||
456 | |||
457 | .. _ref-tasks-checkpkg: | ||
458 | |||
459 | ``do_checkpkg`` | ||
460 | --------------- | ||
461 | |||
462 | Provides information about the recipe including its upstream version and | ||
463 | status. The upstream version and status reveals whether or not a version | ||
464 | of the recipe exists upstream and a status of not updated, updated, or | ||
465 | unknown. | ||
466 | |||
467 | To check the upstream version and status of a recipe, use the following | ||
468 | devtool commands: | ||
469 | :: | ||
470 | |||
471 | $ devtool latest-version | ||
472 | $ devtool check-upgrade-status | ||
473 | |||
474 | See the ":ref:`ref-manual/ref-devtool-reference:\`\`devtool\`\` quick reference`" | ||
475 | chapter for more information on | ||
476 | ``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" | ||
477 | section for information on checking the upgrade status of a recipe. | ||
478 | |||
479 | To build the ``checkpkg`` task, use the ``bitbake`` command with the | ||
480 | "-c" option and task name: | ||
481 | :: | ||
482 | |||
483 | $ bitbake core-image-minimal -c checkpkg | ||
484 | |||
485 | By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g. | ||
486 | ``$BUILD_DIR/tmp/log``). | ||
487 | |||
488 | .. _ref-tasks-checkuri: | ||
489 | |||
490 | ``do_checkuri`` | ||
491 | --------------- | ||
492 | |||
493 | Validates the :term:`SRC_URI` value. | ||
494 | |||
495 | .. _ref-tasks-clean: | ||
496 | |||
497 | ``do_clean`` | ||
498 | ------------ | ||
499 | |||
500 | Removes all output files for a target from the | ||
501 | :ref:`ref-tasks-unpack` task forward (i.e. ``do_unpack``, | ||
502 | :ref:`ref-tasks-configure`, | ||
503 | :ref:`ref-tasks-compile`, | ||
504 | :ref:`ref-tasks-install`, and | ||
505 | :ref:`ref-tasks-package`). | ||
506 | |||
507 | You can run this task using BitBake as follows: | ||
508 | :: | ||
509 | |||
510 | $ bitbake -c clean recipe | ||
511 | |||
512 | Running this task does not remove the | ||
513 | :ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>` cache files. | ||
514 | Consequently, if no changes have been made and the recipe is rebuilt | ||
515 | after cleaning, output files are simply restored from the sstate cache. | ||
516 | If you want to remove the sstate cache files for the recipe, you need to | ||
517 | use the :ref:`ref-tasks-cleansstate` task instead | ||
518 | (i.e. ``bitbake -c cleansstate`` recipe). | ||
519 | |||
520 | .. _ref-tasks-cleanall: | ||
521 | |||
522 | ``do_cleanall`` | ||
523 | --------------- | ||
524 | |||
525 | Removes all output files, shared state | ||
526 | (:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache, and | ||
527 | downloaded source files for a target (i.e. the contents of | ||
528 | :term:`DL_DIR`). Essentially, the ``do_cleanall`` task is | ||
529 | identical to the :ref:`ref-tasks-cleansstate` task | ||
530 | with the added removal of downloaded source files. | ||
531 | |||
532 | You can run this task using BitBake as follows: | ||
533 | :: | ||
534 | |||
535 | $ bitbake -c cleanall recipe | ||
536 | |||
537 | Typically, you would not normally use the ``cleanall`` task. Do so only | ||
538 | if you want to start fresh with the :ref:`ref-tasks-fetch` | ||
539 | task. | ||
540 | |||
541 | .. _ref-tasks-cleansstate: | ||
542 | |||
543 | ``do_cleansstate`` | ||
544 | ------------------ | ||
545 | |||
546 | Removes all output files and shared state | ||
547 | (:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache for a | ||
548 | target. Essentially, the ``do_cleansstate`` task is identical to the | ||
549 | :ref:`ref-tasks-clean` task with the added removal of | ||
550 | shared state (`:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) | ||
551 | cache. | ||
552 | |||
553 | You can run this task using BitBake as follows: | ||
554 | :: | ||
555 | |||
556 | $ bitbake -c cleansstate recipe | ||
557 | |||
558 | When you run the ``do_cleansstate`` task, the OpenEmbedded build system | ||
559 | no longer uses any sstate. Consequently, building the recipe from | ||
560 | scratch is guaranteed. | ||
561 | |||
562 | .. note:: | ||
563 | |||
564 | The | ||
565 | do_cleansstate | ||
566 | task cannot remove sstate from a remote sstate mirror. If you need to | ||
567 | build a target from scratch using remote mirrors, use the "-f" option | ||
568 | as follows: | ||
569 | :: | ||
570 | |||
571 | $ bitbake -f -c do_cleansstate target | ||
572 | |||
573 | |||
574 | .. _ref-tasks-devpyshell: | ||
575 | |||
576 | ``do_devpyshell`` | ||
577 | ----------------- | ||
578 | |||
579 | Starts a shell in which an interactive Python interpreter allows you to | ||
580 | interact with the BitBake build environment. From within this shell, you | ||
581 | can directly examine and set bits from the data store and execute | ||
582 | functions as if within the BitBake environment. See the ":ref:`platdev-appdev-devpyshell`" section in | ||
583 | the Yocto Project Development Tasks Manual for more information about | ||
584 | using ``devpyshell``. | ||
585 | |||
586 | .. _ref-tasks-devshell: | ||
587 | |||
588 | ``do_devshell`` | ||
589 | --------------- | ||
590 | |||
591 | Starts a shell whose environment is set up for development, debugging, | ||
592 | or both. See the ":ref:`platdev-appdev-devshell`" section in the | ||
593 | Yocto Project Development Tasks Manual for more information about using | ||
594 | ``devshell``. | ||
595 | |||
596 | .. _ref-tasks-listtasks: | ||
597 | |||
598 | ``do_listtasks`` | ||
599 | ---------------- | ||
600 | |||
601 | Lists all defined tasks for a target. | ||
602 | |||
603 | .. _ref-tasks-package_index: | ||
604 | |||
605 | ``do_package_index`` | ||
606 | -------------------- | ||
607 | |||
608 | Creates or updates the index in the `:ref:`package-feeds-dev-environment` area. | ||
609 | |||
610 | .. note:: | ||
611 | |||
612 | This task is not triggered with the | ||
613 | bitbake -c | ||
614 | command-line option as are the other tasks in this section. Because | ||
615 | this task is specifically for the | ||
616 | package-index | ||
617 | recipe, you run it using | ||
618 | bitbake package-index | ||
619 | . | ||
620 | |||
621 | Image-Related Tasks | ||
622 | =================== | ||
623 | |||
624 | The following tasks are applicable to image recipes. | ||
625 | |||
626 | .. _ref-tasks-bootimg: | ||
627 | |||
628 | ``do_bootimg`` | ||
629 | -------------- | ||
630 | |||
631 | Creates a bootable live image. See the | ||
632 | :term:`IMAGE_FSTYPES` variable for additional | ||
633 | information on live image types. | ||
634 | |||
635 | .. _ref-tasks-bundle_initramfs: | ||
636 | |||
637 | ``do_bundle_initramfs`` | ||
638 | ----------------------- | ||
639 | |||
640 | Combines an initial RAM disk (initramfs) image and kernel together to | ||
641 | form a single image. The | ||
642 | :term:`CONFIG_INITRAMFS_SOURCE` variable | ||
643 | has some more information about these types of images. | ||
644 | |||
645 | .. _ref-tasks-rootfs: | ||
646 | |||
647 | ``do_rootfs`` | ||
648 | ------------- | ||
649 | |||
650 | Creates the root filesystem (file and directory structure) for an image. | ||
651 | See the ":ref:`image-generation-dev-environment`" | ||
652 | section in the Yocto Project Overview and Concepts Manual for more | ||
653 | information on how the root filesystem is created. | ||
654 | |||
655 | .. _ref-tasks-testimage: | ||
656 | |||
657 | ``do_testimage`` | ||
658 | ---------------- | ||
659 | |||
660 | Boots an image and performs runtime tests within the image. For | ||
661 | information on automatically testing images, see the | ||
662 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
663 | section in the Yocto Project Development Tasks Manual. | ||
664 | |||
665 | .. _ref-tasks-testimage_auto: | ||
666 | |||
667 | ``do_testimage_auto`` | ||
668 | --------------------- | ||
669 | |||
670 | Boots an image and performs runtime tests within the image immediately | ||
671 | after it has been built. This task is enabled when you set | ||
672 | :term:`TESTIMAGE_AUTO` equal to "1". | ||
673 | |||
674 | For information on automatically testing images, see the | ||
675 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
676 | section in the Yocto Project Development Tasks Manual. | ||
677 | |||
678 | Kernel-Related Tasks | ||
679 | ==================== | ||
680 | |||
681 | The following tasks are applicable to kernel recipes. Some of these | ||
682 | tasks (e.g. the :ref:`ref-tasks-menuconfig` task) are | ||
683 | also applicable to recipes that use Linux kernel style configuration | ||
684 | such as the BusyBox recipe. | ||
685 | |||
686 | .. _ref-tasks-compile_kernelmodules: | ||
687 | |||
688 | ``do_compile_kernelmodules`` | ||
689 | ---------------------------- | ||
690 | |||
691 | Runs the step that builds the kernel modules (if needed). Building a | ||
692 | kernel consists of two steps: 1) the kernel (``vmlinux``) is built, and | ||
693 | 2) the modules are built (i.e. ``make modules``). | ||
694 | |||
695 | .. _ref-tasks-diffconfig: | ||
696 | |||
697 | ``do_diffconfig`` | ||
698 | ----------------- | ||
699 | |||
700 | When invoked by the user, this task creates a file containing the | ||
701 | differences between the original config as produced by | ||
702 | :ref:`ref-tasks-kernel_configme` task and the | ||
703 | changes made by the user with other methods (i.e. using | ||
704 | (:ref:`ref-tasks-kernel_menuconfig`). Once the | ||
705 | file of differences is created, it can be used to create a config | ||
706 | fragment that only contains the differences. You can invoke this task | ||
707 | from the command line as follows: | ||
708 | :: | ||
709 | |||
710 | $ bitbake linux-yocto -c diffconfig | ||
711 | |||
712 | For more information, see the | ||
713 | ":ref:`kernel-dev/kernel-dev-common:creating configuration fragments`" | ||
714 | section in the Yocto Project Linux Kernel Development Manual. | ||
715 | |||
716 | .. _ref-tasks-kernel_checkout: | ||
717 | |||
718 | ``do_kernel_checkout`` | ||
719 | ---------------------- | ||
720 | |||
721 | Converts the newly unpacked kernel source into a form with which the | ||
722 | OpenEmbedded build system can work. Because the kernel source can be | ||
723 | fetched in several different ways, the ``do_kernel_checkout`` task makes | ||
724 | sure that subsequent tasks are given a clean working tree copy of the | ||
725 | kernel with the correct branches checked out. | ||
726 | |||
727 | .. _ref-tasks-kernel_configcheck: | ||
728 | |||
729 | ``do_kernel_configcheck`` | ||
730 | ------------------------- | ||
731 | |||
732 | Validates the configuration produced by the | ||
733 | :ref:`ref-tasks-kernel_menuconfig` task. The | ||
734 | ``do_kernel_configcheck`` task produces warnings when a requested | ||
735 | configuration does not appear in the final ``.config`` file or when you | ||
736 | override a policy configuration in a hardware configuration fragment. | ||
737 | You can run this task explicitly and view the output by using the | ||
738 | following command: | ||
739 | :: | ||
740 | |||
741 | $ bitbake linux-yocto -c kernel_configcheck -f | ||
742 | |||
743 | For more information, see the | ||
744 | ":ref:`kernel-dev/kernel-dev-common:validating configuration`" | ||
745 | section in the Yocto Project Linux Kernel Development Manual. | ||
746 | |||
747 | .. _ref-tasks-kernel_configme: | ||
748 | |||
749 | ``do_kernel_configme`` | ||
750 | ---------------------- | ||
751 | |||
752 | After the kernel is patched by the :ref:`ref-tasks-patch` | ||
753 | task, the ``do_kernel_configme`` task assembles and merges all the | ||
754 | kernel config fragments into a merged configuration that can then be | ||
755 | passed to the kernel configuration phase proper. This is also the time | ||
756 | during which user-specified defconfigs are applied if present, and where | ||
757 | configuration modes such as ``--allnoconfig`` are applied. | ||
758 | |||
759 | .. _ref-tasks-kernel_menuconfig: | ||
760 | |||
761 | ``do_kernel_menuconfig`` | ||
762 | ------------------------ | ||
763 | |||
764 | Invoked by the user to manipulate the ``.config`` file used to build a | ||
765 | linux-yocto recipe. This task starts the Linux kernel configuration | ||
766 | tool, which you then use to modify the kernel configuration. | ||
767 | |||
768 | .. note:: | ||
769 | |||
770 | You can also invoke this tool from the command line as follows: | ||
771 | :: | ||
772 | |||
773 | $ bitbake linux-yocto -c menuconfig | ||
774 | |||
775 | |||
776 | See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" | ||
777 | section in the Yocto Project Linux Kernel Development Manual for more | ||
778 | information on this configuration tool. | ||
779 | |||
780 | .. _ref-tasks-kernel_metadata: | ||
781 | |||
782 | ``do_kernel_metadata`` | ||
783 | ---------------------- | ||
784 | |||
785 | Collects all the features required for a given kernel build, whether the | ||
786 | features come from :term:`SRC_URI` or from Git | ||
787 | repositories. After collection, the ``do_kernel_metadata`` task | ||
788 | processes the features into a series of config fragments and patches, | ||
789 | which can then be applied by subsequent tasks such as | ||
790 | :ref:`ref-tasks-patch` and | ||
791 | :ref:`ref-tasks-kernel_configme`. | ||
792 | |||
793 | .. _ref-tasks-menuconfig: | ||
794 | |||
795 | ``do_menuconfig`` | ||
796 | ----------------- | ||
797 | |||
798 | Runs ``make menuconfig`` for the kernel. For information on | ||
799 | ``menuconfig``, see the | ||
800 | ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``" | ||
801 | section in the Yocto Project Linux Kernel Development Manual. | ||
802 | |||
803 | .. _ref-tasks-savedefconfig: | ||
804 | |||
805 | ``do_savedefconfig`` | ||
806 | -------------------- | ||
807 | |||
808 | When invoked by the user, creates a defconfig file that can be used | ||
809 | instead of the default defconfig. The saved defconfig contains the | ||
810 | differences between the default defconfig and the changes made by the | ||
811 | user using other methods (i.e. the | ||
812 | :ref:`ref-tasks-kernel_menuconfig` task. You | ||
813 | can invoke the task using the following command: | ||
814 | :: | ||
815 | |||
816 | $ bitbake linux-yocto -c savedefconfig | ||
817 | |||
818 | .. _ref-tasks-shared_workdir: | ||
819 | |||
820 | ``do_shared_workdir`` | ||
821 | --------------------- | ||
822 | |||
823 | After the kernel has been compiled but before the kernel modules have | ||
824 | been compiled, this task copies files required for module builds and | ||
825 | which are generated from the kernel build into the shared work | ||
826 | directory. With these copies successfully copied, the | ||
827 | :ref:`ref-tasks-compile_kernelmodules` task | ||
828 | can successfully build the kernel modules in the next step of the build. | ||
829 | |||
830 | .. _ref-tasks-sizecheck: | ||
831 | |||
832 | ``do_sizecheck`` | ||
833 | ---------------- | ||
834 | |||
835 | After the kernel has been built, this task checks the size of the | ||
836 | stripped kernel image against | ||
837 | :term:`KERNEL_IMAGE_MAXSIZE`. If that | ||
838 | variable was set and the size of the stripped kernel exceeds that size, | ||
839 | the kernel build produces a warning to that effect. | ||
840 | |||
841 | .. _ref-tasks-strip: | ||
842 | |||
843 | ``do_strip`` | ||
844 | ------------ | ||
845 | |||
846 | If ``KERNEL_IMAGE_STRIP_EXTRA_SECTIONS`` is defined, this task strips | ||
847 | the sections named in that variable from ``vmlinux``. This stripping is | ||
848 | typically used to remove nonessential sections such as ``.comment`` | ||
849 | sections from a size-sensitive configuration. | ||
850 | |||
851 | .. _ref-tasks-validate_branches: | ||
852 | |||
853 | ``do_validate_branches`` | ||
854 | ------------------------ | ||
855 | |||
856 | After the kernel is unpacked but before it is patched, this task makes | ||
857 | sure that the machine and metadata branches as specified by the | ||
858 | :term:`SRCREV` variables actually exist on the specified | ||
859 | branches. If these branches do not exist and | ||
860 | :term:`AUTOREV` is not being used, the | ||
861 | ``do_validate_branches`` task fails during the build. | ||
862 | |||
863 | Miscellaneous Tasks | ||
864 | =================== | ||
865 | |||
866 | The following sections describe miscellaneous tasks. | ||
867 | |||
868 | .. _ref-tasks-spdx: | ||
869 | |||
870 | ``do_spdx`` | ||
871 | ----------- | ||
872 | |||
873 | A build stage that takes the source code and scans it on a remote | ||
874 | FOSSOLOGY server in order to produce an SPDX document. This task applies | ||
875 | only to the :ref:`spdx <ref-classes-spdx>` class. | ||
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index 011e0d7496..5b09b3f2e8 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-tasks'> | 6 | <chapter id='ref-tasks'> |
6 | <title>Tasks</title> | 7 | <title>Tasks</title> |
diff --git a/documentation/ref-manual/ref-terms.rst b/documentation/ref-manual/ref-terms.rst new file mode 100644 index 0000000000..600cc23c3e --- /dev/null +++ b/documentation/ref-manual/ref-terms.rst | |||
@@ -0,0 +1,397 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ******************* | ||
4 | Yocto Project Terms | ||
5 | ******************* | ||
6 | |||
7 | Following is a list of terms and definitions users new to the Yocto Project | ||
8 | development environment might find helpful. While some of these terms are | ||
9 | universal, the list includes them just in case: | ||
10 | |||
11 | .. glossary:: | ||
12 | |||
13 | Append Files | ||
14 | Files that append build information to a recipe file. Append files are | ||
15 | known as BitBake append files and ``.bbappend`` files. The OpenEmbedded | ||
16 | build system expects every append file to have a corresponding recipe | ||
17 | (``.bb``) file. Furthermore, the append file and corresponding recipe file | ||
18 | must use the same root filename. The filenames can differ only in the | ||
19 | file type suffix used (e.g. ``formfactor_0.0.bb`` and | ||
20 | ``formfactor_0.0.bbappend``). | ||
21 | |||
22 | Information in append files extends or overrides the information in the | ||
23 | similarly-named recipe file. For an example of an append file in use, see | ||
24 | the ":ref:`dev-manual/dev-manual-common-tasks:Using .bbappend Files in | ||
25 | Your Layer`" section in the Yocto Project Development Tasks Manual. | ||
26 | |||
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 | ||
29 | append file named as follows: | ||
30 | :: | ||
31 | |||
32 | busybox_1.21.%.bbappend | ||
33 | |||
34 | That append file | ||
35 | would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, | ||
36 | the append file would match any of the following recipe names: | ||
37 | |||
38 | .. code-block:: shell | ||
39 | |||
40 | busybox_1.21.1.bb | ||
41 | busybox_1.21.2.bb | ||
42 | busybox_1.21.3.bb | ||
43 | busybox_1.21.10.bb | ||
44 | busybox_1.21.25.bb | ||
45 | |||
46 | .. note:: | ||
47 | |||
48 | The use of the " % " character is limited in that it only works | ||
49 | directly in front of the .bbappend portion of the append file's | ||
50 | name. You cannot use the wildcard character in any other location of | ||
51 | the name. | ||
52 | |||
53 | BitBake | ||
54 | The task executor and scheduler used by the OpenEmbedded build system to | ||
55 | build images. For more information on BitBake, see the :doc:`BitBake User | ||
56 | Manual <bitbake:index>`. | ||
57 | |||
58 | Board Support Package (BSP) | ||
59 | A group of drivers, definitions, and other components that provide support | ||
60 | for a specific hardware configuration. For more information on BSPs, see | ||
61 | the :ref:`bsp-guide/bsp-guide:Yocto Project Board Support Package | ||
62 | Developer's Guide`. | ||
63 | |||
64 | Build Directory | ||
65 | This term refers to the area used by the OpenEmbedded build system for | ||
66 | builds. The area is created when you ``source`` the setup environment | ||
67 | script that is found in the Source Directory | ||
68 | (i.e. :ref:`ref-manual/ref-structure:\`\`oe-init-build-env\`\``). The | ||
69 | :term:`TOPDIR` variable points to the Build Directory. | ||
70 | |||
71 | You have a lot of flexibility when creating the Build Directory. | ||
72 | Following are some examples that show how to create the directory. The | ||
73 | examples assume your :term:`Source Directory` is named ``poky``: | ||
74 | |||
75 | - Create the Build Directory inside your Source Directory and let | ||
76 | the name of the Build Directory default to ``build``: | ||
77 | |||
78 | .. code-block:: shell | ||
79 | |||
80 | $ cd $HOME/poky | ||
81 | $ source oe-init-build-env | ||
82 | |||
83 | - Create the Build Directory inside your home directory and | ||
84 | specifically name it ``test-builds``: | ||
85 | |||
86 | .. code-block:: shell | ||
87 | |||
88 | $ cd $HOME | ||
89 | $ source poky/oe-init-build-env test-builds | ||
90 | |||
91 | - Provide a directory path and specifically name the Build | ||
92 | Directory. Any intermediate folders in the pathname must exist. | ||
93 | This next example creates a Build Directory named | ||
94 | ``YP-POKYVERSION`` in your home directory within the existing | ||
95 | directory ``mybuilds``: | ||
96 | |||
97 | .. code-block:: shell | ||
98 | |||
99 | $ cd $HOME | ||
100 | $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION | ||
101 | |||
102 | .. note:: | ||
103 | |||
104 | By default, the Build Directory contains :term:`TMPDIR` , which is a | ||
105 | temporary directory the build system uses for its work. TMPDIR cannot | ||
106 | be under NFS. Thus, by default, the Build Directory cannot be under | ||
107 | NFS. However, if you need the Build Directory to be under NFS, you can | ||
108 | set this up by setting TMPDIR in your local.conf file to use a local | ||
109 | drive. Doing so effectively separates TMPDIR from TOPDIR , which is the | ||
110 | Build Directory. | ||
111 | |||
112 | Build Host | ||
113 | The system used to build images in a Yocto Project Development | ||
114 | environment. The build system is sometimes referred to as the development | ||
115 | host. | ||
116 | |||
117 | Classes | ||
118 | Files that provide for logic encapsulation and inheritance so that | ||
119 | commonly used patterns can be defined once and then easily used in | ||
120 | multiple recipes. For reference information on the Yocto Project classes, | ||
121 | see the ":ref:`ref-manual/ref-classes:Classes`" chapter. Class files end with the | ||
122 | ``.bbclass`` filename extension. | ||
123 | |||
124 | Configuration File | ||
125 | Files that hold global definitions of variables, user-defined variables, | ||
126 | and hardware configuration information. These files tell the OpenEmbedded | ||
127 | build system what to build and what to put into the image to support a | ||
128 | particular platform. | ||
129 | |||
130 | Configuration files end with a ``.conf`` filename extension. The | ||
131 | :file:`conf/local.conf` configuration file in the :term:`Build Directory` | ||
132 | contains user-defined variables that affect every build. The | ||
133 | :file:`meta-poky/conf/distro/poky.conf` configuration file defines Yocto | ||
134 | "distro" configuration variables used only when building with this | ||
135 | policy. Machine configuration files, which are located throughout the | ||
136 | :term:`Source Directory`, define variables for specific hardware and are | ||
137 | only used when building for that target (e.g. the | ||
138 | :file:`machine/beaglebone.conf` configuration file defines variables for | ||
139 | the Texas Instruments ARM Cortex-A8 development board). | ||
140 | |||
141 | Container Layer | ||
142 | Layers that hold other layers. An example of a container layer is | ||
143 | OpenEmbedded's `meta-openembedded | ||
144 | <https://github.com/openembedded/meta-openembedded>`_ layer. The | ||
145 | ``meta-openembedded`` layer contains many ``meta-*`` layers. | ||
146 | |||
147 | Cross-Development Toolchain | ||
148 | In general, a cross-development toolchain is a collection of software | ||
149 | development tools and utilities that run on one architecture and allow you | ||
150 | to develop software for a different, or targeted, architecture. These | ||
151 | toolchains contain cross-compilers, linkers, and debuggers that are | ||
152 | specific to the target architecture. | ||
153 | |||
154 | The Yocto Project supports two different cross-development toolchains: | ||
155 | |||
156 | - A toolchain only used by and within BitBake when building an image for a | ||
157 | target architecture. | ||
158 | |||
159 | - A relocatable toolchain used outside of BitBake by developers when | ||
160 | developing applications that will run on a targeted device. | ||
161 | |||
162 | Creation of these toolchains is simple and automated. For information on | ||
163 | toolchain concepts as they apply to the Yocto Project, see the | ||
164 | ":ref:`overview-manual/overview-manual-concepts:Cross-Development | ||
165 | Toolchain Generation`" section in the Yocto Project Overview and Concepts | ||
166 | Manual. You can also find more information on using the relocatable | ||
167 | toolchain in the :ref:`sdk-manual/sdk-manual:Yocto Project Application | ||
168 | Development and the Extensible Software Development Kit (eSDK)` manual. | ||
169 | |||
170 | Extensible Software Development Kit (eSDK) | ||
171 | A custom SDK for application developers. This eSDK allows developers to | ||
172 | incorporate their library and programming changes back into the image to | ||
173 | make their code available to other application developers. | ||
174 | |||
175 | For information on the eSDK, see the :ref:`sdk-manual/sdk-manual:Yocto | ||
176 | Project Application Development and the Extensible Software Development | ||
177 | Kit (eSDK)` manual. | ||
178 | |||
179 | Image | ||
180 | An image is an artifact of the BitBake build process given a collection of | ||
181 | recipes and related Metadata. Images are the binary output that run on | ||
182 | specific hardware or QEMU and are used for specific use-cases. For a list | ||
183 | of the supported image types that the Yocto Project provides, see the | ||
184 | ":ref:`ref-manual/ref-images:Images`" chapter. | ||
185 | |||
186 | Layer | ||
187 | A collection of related recipes. Layers allow you to consolidate related | ||
188 | metadata to customize your build. Layers also isolate information used | ||
189 | when building for multiple architectures. Layers are hierarchical in | ||
190 | their ability to override previous specifications. You can include any | ||
191 | number of available layers from the Yocto Project and customize the build | ||
192 | by adding your layers after them. You can search the Layer Index for | ||
193 | layers used within Yocto Project. | ||
194 | |||
195 | For introductory information on layers, see the | ||
196 | ":ref:`overview-manual/overview-manual-yp-intro:The Yocto Project Layer | ||
197 | Model`" section in the Yocto Project Overview and Concepts Manual. For | ||
198 | more detailed information on layers, see the | ||
199 | ":ref:`dev-manual/dev-manual-common-tasks:Understanding and Creating | ||
200 | Layers`" section in the Yocto Project Development Tasks Manual. For a | ||
201 | discussion specifically on BSP Layers, see the ":ref:`bsp-guide/bsp:BSP | ||
202 | Layers`" section in the Yocto Project Board Support Packages (BSP) | ||
203 | Developer's Guide. | ||
204 | |||
205 | Metadata | ||
206 | A key element of the Yocto Project is the Metadata that | ||
207 | is used to construct a Linux distribution and is contained in the | ||
208 | files that the :term:`OpenEmbedded Build System` | ||
209 | parses when building an image. In general, Metadata includes recipes, | ||
210 | configuration files, and other information that refers to the build | ||
211 | instructions themselves, as well as the data used to control what | ||
212 | things get built and the effects of the build. Metadata also includes | ||
213 | commands and data used to indicate what versions of software are | ||
214 | used, from where they are obtained, and changes or additions to the | ||
215 | software itself (patches or auxiliary files) that are used to fix | ||
216 | bugs or customize the software for use in a particular situation. | ||
217 | OpenEmbedded-Core is an important set of validated metadata. | ||
218 | |||
219 | In the context of the kernel ("kernel Metadata"), the term refers to | ||
220 | the kernel config fragments and features contained in the | ||
221 | :yocto_git:`yocto-kernel-cache </cgit/cgit.cgi/yocto-kernel-cache>` | ||
222 | Git repository. | ||
223 | |||
224 | OpenEmbedded-Core (OE-Core) | ||
225 | OE-Core is metadata comprised of | ||
226 | foundational recipes, classes, and associated files that are meant to | ||
227 | be common among many different OpenEmbedded-derived systems, | ||
228 | including the Yocto Project. OE-Core is a curated subset of an | ||
229 | original repository developed by the OpenEmbedded community that has | ||
230 | been pared down into a smaller, core set of continuously validated | ||
231 | recipes. The result is a tightly controlled and an quality-assured | ||
232 | core set of recipes. | ||
233 | |||
234 | You can see the Metadata in the ``meta`` directory of the Yocto | ||
235 | Project :yocto_git:`Source Repositories <>`. | ||
236 | |||
237 | OpenEmbedded Build System | ||
238 | The build system specific to the Yocto | ||
239 | Project. The OpenEmbedded build system is based on another project | ||
240 | known as "Poky", which uses :term:`BitBake` as the task | ||
241 | executor. Throughout the Yocto Project documentation set, the | ||
242 | OpenEmbedded build system is sometimes referred to simply as "the | ||
243 | build system". If other build systems, such as a host or target build | ||
244 | system are referenced, the documentation clearly states the | ||
245 | difference. | ||
246 | |||
247 | .. note:: | ||
248 | |||
249 | For some historical information about Poky, see the | ||
250 | Poky | ||
251 | term. | ||
252 | |||
253 | Package | ||
254 | In the context of the Yocto Project, this term refers to a | ||
255 | recipe's packaged output produced by BitBake (i.e. a "baked recipe"). | ||
256 | A package is generally the compiled binaries produced from the | ||
257 | recipe's sources. You "bake" something by running it through BitBake. | ||
258 | |||
259 | It is worth noting that the term "package" can, in general, have | ||
260 | subtle meanings. For example, the packages referred to in the | ||
261 | "`Required Packages for the Build | ||
262 | Host <#required-packages-for-the-build-host>`__" section are compiled | ||
263 | binaries that, when installed, add functionality to your Linux | ||
264 | distribution. | ||
265 | |||
266 | Another point worth noting is that historically within the Yocto | ||
267 | Project, recipes were referred to as packages - thus, the existence | ||
268 | of several BitBake variables that are seemingly mis-named, (e.g. | ||
269 | :term:`PR`, :term:`PV`, and | ||
270 | :term:`PE`). | ||
271 | |||
272 | Package Groups | ||
273 | Arbitrary groups of software Recipes. You use | ||
274 | package groups to hold recipes that, when built, usually accomplish a | ||
275 | single task. For example, a package group could contain the recipes | ||
276 | for a company's proprietary or value-add software. Or, the package | ||
277 | group could contain the recipes that enable graphics. A package group | ||
278 | is really just another recipe. Because package group files are | ||
279 | recipes, they end with the ``.bb`` filename extension. | ||
280 | |||
281 | Poky | ||
282 | Poky, which is pronounced *Pock*-ee, is a reference embedded | ||
283 | distribution and a reference test configuration. Poky provides the | ||
284 | following: | ||
285 | |||
286 | - A base-level functional distro used to illustrate how to customize | ||
287 | a distribution. | ||
288 | |||
289 | - A means by which to test the Yocto Project components (i.e. Poky | ||
290 | is used to validate the Yocto Project). | ||
291 | |||
292 | - A vehicle through which you can download the Yocto Project. | ||
293 | |||
294 | Poky is not a product level distro. Rather, it is a good starting | ||
295 | point for customization. | ||
296 | |||
297 | .. note:: | ||
298 | |||
299 | Poky began as an open-source project initially developed by | ||
300 | OpenedHand. OpenedHand developed Poky from the existing | ||
301 | OpenEmbedded build system to create a commercially supportable | ||
302 | build system for embedded Linux. After Intel Corporation acquired | ||
303 | OpenedHand, the poky project became the basis for the Yocto | ||
304 | Project's build system. | ||
305 | |||
306 | Recipe | ||
307 | A set of instructions for building packages. A recipe | ||
308 | describes where you get source code, which patches to apply, how to | ||
309 | configure the source, how to compile it and so on. Recipes also | ||
310 | describe dependencies for libraries or for other recipes. Recipes | ||
311 | represent the logical unit of execution, the software to build, the | ||
312 | images to build, and use the ``.bb`` file extension. | ||
313 | |||
314 | Reference Kit | ||
315 | A working example of a system, which includes a | ||
316 | :term:`BSP<Board Support Package (BSP)>` as well as a | ||
317 | :term:`build host<Build Host>` and other components, that can | ||
318 | work on specific hardware. | ||
319 | |||
320 | Source Directory | ||
321 | This term refers to the directory structure | ||
322 | created as a result of creating a local copy of the ``poky`` Git | ||
323 | repository ``git://git.yoctoproject.org/poky`` or expanding a | ||
324 | released ``poky`` tarball. | ||
325 | |||
326 | .. note:: | ||
327 | |||
328 | Creating a local copy of the | ||
329 | poky | ||
330 | Git repository is the recommended method for setting up your | ||
331 | Source Directory. | ||
332 | |||
333 | Sometimes you might hear the term "poky directory" used to refer to | ||
334 | this directory structure. | ||
335 | |||
336 | .. note:: | ||
337 | |||
338 | The OpenEmbedded build system does not support file or directory | ||
339 | names that contain spaces. Be sure that the Source Directory you | ||
340 | use does not contain these types of names. | ||
341 | |||
342 | The Source Directory contains BitBake, Documentation, Metadata and | ||
343 | other files that all support the Yocto Project. Consequently, you | ||
344 | must have the Source Directory in place on your development system in | ||
345 | order to do any development using the Yocto Project. | ||
346 | |||
347 | When you create a local copy of the Git repository, you can name the | ||
348 | repository anything you like. Throughout much of the documentation, | ||
349 | "poky" is used as the name of the top-level folder of the local copy | ||
350 | of the poky Git repository. So, for example, cloning the ``poky`` Git | ||
351 | repository results in a local Git repository whose top-level folder | ||
352 | is also named "poky". | ||
353 | |||
354 | While it is not recommended that you use tarball expansion to set up | ||
355 | the Source Directory, if you do, the top-level directory name of the | ||
356 | Source Directory is derived from the Yocto Project release tarball. | ||
357 | For example, downloading and unpacking | ||
358 | :yocto_dl:`/releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2` | ||
359 | results in a Source Directory whose root folder is named ``poky``. | ||
360 | |||
361 | It is important to understand the differences between the Source | ||
362 | Directory created by unpacking a released tarball as compared to | ||
363 | cloning ``git://git.yoctoproject.org/poky``. When you unpack a | ||
364 | tarball, you have an exact copy of the files based on the time of | ||
365 | release - a fixed release point. Any changes you make to your local | ||
366 | files in the Source Directory are on top of the release and will | ||
367 | remain local only. On the other hand, when you clone the ``poky`` Git | ||
368 | repository, you have an active development repository with access to | ||
369 | the upstream repository's branches and tags. In this case, any local | ||
370 | changes you make to the local Source Directory can be later applied | ||
371 | to active development branches of the upstream ``poky`` Git | ||
372 | repository. | ||
373 | |||
374 | For more information on concepts related to Git repositories, | ||
375 | branches, and tags, see the | ||
376 | ":ref:`overview-manual/overview-manual-development-environment:repositories, tags, and branches`" | ||
377 | section in the Yocto Project Overview and Concepts Manual. | ||
378 | |||
379 | Task | ||
380 | A unit of execution for BitBake (e.g. | ||
381 | :ref:`ref-tasks-compile`, | ||
382 | :ref:`ref-tasks-fetch`, | ||
383 | :ref:`ref-tasks-patch`, and so forth). | ||
384 | |||
385 | Toaster | ||
386 | A web interface to the Yocto Project's :term:`OpenEmbedded Build System`. | ||
387 | The interface enables you to | ||
388 | configure and run your builds. Information about builds is collected | ||
389 | and stored in a database. For information on Toaster, see the | ||
390 | :doc:`../toaster-manual/toaster-manual`. | ||
391 | |||
392 | Upstream | ||
393 | A reference to source code or repositories that are not | ||
394 | local to the development system but located in a master area that is | ||
395 | controlled by the maintainer of the source code. For example, in | ||
396 | order for a developer to work on a particular piece of code, they | ||
397 | need to first get a copy of it from an "upstream" source. | ||
diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml index 722fa7ee27..2a0452bd78 100644 --- a/documentation/ref-manual/ref-terms.xml +++ b/documentation/ref-manual/ref-terms.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-terms'> | 6 | <chapter id='ref-terms'> |
6 | <title>Yocto Project Terms</title> | 7 | <title>Yocto Project Terms</title> |
@@ -364,7 +365,7 @@ | |||
364 | You use package groups to hold recipes that, when built, | 365 | You use package groups to hold recipes that, when built, |
365 | usually accomplish a single task. | 366 | usually accomplish a single task. |
366 | For example, a package group could contain the recipes for a | 367 | For example, a package group could contain the recipes for a |
367 | company’s proprietary or value-add software. | 368 | company's proprietary or value-add software. |
368 | Or, the package group could contain the recipes that enable | 369 | Or, the package group could contain the recipes that enable |
369 | graphics. | 370 | graphics. |
370 | A package group is really just another recipe. | 371 | A package group is really just another recipe. |
diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst new file mode 100644 index 0000000000..c49c208bc0 --- /dev/null +++ b/documentation/ref-manual/ref-variables.rst | |||
@@ -0,0 +1,8899 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | ****************** | ||
4 | Variables Glossary | ||
5 | ****************** | ||
6 | |||
7 | This chapter lists common variables used in the OpenEmbedded build | ||
8 | system and gives an overview of their function and contents. | ||
9 | |||
10 | `A <#var-ABIEXTENSION>`__ :term:`B` `C <#var-CACHE>`__ | ||
11 | :term:`D` `E <#var-EFI_PROVIDER>`__ `F <#var-FEATURE_PACKAGES>`__ | ||
12 | `G <#var-GCCPIE>`__ `H <#var-HOMEPAGE>`__ `I <#var-ICECC_DISABLED>`__ | ||
13 | `K <#var-KARCH>`__ `L <#var-LABELS>`__ `M <#var-MACHINE>`__ | ||
14 | `N <#var-NATIVELSBSTRING>`__ `O <#var-OBJCOPY>`__ :term:`P` | ||
15 | `R <#var-RANLIB>`__ :term:`S` :term:`T` | ||
16 | `U <#var-UBOOT_CONFIG>`__ `V <#var-VOLATILE_LOG_DIR>`__ | ||
17 | `W <#var-WARN_QA>`__ `X <#var-XSERVER>`__ | ||
18 | |||
19 | .. glossary:: | ||
20 | |||
21 | ABIEXTENSION | ||
22 | Extension to the Application Binary Interface (ABI) field of the GNU | ||
23 | canonical architecture name (e.g. "eabi"). | ||
24 | |||
25 | ABI extensions are set in the machine include files. For example, the | ||
26 | ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the | ||
27 | following extension: | ||
28 | :: | ||
29 | |||
30 | ABIEXTENSION = "eabi" | ||
31 | |||
32 | ALLOW_EMPTY | ||
33 | Specifies whether to produce an output package even if it is empty. | ||
34 | By default, BitBake does not produce empty packages. This default | ||
35 | behavior can cause issues when there is an | ||
36 | :term:`RDEPENDS` or some other hard runtime | ||
37 | requirement on the existence of the package. | ||
38 | |||
39 | Like all package-controlling variables, you must always use them in | ||
40 | conjunction with a package name override, as in: | ||
41 | :: | ||
42 | |||
43 | ALLOW_EMPTY_${PN} = "1" | ||
44 | ALLOW_EMPTY_${PN}-dev = "1" | ||
45 | ALLOW_EMPTY_${PN}-staticdev = "1" | ||
46 | |||
47 | ALTERNATIVE | ||
48 | Lists commands in a package that need an alternative binary naming | ||
49 | scheme. Sometimes the same command is provided in multiple packages. | ||
50 | When this occurs, the OpenEmbedded build system needs to use the | ||
51 | alternatives system to create a different binary naming scheme so the | ||
52 | commands can co-exist. | ||
53 | |||
54 | To use the variable, list out the package's commands that also exist | ||
55 | as part of another package. For example, if the ``busybox`` package | ||
56 | has four commands that also exist as part of another package, you | ||
57 | identify them as follows: | ||
58 | :: | ||
59 | |||
60 | ALTERNATIVE_busybox = "sh sed test bracket" | ||
61 | |||
62 | For more information on the alternatives system, see the | ||
63 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
64 | section. | ||
65 | |||
66 | ALTERNATIVE_LINK_NAME | ||
67 | Used by the alternatives system to map duplicated commands to actual | ||
68 | locations. For example, if the ``bracket`` command provided by the | ||
69 | ``busybox`` package is duplicated through another package, you must | ||
70 | use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual | ||
71 | location: | ||
72 | :: | ||
73 | |||
74 | ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" | ||
75 | |||
76 | In this example, the binary for the ``bracket`` command (i.e. ``[``) | ||
77 | from the ``busybox`` package resides in ``/usr/bin/``. | ||
78 | |||
79 | .. note:: | ||
80 | |||
81 | If ALTERNATIVE_LINK_NAME is not defined, it defaults to ${bindir}/ name. | ||
82 | |||
83 | For more information on the alternatives system, see the | ||
84 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
85 | section. | ||
86 | |||
87 | ALTERNATIVE_PRIORITY | ||
88 | Used by the alternatives system to create default priorities for | ||
89 | duplicated commands. You can use the variable to create a single | ||
90 | default regardless of the command name or package, a default for | ||
91 | specific duplicated commands regardless of the package, or a default | ||
92 | for specific commands tied to particular packages. Here are the | ||
93 | available syntax forms: | ||
94 | :: | ||
95 | |||
96 | ALTERNATIVE_PRIORITY = "priority" | ||
97 | ALTERNATIVE_PRIORITY[name] = "priority" | ||
98 | ALTERNATIVE_PRIORITY_pkg[name] = "priority" | ||
99 | |||
100 | For more information on the alternatives system, see the | ||
101 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
102 | section. | ||
103 | |||
104 | ALTERNATIVE_TARGET | ||
105 | Used by the alternatives system to create default link locations for | ||
106 | duplicated commands. You can use the variable to create a single | ||
107 | default location for all duplicated commands regardless of the | ||
108 | command name or package, a default for specific duplicated commands | ||
109 | regardless of the package, or a default for specific commands tied to | ||
110 | particular packages. Here are the available syntax forms: | ||
111 | :: | ||
112 | |||
113 | ALTERNATIVE_TARGET = "target" | ||
114 | ALTERNATIVE_TARGET[name] = "target" | ||
115 | ALTERNATIVE_TARGET_pkg[name] = "target" | ||
116 | |||
117 | .. note:: | ||
118 | |||
119 | If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value | ||
120 | from the :term:`ALTERNATIVE_LINK_NAME` variable. | ||
121 | |||
122 | If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the | ||
123 | same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" | ||
124 | appended to it. | ||
125 | |||
126 | Finally, if the file referenced has not been renamed, the | ||
127 | alternatives system will rename it to avoid the need to rename | ||
128 | alternative files in the :ref:`ref-tasks-install` | ||
129 | task while retaining support for the command if necessary. | ||
130 | |||
131 | For more information on the alternatives system, see the | ||
132 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
133 | section. | ||
134 | |||
135 | APPEND | ||
136 | An override list of append strings for each target specified with | ||
137 | :term:`LABELS`. | ||
138 | |||
139 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | ||
140 | information on how this variable is used. | ||
141 | |||
142 | AR | ||
143 | The minimal command and arguments used to run ``ar``. | ||
144 | |||
145 | ARCHIVER_MODE | ||
146 | When used with the :ref:`archiver <ref-classes-archiver>` class, | ||
147 | determines the type of information used to create a released archive. | ||
148 | You can use this variable to create archives of patched source, | ||
149 | original source, configured source, and so forth by employing the | ||
150 | following variable flags (varflags): | ||
151 | :: | ||
152 | |||
153 | ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. | ||
154 | ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. | ||
155 | ARCHIVER_MODE[src] = "configured" # Uses configured source files. | ||
156 | ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch. | ||
157 | ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff. | ||
158 | ARCHIVER_MODE[dumpdata] = "1" # Uses environment data. | ||
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 | ||
163 | ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`. | ||
164 | |||
165 | AS | ||
166 | Minimal command and arguments needed to run the assembler. | ||
167 | |||
168 | ASSUME_PROVIDED | ||
169 | Lists recipe names (:term:`PN` values) BitBake does not | ||
170 | attempt to build. Instead, BitBake assumes these recipes have already | ||
171 | been built. | ||
172 | |||
173 | In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native | ||
174 | tools that should not be built. An example is ``git-native``, which | ||
175 | when specified, allows for the Git binary from the host to be used | ||
176 | rather than building ``git-native``. | ||
177 | |||
178 | ASSUME_SHLIBS | ||
179 | Provides additional ``shlibs`` provider mapping information, which | ||
180 | adds to or overwrites the information provided automatically by the | ||
181 | system. Separate multiple entries using spaces. | ||
182 | |||
183 | As an example, use the following form to add an ``shlib`` provider of | ||
184 | shlibname in packagename with the optional version: | ||
185 | :: | ||
186 | |||
187 | shlibname:packagename[_version] | ||
188 | |||
189 | Here is an example that adds a shared library named ``libEGL.so.1`` | ||
190 | as being provided by the ``libegl-implementation`` package: | ||
191 | :: | ||
192 | |||
193 | ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" | ||
194 | |||
195 | AUTHOR | ||
196 | The email address used to contact the original author or authors in | ||
197 | order to send patches and forward bugs. | ||
198 | |||
199 | AUTO_LIBNAME_PKGS | ||
200 | When the :ref:`debian <ref-classes-debian>` class is inherited, | ||
201 | which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which | ||
202 | packages should be checked for libraries and renamed according to | ||
203 | Debian library package naming. | ||
204 | |||
205 | The default value is "${PACKAGES}", which causes the debian class to | ||
206 | act on all packages that are explicitly generated by the recipe. | ||
207 | |||
208 | AUTO_SYSLINUXMENU | ||
209 | Enables creating an automatic menu for the syslinux bootloader. You | ||
210 | must set this variable in your recipe. The | ||
211 | :ref:`syslinux <ref-classes-syslinux>` class checks this variable. | ||
212 | |||
213 | AUTOREV | ||
214 | When ``SRCREV`` is set to the value of this variable, it specifies to | ||
215 | use the latest source revision in the repository. Here is an example: | ||
216 | :: | ||
217 | |||
218 | SRCREV = "${AUTOREV}" | ||
219 | |||
220 | If you use the previous statement to retrieve the latest version of | ||
221 | software, you need to be sure :term:`PV` contains | ||
222 | ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you | ||
223 | have a kernel recipe that inherits the | ||
224 | :ref:`kernel <ref-classes-kernel>` class and you use the previous | ||
225 | statement. In this example, ``${SRCPV}`` does not automatically get | ||
226 | into ``PV``. Consequently, you need to change ``PV`` in your recipe | ||
227 | so that it does contain ``${SRCPV}``. | ||
228 | |||
229 | For more information see the | ||
230 | ":ref:`dev-manual/dev-manual-common-tasks:automatically incrementing a package version number`" | ||
231 | section in the Yocto Project Development Tasks Manual. | ||
232 | |||
233 | AVAILABLE_LICENSES | ||
234 | List of licenses found in the directories specified by | ||
235 | :term:`COMMON_LICENSE_DIR` and | ||
236 | :term:`LICENSE_PATH`. | ||
237 | |||
238 | .. note:: | ||
239 | |||
240 | It is assumed that all changes to | ||
241 | COMMON_LICENSE_DIR | ||
242 | and | ||
243 | LICENSE_PATH | ||
244 | have been done before | ||
245 | AVAILABLE_LICENSES | ||
246 | is defined (in | ||
247 | license.bbclass | ||
248 | ). | ||
249 | |||
250 | AVAILTUNES | ||
251 | The list of defined CPU and Application Binary Interface (ABI) | ||
252 | tunings (i.e. "tunes") available for use by the OpenEmbedded build | ||
253 | system. | ||
254 | |||
255 | The list simply presents the tunes that are available. Not all tunes | ||
256 | may be compatible with a particular machine configuration, or with | ||
257 | each other in a | ||
258 | :ref:`Multilib <dev-manual/dev-manual-common-tasks:combining multiple versions of library files into one image>` | ||
259 | configuration. | ||
260 | |||
261 | To add a tune to the list, be sure to append it with spaces using the | ||
262 | "+=" BitBake operator. Do not simply replace the list by using the | ||
263 | "=" operator. See the | ||
264 | ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake | ||
265 | User Manual for more information. | ||
266 | |||
267 | B | ||
268 | The directory within the :term:`Build Directory` in | ||
269 | which the OpenEmbedded build system places generated objects during a | ||
270 | recipe's build process. By default, this directory is the same as the | ||
271 | :term:`S` directory, which is defined as: | ||
272 | :: | ||
273 | |||
274 | S = "${WORKDIR}/${BP}" | ||
275 | |||
276 | You can separate the (``S``) directory and the directory pointed to | ||
277 | by the ``B`` variable. Most Autotools-based recipes support | ||
278 | separating these directories. The build system defaults to using | ||
279 | separate directories for ``gcc`` and some kernel recipes. | ||
280 | |||
281 | BAD_RECOMMENDATIONS | ||
282 | Lists "recommended-only" packages to not install. Recommended-only | ||
283 | packages are packages installed only through the | ||
284 | :term:`RRECOMMENDS` variable. You can prevent any | ||
285 | of these "recommended" packages from being installed by listing them | ||
286 | with the ``BAD_RECOMMENDATIONS`` variable: | ||
287 | :: | ||
288 | |||
289 | BAD_RECOMMENDATIONS = "package_name package_name package_name ..." | ||
290 | |||
291 | You can set this variable globally in your ``local.conf`` file or you | ||
292 | can attach it to a specific image recipe by using the recipe name | ||
293 | override: | ||
294 | :: | ||
295 | |||
296 | BAD_RECOMMENDATIONS_pn-target_image = "package_name" | ||
297 | |||
298 | It is important to realize that if you choose to not install packages | ||
299 | using this variable and some other packages are dependent on them | ||
300 | (i.e. listed in a recipe's :term:`RDEPENDS` | ||
301 | variable), the OpenEmbedded build system ignores your request and | ||
302 | will install the packages to avoid dependency errors. | ||
303 | |||
304 | Support for this variable exists only when using the IPK and RPM | ||
305 | packaging backend. Support does not exist for DEB. | ||
306 | |||
307 | See the :term:`NO_RECOMMENDATIONS` and the | ||
308 | :term:`PACKAGE_EXCLUDE` variables for related | ||
309 | information. | ||
310 | |||
311 | BASE_LIB | ||
312 | The library directory name for the CPU or Application Binary | ||
313 | Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib | ||
314 | context. See the ":ref:`dev-manual/dev-manual-common-tasks:combining multiple versions of library files into one image`" | ||
315 | section in the Yocto Project Development Tasks Manual for information | ||
316 | on Multilib. | ||
317 | |||
318 | The ``BASE_LIB`` variable is defined in the machine include files in | ||
319 | the :term:`Source Directory`. If Multilib is not | ||
320 | being used, the value defaults to "lib". | ||
321 | |||
322 | BASE_WORKDIR | ||
323 | Points to the base of the work directory for all recipes. The default | ||
324 | value is "${TMPDIR}/work". | ||
325 | |||
326 | BB_ALLOWED_NETWORKS | ||
327 | Specifies a space-delimited list of hosts that the fetcher is allowed | ||
328 | to use to obtain the required source code. Following are | ||
329 | considerations surrounding this variable: | ||
330 | |||
331 | - This host list is only used if ``BB_NO_NETWORK`` is either not set | ||
332 | or set to "0". | ||
333 | |||
334 | - Limited support for wildcard matching against the beginning of | ||
335 | host names exists. For example, the following setting matches | ||
336 | ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``. | ||
337 | :: | ||
338 | |||
339 | BB_ALLOWED_NETWORKS = "*.gnu.org" | ||
340 | |||
341 | .. note:: | ||
342 | |||
343 | The use of the "``*``" character only works at the beginning of | ||
344 | a host name and it must be isolated from the remainder of the | ||
345 | host name. You cannot use the wildcard character in any other | ||
346 | location of the name or combined with the front part of the | ||
347 | name. | ||
348 | |||
349 | For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` | ||
350 | is not. | ||
351 | |||
352 | - Mirrors not in the host list are skipped and logged in debug. | ||
353 | |||
354 | - Attempts to access networks not in the host list cause a failure. | ||
355 | |||
356 | Using ``BB_ALLOWED_NETWORKS`` in conjunction with | ||
357 | :term:`PREMIRRORS` is very useful. Adding the host | ||
358 | you want to use to ``PREMIRRORS`` results in the source code being | ||
359 | fetched from an allowed location and avoids raising an error when a | ||
360 | host that is not allowed is in a :term:`SRC_URI` | ||
361 | statement. This is because the fetcher does not attempt to use the | ||
362 | host listed in ``SRC_URI`` after a successful fetch from the | ||
363 | ``PREMIRRORS`` occurs. | ||
364 | |||
365 | BB_DANGLINGAPPENDS_WARNONLY | ||
366 | Defines how BitBake handles situations where an append file | ||
367 | (``.bbappend``) has no corresponding recipe file (``.bb``). This | ||
368 | condition often occurs when layers get out of sync (e.g. ``oe-core`` | ||
369 | bumps a recipe version and the old recipe no longer exists and the | ||
370 | other layer has not been updated to the new version of the recipe | ||
371 | yet). | ||
372 | |||
373 | The default fatal behavior is safest because it is the sane reaction | ||
374 | given something is out of sync. It is important to realize when your | ||
375 | changes are no longer being applied. | ||
376 | |||
377 | You can change the default behavior by setting this variable to "1", | ||
378 | "yes", or "true" in your ``local.conf`` file, which is located in the | ||
379 | :term:`Build Directory`: Here is an example: | ||
380 | :: | ||
381 | |||
382 | BB_DANGLINGAPPENDS_WARNONLY = "1" | ||
383 | |||
384 | BB_DISKMON_DIRS | ||
385 | Monitors disk space and available inodes during the build and allows | ||
386 | you to control the build based on these parameters. | ||
387 | |||
388 | Disk space monitoring is disabled by default. To enable monitoring, | ||
389 | add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file | ||
390 | found in the :term:`Build Directory`. Use the | ||
391 | following form: | ||
392 | :: | ||
393 | |||
394 | BB_DISKMON_DIRS = "action,dir,threshold [...]" | ||
395 | |||
396 | where: | ||
397 | |||
398 | action is: | ||
399 | ABORT: Immediately abort the build when | ||
400 | a threshold is broken. | ||
401 | STOPTASKS: Stop the build after the currently | ||
402 | executing tasks have finished when | ||
403 | a threshold is broken. | ||
404 | WARN: Issue a warning but continue the | ||
405 | build when a threshold is broken. | ||
406 | Subsequent warnings are issued as | ||
407 | defined by the BB_DISKMON_WARNINTERVAL | ||
408 | variable, which must be defined in | ||
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 | |||
435 | The first example works only if you also provide the | ||
436 | :term:`BB_DISKMON_WARNINTERVAL` | ||
437 | variable in the ``conf/local.conf``. This example causes the build | ||
438 | system to immediately abort when either the disk space in | ||
439 | ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops | ||
440 | below 100 Kbytes. Because two directories are provided with the | ||
441 | variable, the build system also issue a warning when the disk space | ||
442 | in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number | ||
443 | of free inodes drops below 100 Kbytes. Subsequent warnings are issued | ||
444 | during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` | ||
445 | variable. | ||
446 | |||
447 | The second example stops the build after all currently executing | ||
448 | tasks complete when the minimum disk space in the ``${TMPDIR}`` | ||
449 | directory drops below 1 Gbyte. No disk monitoring occurs for the free | ||
450 | inodes in this case. | ||
451 | |||
452 | The final example immediately aborts the build when the number of | ||
453 | free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No | ||
454 | disk space monitoring for the directory itself occurs in this case. | ||
455 | |||
456 | BB_DISKMON_WARNINTERVAL | ||
457 | Defines the disk space and free inode warning intervals. To set these | ||
458 | intervals, define the variable in your ``conf/local.conf`` file in | ||
459 | the :term:`Build Directory`. | ||
460 | |||
461 | If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you | ||
462 | must also use the :term:`BB_DISKMON_DIRS` | ||
463 | variable and define its action as "WARN". During the build, | ||
464 | subsequent warnings are issued each time disk space or number of free | ||
465 | inodes further reduces by the respective interval. | ||
466 | |||
467 | If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you | ||
468 | do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk | ||
469 | monitoring interval defaults to the following: | ||
470 | :: | ||
471 | |||
472 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
473 | |||
474 | When specifying the variable in your configuration file, use the | ||
475 | following form: | ||
476 | :: | ||
477 | |||
478 | BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval" | ||
479 | |||
480 | where: | ||
481 | |||
482 | disk_space_interval is: | ||
483 | An interval of memory expressed in either | ||
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 | ||
499 | OpenEmbedded build system to issue subsequent warnings each time the | ||
500 | available disk space further reduces by 50 Mbytes or the number of | ||
501 | free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` | ||
502 | directory. Subsequent warnings based on the interval occur each time | ||
503 | a respective interval is reached beyond the initial warning (i.e. 1 | ||
504 | Gbytes and 100 Kbytes). | ||
505 | |||
506 | BB_GENERATE_MIRROR_TARBALLS | ||
507 | Causes tarballs of the source control repositories (e.g. Git | ||
508 | repositories), including metadata, to be placed in the | ||
509 | :term:`DL_DIR` directory. | ||
510 | |||
511 | For performance reasons, creating and placing tarballs of these | ||
512 | repositories is not the default action by the OpenEmbedded build | ||
513 | system. | ||
514 | :: | ||
515 | |||
516 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
517 | |||
518 | Set this variable in your | ||
519 | ``local.conf`` file in the :term:`Build Directory`. | ||
520 | |||
521 | Once you have the tarballs containing your source files, you can | ||
522 | clean up your ``DL_DIR`` directory by deleting any Git or other | ||
523 | source control work directories. | ||
524 | |||
525 | BB_NUMBER_THREADS | ||
526 | The maximum number of tasks BitBake should run in parallel at any one | ||
527 | time. The OpenEmbedded build system automatically configures this | ||
528 | variable to be equal to the number of cores on the build system. For | ||
529 | example, a system with a dual core processor that also uses | ||
530 | hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default | ||
531 | to "4". | ||
532 | |||
533 | For single socket systems (i.e. one CPU), you should not have to | ||
534 | override this variable to gain optimal parallelism during builds. | ||
535 | However, if you have very large systems that employ multiple physical | ||
536 | CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable | ||
537 | is not set higher than "20". | ||
538 | |||
539 | For more information on speeding up builds, see the | ||
540 | ":ref:`dev-manual/dev-manual-common-tasks:speeding up a build`" | ||
541 | section in the Yocto Project Development Tasks Manual. | ||
542 | |||
543 | BB_SERVER_TIMEOUT | ||
544 | Specifies the time (in seconds) after which to unload the BitBake | ||
545 | server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how | ||
546 | long the BitBake server stays resident between invocations. | ||
547 | |||
548 | For example, the following statement in your ``local.conf`` file | ||
549 | instructs the server to be unloaded after 20 seconds of inactivity: | ||
550 | :: | ||
551 | |||
552 | BB_SERVER_TIMEOUT = "20" | ||
553 | |||
554 | If you want the server to never be unloaded, | ||
555 | set ``BB_SERVER_TIMEOUT`` to "-1". | ||
556 | |||
557 | BBCLASSEXTEND | ||
558 | Allows you to extend a recipe so that it builds variants of the | ||
559 | software. Common variants for recipes exist such as "natives" like | ||
560 | ``quilt-native``, which is a copy of Quilt built to run on the build | ||
561 | system; "crosses" such as ``gcc-cross``, which is a compiler built to | ||
562 | run on the build machine but produces binaries that run on the target | ||
563 | :term:`MACHINE`; "nativesdk", which targets the SDK | ||
564 | machine instead of ``MACHINE``; and "mulitlibs" in the form | ||
565 | "``multilib:``\ multilib_name". | ||
566 | |||
567 | To build a different variant of the recipe with a minimal amount of | ||
568 | code, it usually is as simple as adding the following to your recipe: | ||
569 | :: | ||
570 | |||
571 | BBCLASSEXTEND =+ "native nativesdk" | ||
572 | BBCLASSEXTEND =+ "multilib:multilib_name" | ||
573 | |||
574 | .. note:: | ||
575 | |||
576 | Internally, the ``BBCLASSEXTEND`` mechanism generates recipe | ||
577 | variants by rewriting variable values and applying overrides such | ||
578 | as ``_class-native``. For example, to generate a native version of | ||
579 | a recipe, a :term:`DEPENDS` on "foo" is rewritten | ||
580 | to a ``DEPENDS`` on "foo-native". | ||
581 | |||
582 | Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. | ||
583 | Parsing once adds some limitations. For example, it is not | ||
584 | possible to include a different file depending on the variant, | ||
585 | since ``include`` statements are processed when the recipe is | ||
586 | parsed. | ||
587 | |||
588 | BBFILE_COLLECTIONS | ||
589 | Lists the names of configured layers. These names are used to find | ||
590 | the other ``BBFILE_*`` variables. Typically, each layer will append | ||
591 | its name to this variable in its ``conf/layer.conf`` file. | ||
592 | |||
593 | BBFILE_PATTERN | ||
594 | Variable that expands to match files from | ||
595 | :term:`BBFILES` in a particular layer. This variable | ||
596 | is used in the ``conf/layer.conf`` file and must be suffixed with the | ||
597 | name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). | ||
598 | |||
599 | BBFILE_PRIORITY | ||
600 | Assigns the priority for recipe files in each layer. | ||
601 | |||
602 | This variable is useful in situations where the same recipe appears | ||
603 | in more than one layer. Setting this variable allows you to | ||
604 | prioritize a layer against other layers that contain the same recipe | ||
605 | - effectively letting you control the precedence for the multiple | ||
606 | layers. The precedence established through this variable stands | ||
607 | regardless of a recipe's version (:term:`PV` variable). For | ||
608 | example, a layer that has a recipe with a higher ``PV`` value but for | ||
609 | which the ``BBFILE_PRIORITY`` is set to have a lower precedence still | ||
610 | has a lower precedence. | ||
611 | |||
612 | A larger value for the ``BBFILE_PRIORITY`` variable results in a | ||
613 | higher precedence. For example, the value 6 has a higher precedence | ||
614 | than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable | ||
615 | is set based on layer dependencies (see the ``LAYERDEPENDS`` variable | ||
616 | for more information. The default priority, if unspecified for a | ||
617 | layer with no dependencies, is the lowest defined priority + 1 (or 1 | ||
618 | if no priorities are defined). | ||
619 | |||
620 | .. tip:: | ||
621 | |||
622 | You can use the command | ||
623 | bitbake-layers show-layers | ||
624 | to list all configured layers along with their priorities. | ||
625 | |||
626 | BBFILES | ||
627 | A space-separated list of recipe files BitBake uses to build | ||
628 | software. | ||
629 | |||
630 | When specifying recipe files, you can pattern match using Python's | ||
631 | `glob <https://docs.python.org/3/library/glob.html>`_ syntax. | ||
632 | For details on the syntax, see the documentation by following the | ||
633 | previous link. | ||
634 | |||
635 | BBFILES_DYNAMIC | ||
636 | Activates content when identified layers are present. You identify | ||
637 | the layers by the collections that the layers define. | ||
638 | |||
639 | Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files | ||
640 | whose corresponding ``.bb`` file is in a layer that attempts to | ||
641 | modify other layers through ``.bbappend`` but does not want to | ||
642 | introduce a hard dependency on those other layers. | ||
643 | |||
644 | Use the following form for ``BBFILES_DYNAMIC``: | ||
645 | collection_name:filename_pattern The following example identifies two | ||
646 | collection names and two filename patterns: | ||
647 | :: | ||
648 | |||
649 | BBFILES_DYNAMIC += " \ | ||
650 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ | ||
651 | core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ | ||
652 | " | ||
653 | |||
654 | This next example shows an error message that occurs because invalid | ||
655 | entries are found, which cause parsing to abort: | ||
656 | :: | ||
657 | |||
658 | ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not: | ||
659 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend | ||
660 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend | ||
661 | |||
662 | BBINCLUDELOGS | ||
663 | Variable that controls how BitBake displays logs on build failure. | ||
664 | |||
665 | BBINCLUDELOGS_LINES | ||
666 | If :term:`BBINCLUDELOGS` is set, specifies the | ||
667 | maximum number of lines from the task log file to print when | ||
668 | reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, | ||
669 | the entire log is printed. | ||
670 | |||
671 | BBLAYERS | ||
672 | Lists the layers to enable during the build. This variable is defined | ||
673 | in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. | ||
674 | Here is an example: | ||
675 | :: | ||
676 | |||
677 | BBLAYERS = " \ | ||
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 | |||
683 | This example enables four layers, one of which is a custom, | ||
684 | user-defined layer named ``meta-mykernel``. | ||
685 | |||
686 | BBMASK | ||
687 | Prevents BitBake from processing recipes and recipe append files. | ||
688 | |||
689 | You can use the ``BBMASK`` variable to "hide" these ``.bb`` and | ||
690 | ``.bbappend`` files. BitBake ignores any recipe or recipe append | ||
691 | files that match any of the expressions. It is as if BitBake does not | ||
692 | see them at all. Consequently, matching files are not parsed or | ||
693 | otherwise used by BitBake. | ||
694 | |||
695 | The values you provide are passed to Python's regular expression | ||
696 | compiler. Consequently, the syntax follows Python's Regular | ||
697 | Expression (re) syntax. The expressions are compared against the full | ||
698 | paths to the files. For complete syntax information, see Python's | ||
699 | documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax. | ||
700 | |||
701 | The following example uses a complete regular expression to tell | ||
702 | BitBake to ignore all recipe and recipe append files in the | ||
703 | ``meta-ti/recipes-misc/`` directory: | ||
704 | :: | ||
705 | |||
706 | BBMASK = "meta-ti/recipes-misc/" | ||
707 | |||
708 | If you want to mask out multiple directories or recipes, you can | ||
709 | specify multiple regular expression fragments. This next example | ||
710 | masks out multiple directories and individual recipes: :: | ||
711 | |||
712 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" | ||
713 | BBMASK += "/meta-oe/recipes-support/" | ||
714 | BBMASK += "/meta-foo/.*/openldap" | ||
715 | BBMASK += "opencv.*\.bbappend" | ||
716 | BBMASK += "lzma" | ||
717 | |||
718 | .. note:: | ||
719 | |||
720 | When specifying a directory name, use the trailing slash character | ||
721 | to ensure you match just that directory name. | ||
722 | |||
723 | BBMULTICONFIG | ||
724 | Specifies each additional separate configuration when you are | ||
725 | building targets with multiple configurations. Use this variable in | ||
726 | your ``conf/local.conf`` configuration file. Specify a | ||
727 | multiconfigname for each configuration file you are using. For | ||
728 | example, the following line specifies three configuration files: | ||
729 | :: | ||
730 | |||
731 | BBMULTICONFIG = "configA configB configC" | ||
732 | |||
733 | Each configuration file you | ||
734 | use must reside in the :term:`Build Directory` | ||
735 | ``conf/multiconfig`` directory (e.g. | ||
736 | build_directory\ ``/conf/multiconfig/configA.conf``). | ||
737 | |||
738 | For information on how to use ``BBMULTICONFIG`` in an environment | ||
739 | that supports building targets with multiple configurations, see the | ||
740 | ":ref:`dev-building-images-for-multiple-targets-using-multiple-configurations`" | ||
741 | section in the Yocto Project Development Tasks Manual. | ||
742 | |||
743 | BBPATH | ||
744 | Used by BitBake to locate ``.bbclass`` and configuration files. This | ||
745 | variable is analogous to the ``PATH`` variable. | ||
746 | |||
747 | .. note:: | ||
748 | |||
749 | If you run BitBake from a directory outside of the | ||
750 | Build Directory | ||
751 | , you must be sure to set | ||
752 | BBPATH | ||
753 | to point to the Build Directory. Set the variable as you would any | ||
754 | environment variable and then run BitBake: | ||
755 | :: | ||
756 | |||
757 | $ BBPATH = "build_directory" | ||
758 | $ export BBPATH | ||
759 | $ bitbake target | ||
760 | |||
761 | |||
762 | BBSERVER | ||
763 | If defined in the BitBake environment, ``BBSERVER`` points to the | ||
764 | BitBake remote server. | ||
765 | |||
766 | Use the following format to export the variable to the BitBake | ||
767 | environment: | ||
768 | :: | ||
769 | |||
770 | export BBSERVER=localhost:$port | ||
771 | |||
772 | By default, ``BBSERVER`` also appears in | ||
773 | :term:`bitbake:BB_HASHBASE_WHITELIST`. | ||
774 | Consequently, ``BBSERVER`` is excluded from checksum and dependency | ||
775 | data. | ||
776 | |||
777 | BINCONFIG | ||
778 | When inheriting the | ||
779 | :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class, | ||
780 | this variable specifies binary configuration scripts to disable in | ||
781 | favor of using ``pkg-config`` to query the information. The | ||
782 | ``binconfig-disabled`` class will modify the specified scripts to | ||
783 | return an error so that calls to them can be easily found and | ||
784 | replaced. | ||
785 | |||
786 | To add multiple scripts, separate them by spaces. Here is an example | ||
787 | from the ``libpng`` recipe: | ||
788 | :: | ||
789 | |||
790 | BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" | ||
791 | |||
792 | BINCONFIG_GLOB | ||
793 | When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, | ||
794 | this variable specifies a wildcard for configuration scripts that | ||
795 | need editing. The scripts are edited to correct any paths that have | ||
796 | been set up during compilation so that they are correct for use when | ||
797 | installed into the sysroot and called by the build processes of other | ||
798 | recipes. | ||
799 | |||
800 | .. note:: | ||
801 | |||
802 | The | ||
803 | BINCONFIG_GLOB | ||
804 | variable uses | ||
805 | shell globbing | ||
806 | , which is recognition and expansion of wildcards during pattern | ||
807 | matching. Shell globbing is very similar to | ||
808 | fnmatch | ||
809 | and | ||
810 | glob | ||
811 | . | ||
812 | |||
813 | For more information on how this variable works, see | ||
814 | ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`. | ||
815 | You can also find general | ||
816 | information on the class in the | ||
817 | ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. | ||
818 | |||
819 | BP | ||
820 | The base recipe name and version but without any special recipe name | ||
821 | suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is | ||
822 | comprised of the following: | ||
823 | :: | ||
824 | |||
825 | ${BPN}-${PV} | ||
826 | |||
827 | BPN | ||
828 | This variable is a version of the :term:`PN` variable with | ||
829 | common prefixes and suffixes removed, such as ``nativesdk-``, | ||
830 | ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``. | ||
831 | The exact lists of prefixes and suffixes removed are specified by the | ||
832 | :term:`MLPREFIX` and | ||
833 | :term:`SPECIAL_PKGSUFFIX` variables, | ||
834 | respectively. | ||
835 | |||
836 | BUGTRACKER | ||
837 | Specifies a URL for an upstream bug tracking website for a recipe. | ||
838 | The OpenEmbedded build system does not use this variable. Rather, the | ||
839 | variable is a useful pointer in case a bug in the software being | ||
840 | built needs to be manually reported. | ||
841 | |||
842 | BUILD_ARCH | ||
843 | Specifies the architecture of the build host (e.g. ``i686``). The | ||
844 | OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the | ||
845 | machine name reported by the ``uname`` command. | ||
846 | |||
847 | BUILD_AS_ARCH | ||
848 | Specifies the architecture-specific assembler flags for the build | ||
849 | host. By default, the value of ``BUILD_AS_ARCH`` is empty. | ||
850 | |||
851 | BUILD_CC_ARCH | ||
852 | Specifies the architecture-specific C compiler flags for the build | ||
853 | host. By default, the value of ``BUILD_CC_ARCH`` is empty. | ||
854 | |||
855 | BUILD_CCLD | ||
856 | Specifies the linker command to be used for the build host when the C | ||
857 | compiler is being used as the linker. By default, ``BUILD_CCLD`` | ||
858 | points to GCC and passes as arguments the value of | ||
859 | :term:`BUILD_CC_ARCH`, assuming | ||
860 | ``BUILD_CC_ARCH`` is set. | ||
861 | |||
862 | BUILD_CFLAGS | ||
863 | Specifies the flags to pass to the C compiler when building for the | ||
864 | build host. When building in the ``-native`` context, | ||
865 | :term:`CFLAGS` is set to the value of this variable by | ||
866 | default. | ||
867 | |||
868 | BUILD_CPPFLAGS | ||
869 | Specifies the flags to pass to the C preprocessor (i.e. to both the C | ||
870 | and the C++ compilers) when building for the build host. When | ||
871 | building in the ``-native`` context, :term:`CPPFLAGS` | ||
872 | is set to the value of this variable by default. | ||
873 | |||
874 | BUILD_CXXFLAGS | ||
875 | Specifies the flags to pass to the C++ compiler when building for the | ||
876 | build host. When building in the ``-native`` context, | ||
877 | :term:`CXXFLAGS` is set to the value of this variable | ||
878 | by default. | ||
879 | |||
880 | BUILD_FC | ||
881 | Specifies the Fortran compiler command for the build host. By | ||
882 | default, ``BUILD_FC`` points to Gfortran and passes as arguments the | ||
883 | value of :term:`BUILD_CC_ARCH`, assuming | ||
884 | ``BUILD_CC_ARCH`` is set. | ||
885 | |||
886 | BUILD_LD | ||
887 | Specifies the linker command for the build host. By default, | ||
888 | ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments | ||
889 | the value of :term:`BUILD_LD_ARCH`, assuming | ||
890 | ``BUILD_LD_ARCH`` is set. | ||
891 | |||
892 | BUILD_LD_ARCH | ||
893 | Specifies architecture-specific linker flags for the build host. By | ||
894 | default, the value of ``BUILD_LD_ARCH`` is empty. | ||
895 | |||
896 | BUILD_LDFLAGS | ||
897 | Specifies the flags to pass to the linker when building for the build | ||
898 | host. When building in the ``-native`` context, | ||
899 | :term:`LDFLAGS` is set to the value of this variable | ||
900 | by default. | ||
901 | |||
902 | BUILD_OPTIMIZATION | ||
903 | Specifies the optimization flags passed to the C compiler when | ||
904 | building for the build host or the SDK. The flags are passed through | ||
905 | the :term:`BUILD_CFLAGS` and | ||
906 | :term:`BUILDSDK_CFLAGS` default values. | ||
907 | |||
908 | The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 | ||
909 | -pipe". | ||
910 | |||
911 | BUILD_OS | ||
912 | Specifies the operating system in use on the build host (e.g. | ||
913 | "linux"). The OpenEmbedded build system sets the value of | ||
914 | ``BUILD_OS`` from the OS reported by the ``uname`` command - the | ||
915 | first word, converted to lower-case characters. | ||
916 | |||
917 | BUILD_PREFIX | ||
918 | The toolchain binary prefix used for native recipes. The OpenEmbedded | ||
919 | build system uses the ``BUILD_PREFIX`` value to set the | ||
920 | :term:`TARGET_PREFIX` when building for | ||
921 | ``native`` recipes. | ||
922 | |||
923 | BUILD_STRIP | ||
924 | Specifies the command to be used to strip debugging symbols from | ||
925 | binaries produced for the build host. By default, ``BUILD_STRIP`` | ||
926 | points to | ||
927 | ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. | ||
928 | |||
929 | BUILD_SYS | ||
930 | Specifies the system, including the architecture and the operating | ||
931 | system, to use when building for the build host (i.e. when building | ||
932 | ``native`` recipes). | ||
933 | |||
934 | The OpenEmbedded build system automatically sets this variable based | ||
935 | on :term:`BUILD_ARCH`, | ||
936 | :term:`BUILD_VENDOR`, and | ||
937 | :term:`BUILD_OS`. You do not need to set the | ||
938 | ``BUILD_SYS`` variable yourself. | ||
939 | |||
940 | BUILD_VENDOR | ||
941 | Specifies the vendor name to use when building for the build host. | ||
942 | The default value is an empty string (""). | ||
943 | |||
944 | BUILDDIR | ||
945 | Points to the location of the :term:`Build Directory`. | ||
946 | You can define this directory indirectly through the | ||
947 | ````` <#structure-core-script>`__ script by passing in a Build | ||
948 | Directory path when you run the script. If you run the script and do | ||
949 | not provide a Build Directory path, the ``BUILDDIR`` defaults to | ||
950 | ``build`` in the current directory. | ||
951 | |||
952 | BUILDHISTORY_COMMIT | ||
953 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
954 | class, this variable specifies whether or not to commit the build | ||
955 | history output in a local Git repository. If set to "1", this local | ||
956 | repository will be maintained automatically by the ``buildhistory`` | ||
957 | class and a commit will be created on every build for changes to each | ||
958 | top-level subdirectory of the build history output (images, packages, | ||
959 | and sdk). If you want to track changes to build history over time, | ||
960 | you should set this value to "1". | ||
961 | |||
962 | By default, the ``buildhistory`` class does not commit the build | ||
963 | history output in a local Git repository: | ||
964 | :: | ||
965 | |||
966 | BUILDHISTORY_COMMIT ?= "0" | ||
967 | |||
968 | BUILDHISTORY_COMMIT_AUTHOR | ||
969 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
970 | class, this variable specifies the author to use for each Git commit. | ||
971 | In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the | ||
972 | :term:`BUILDHISTORY_COMMIT` variable must | ||
973 | be set to "1". | ||
974 | |||
975 | Git requires that the value you provide for the | ||
976 | ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name | ||
977 | email@host". Providing an email address or host that is not valid | ||
978 | does not produce an error. | ||
979 | |||
980 | By default, the ``buildhistory`` class sets the variable as follows: | ||
981 | :: | ||
982 | |||
983 | BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" | ||
984 | |||
985 | BUILDHISTORY_DIR | ||
986 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
987 | class, this variable specifies the directory in which build history | ||
988 | information is kept. For more information on how the variable works, | ||
989 | see the ``buildhistory.class``. | ||
990 | |||
991 | By default, the ``buildhistory`` class sets the directory as follows: | ||
992 | :: | ||
993 | |||
994 | BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" | ||
995 | |||
996 | BUILDHISTORY_FEATURES | ||
997 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
998 | class, this variable specifies the build history features to be | ||
999 | enabled. For more information on how build history works, see the | ||
1000 | ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`" | ||
1001 | section in the Yocto Project Development Tasks Manual. | ||
1002 | |||
1003 | You can specify these features in the form of a space-separated list: | ||
1004 | |||
1005 | - *image:* Analysis of the contents of images, which includes the | ||
1006 | list of installed packages among other things. | ||
1007 | |||
1008 | - *package:* Analysis of the contents of individual packages. | ||
1009 | |||
1010 | - *sdk:* Analysis of the contents of the software development kit | ||
1011 | (SDK). | ||
1012 | |||
1013 | - *task:* Save output file signatures for | ||
1014 | :ref:`shared state <overview-manual/overview-manual-concepts:shared state cache>` | ||
1015 | (sstate) tasks. | ||
1016 | This saves one file per task and lists the SHA-256 checksums for | ||
1017 | each file staged (i.e. the output of the task). | ||
1018 | |||
1019 | By default, the ``buildhistory`` class enables the following | ||
1020 | features: | ||
1021 | :: | ||
1022 | |||
1023 | BUILDHISTORY_FEATURES ?= "image package sdk" | ||
1024 | |||
1025 | BUILDHISTORY_IMAGE_FILES | ||
1026 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
1027 | class, this variable specifies a list of paths to files copied from | ||
1028 | the image contents into the build history directory under an | ||
1029 | "image-files" directory in the directory for the image, so that you | ||
1030 | can track the contents of each file. The default is to copy | ||
1031 | ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for | ||
1032 | changes in user and group entries. You can modify the list to include | ||
1033 | any file. Specifying an invalid path does not produce an error. | ||
1034 | Consequently, you can include files that might not always be present. | ||
1035 | |||
1036 | By default, the ``buildhistory`` class provides paths to the | ||
1037 | following files: | ||
1038 | :: | ||
1039 | |||
1040 | BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" | ||
1041 | |||
1042 | BUILDHISTORY_PUSH_REPO | ||
1043 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
1044 | class, this variable optionally specifies a remote repository to | ||
1045 | which build history pushes Git changes. In order for | ||
1046 | ``BUILDHISTORY_PUSH_REPO`` to work, | ||
1047 | :term:`BUILDHISTORY_COMMIT` must be set to | ||
1048 | "1". | ||
1049 | |||
1050 | The repository should correspond to a remote address that specifies a | ||
1051 | repository as understood by Git, or alternatively to a remote name | ||
1052 | that you have set up manually using ``git remote`` within the local | ||
1053 | repository. | ||
1054 | |||
1055 | By default, the ``buildhistory`` class sets the variable as follows: | ||
1056 | :: | ||
1057 | |||
1058 | BUILDHISTORY_PUSH_REPO ?= "" | ||
1059 | |||
1060 | BUILDSDK_CFLAGS | ||
1061 | Specifies the flags to pass to the C compiler when building for the | ||
1062 | SDK. When building in the ``nativesdk-`` context, | ||
1063 | :term:`CFLAGS` is set to the value of this variable by | ||
1064 | default. | ||
1065 | |||
1066 | BUILDSDK_CPPFLAGS | ||
1067 | Specifies the flags to pass to the C pre-processor (i.e. to both the | ||
1068 | C and the C++ compilers) when building for the SDK. When building in | ||
1069 | the ``nativesdk-`` context, :term:`CPPFLAGS` is set | ||
1070 | to the value of this variable by default. | ||
1071 | |||
1072 | BUILDSDK_CXXFLAGS | ||
1073 | Specifies the flags to pass to the C++ compiler when building for the | ||
1074 | SDK. When building in the ``nativesdk-`` context, | ||
1075 | :term:`CXXFLAGS` is set to the value of this variable | ||
1076 | by default. | ||
1077 | |||
1078 | BUILDSDK_LDFLAGS | ||
1079 | Specifies the flags to pass to the linker when building for the SDK. | ||
1080 | When building in the ``nativesdk-`` context, | ||
1081 | :term:`LDFLAGS` is set to the value of this variable | ||
1082 | by default. | ||
1083 | |||
1084 | BUILDSTATS_BASE | ||
1085 | Points to the location of the directory that holds build statistics | ||
1086 | when you use and enable the | ||
1087 | :ref:`buildstats <ref-classes-buildstats>` class. The | ||
1088 | ``BUILDSTATS_BASE`` directory defaults to | ||
1089 | ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. | ||
1090 | |||
1091 | BUSYBOX_SPLIT_SUID | ||
1092 | For the BusyBox recipe, specifies whether to split the output | ||
1093 | executable file into two parts: one for features that require | ||
1094 | ``setuid root``, and one for the remaining features (i.e. those that | ||
1095 | do not require ``setuid root``). | ||
1096 | |||
1097 | The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in | ||
1098 | splitting the output executable file. Set the variable to "0" to get | ||
1099 | a single output executable file. | ||
1100 | |||
1101 | CACHE | ||
1102 | Specifies the directory BitBake uses to store a cache of the | ||
1103 | :term:`Metadata` so it does not need to be parsed every time | ||
1104 | BitBake is started. | ||
1105 | |||
1106 | CC | ||
1107 | The minimal command and arguments used to run the C compiler. | ||
1108 | |||
1109 | CFLAGS | ||
1110 | Specifies the flags to pass to the C compiler. This variable is | ||
1111 | exported to an environment variable and thus made visible to the | ||
1112 | software being built during the compilation step. | ||
1113 | |||
1114 | Default initialization for ``CFLAGS`` varies depending on what is | ||
1115 | being built: | ||
1116 | |||
1117 | - :term:`TARGET_CFLAGS` when building for the | ||
1118 | target | ||
1119 | |||
1120 | - :term:`BUILD_CFLAGS` when building for the | ||
1121 | build host (i.e. ``-native``) | ||
1122 | |||
1123 | - :term:`BUILDSDK_CFLAGS` when building for | ||
1124 | an SDK (i.e. ``nativesdk-``) | ||
1125 | |||
1126 | CLASSOVERRIDE | ||
1127 | An internal variable specifying the special class override that | ||
1128 | should currently apply (e.g. "class-target", "class-native", and so | ||
1129 | forth). The classes that use this variable (e.g. | ||
1130 | :ref:`native <ref-classes-native>`, | ||
1131 | :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the | ||
1132 | variable to appropriate values. | ||
1133 | |||
1134 | .. note:: | ||
1135 | |||
1136 | CLASSOVERRIDE | ||
1137 | gets its default "class-target" value from the | ||
1138 | bitbake.conf | ||
1139 | file. | ||
1140 | |||
1141 | As an example, the following override allows you to install extra | ||
1142 | files, but only when building for the target: | ||
1143 | :: | ||
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 | ||
1150 | "native" when building for the build host, and to "other" when not | ||
1151 | building for the build host: | ||
1152 | :: | ||
1153 | |||
1154 | FOO_class-native = "native" | ||
1155 | FOO = "other" | ||
1156 | |||
1157 | The underlying mechanism behind ``CLASSOVERRIDE`` is simply | ||
1158 | that it is included in the default value of | ||
1159 | :term:`OVERRIDES`. | ||
1160 | |||
1161 | CLEANBROKEN | ||
1162 | If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the | ||
1163 | ``make clean`` command does not work for the software being built. | ||
1164 | Consequently, the OpenEmbedded build system will not try to run | ||
1165 | ``make clean`` during the :ref:`ref-tasks-configure` | ||
1166 | task, which is the default behavior. | ||
1167 | |||
1168 | COMBINED_FEATURES | ||
1169 | Provides a list of hardware features that are enabled in both | ||
1170 | :term:`MACHINE_FEATURES` and | ||
1171 | :term:`DISTRO_FEATURES`. This select list of | ||
1172 | features contains features that make sense to be controlled both at | ||
1173 | the machine and distribution configuration level. For example, the | ||
1174 | "bluetooth" feature requires hardware support but should also be | ||
1175 | optional at the distribution level, in case the hardware supports | ||
1176 | Bluetooth but you do not ever intend to use it. | ||
1177 | |||
1178 | COMMON_LICENSE_DIR | ||
1179 | Points to ``meta/files/common-licenses`` in the | ||
1180 | :term:`Source Directory`, which is where generic license | ||
1181 | files reside. | ||
1182 | |||
1183 | COMPATIBLE_HOST | ||
1184 | A regular expression that resolves to one or more hosts (when the | ||
1185 | recipe is native) or one or more targets (when the recipe is | ||
1186 | non-native) with which a recipe is compatible. The regular expression | ||
1187 | is matched against :term:`HOST_SYS`. You can use the | ||
1188 | variable to stop recipes from being built for classes of systems with | ||
1189 | which the recipes are not compatible. Stopping these builds is | ||
1190 | particularly useful with kernels. The variable also helps to increase | ||
1191 | parsing speed since the build system skips parsing recipes not | ||
1192 | compatible with the current system. | ||
1193 | |||
1194 | COMPATIBLE_MACHINE | ||
1195 | A regular expression that resolves to one or more target machines | ||
1196 | with which a recipe is compatible. The regular expression is matched | ||
1197 | against :term:`MACHINEOVERRIDES`. You can use | ||
1198 | the variable to stop recipes from being built for machines with which | ||
1199 | the recipes are not compatible. Stopping these builds is particularly | ||
1200 | useful with kernels. The variable also helps to increase parsing | ||
1201 | speed since the build system skips parsing recipes not compatible | ||
1202 | with the current machine. | ||
1203 | |||
1204 | COMPLEMENTARY_GLOB | ||
1205 | Defines wildcards to match when installing a list of complementary | ||
1206 | packages for all the packages explicitly (or implicitly) installed in | ||
1207 | an image. | ||
1208 | |||
1209 | .. note:: | ||
1210 | |||
1211 | The | ||
1212 | COMPLEMENTARY_GLOB | ||
1213 | variable uses Unix filename pattern matching ( | ||
1214 | fnmatch | ||
1215 | ), which is similar to the Unix style pathname pattern expansion ( | ||
1216 | glob | ||
1217 | ). | ||
1218 | |||
1219 | The resulting list of complementary packages is associated with an | ||
1220 | item that can be added to | ||
1221 | :term:`IMAGE_FEATURES`. An example usage of | ||
1222 | this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES`` | ||
1223 | will install -dev packages (containing headers and other development | ||
1224 | files) for every package in the image. | ||
1225 | |||
1226 | To add a new feature item pointing to a wildcard, use a variable flag | ||
1227 | to specify the feature item name and use the value to specify the | ||
1228 | wildcard. Here is an example: | ||
1229 | :: | ||
1230 | |||
1231 | COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' | ||
1232 | |||
1233 | COMPONENTS_DIR | ||
1234 | Stores sysroot components for each recipe. The OpenEmbedded build | ||
1235 | system uses ``COMPONENTS_DIR`` when constructing recipe-specific | ||
1236 | sysroots for other recipes. | ||
1237 | |||
1238 | The default is | ||
1239 | "``${``\ :term:`STAGING_DIR`\ ``}-components``." | ||
1240 | (i.e. | ||
1241 | "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). | ||
1242 | |||
1243 | CONF_VERSION | ||
1244 | Tracks the version of the local configuration file (i.e. | ||
1245 | ``local.conf``). The value for ``CONF_VERSION`` increments each time | ||
1246 | ``build/conf/`` compatibility changes. | ||
1247 | |||
1248 | CONFFILES | ||
1249 | Identifies editable or configurable files that are part of a package. | ||
1250 | If the Package Management System (PMS) is being used to update | ||
1251 | packages on the target system, it is possible that configuration | ||
1252 | files you have changed after the original installation and that you | ||
1253 | now want to remain unchanged are overwritten. In other words, | ||
1254 | editable files might exist in the package that you do not want reset | ||
1255 | as part of the package update process. You can use the ``CONFFILES`` | ||
1256 | variable to list the files in the package that you wish to prevent | ||
1257 | the PMS from overwriting during this update process. | ||
1258 | |||
1259 | To use the ``CONFFILES`` variable, provide a package name override | ||
1260 | that identifies the resulting package. Then, provide a | ||
1261 | space-separated list of files. Here is an example: | ||
1262 | :: | ||
1263 | |||
1264 | CONFFILES_${PN} += "${sysconfdir}/file1 \ | ||
1265 | ${sysconfdir}/file2 ${sysconfdir}/file3" | ||
1266 | |||
1267 | A relationship exists between the ``CONFFILES`` and ``FILES`` | ||
1268 | variables. The files listed within ``CONFFILES`` must be a subset of | ||
1269 | the files listed within ``FILES``. Because the configuration files | ||
1270 | you provide with ``CONFFILES`` are simply being identified so that | ||
1271 | the PMS will not overwrite them, it makes sense that the files must | ||
1272 | already be included as part of the package through the ``FILES`` | ||
1273 | variable. | ||
1274 | |||
1275 | .. note:: | ||
1276 | |||
1277 | When specifying paths as part of the | ||
1278 | CONFFILES | ||
1279 | variable, it is good practice to use appropriate path variables. | ||
1280 | For example, | ||
1281 | ${sysconfdir} | ||
1282 | rather than | ||
1283 | /etc | ||
1284 | or | ||
1285 | ${bindir} | ||
1286 | rather than | ||
1287 | /usr/bin | ||
1288 | . You can find a list of these variables at the top of the | ||
1289 | meta/conf/bitbake.conf | ||
1290 | file in the | ||
1291 | Source Directory | ||
1292 | . | ||
1293 | |||
1294 | CONFIG_INITRAMFS_SOURCE | ||
1295 | Identifies the initial RAM filesystem (initramfs) source files. The | ||
1296 | OpenEmbedded build system receives and uses this kernel Kconfig | ||
1297 | variable as an environment variable. By default, the variable is set | ||
1298 | to null (""). | ||
1299 | |||
1300 | The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive | ||
1301 | with a ``.cpio`` suffix or a space-separated list of directories and | ||
1302 | files for building the initramfs image. A cpio archive should contain | ||
1303 | a filesystem archive to be used as an initramfs image. Directories | ||
1304 | should contain a filesystem layout to be included in the initramfs | ||
1305 | image. Files should contain entries according to the format described | ||
1306 | by the ``usr/gen_init_cpio`` program in the kernel tree. | ||
1307 | |||
1308 | If you specify multiple directories and files, the initramfs image | ||
1309 | will be the aggregate of all of them. | ||
1310 | |||
1311 | For information on creating an initramfs, see the | ||
1312 | ":ref:`building-an-initramfs-image`" section | ||
1313 | in the Yocto Project Development Tasks Manual. | ||
1314 | |||
1315 | CONFIG_SITE | ||
1316 | A list of files that contains ``autoconf`` test results relevant to | ||
1317 | the current build. This variable is used by the Autotools utilities | ||
1318 | when running ``configure``. | ||
1319 | |||
1320 | CONFIGURE_FLAGS | ||
1321 | The minimal arguments for GNU configure. | ||
1322 | |||
1323 | CONFLICT_DISTRO_FEATURES | ||
1324 | When inheriting the | ||
1325 | :ref:`distro_features_check <ref-classes-distro_features_check>` | ||
1326 | class, this variable identifies distribution features that would be | ||
1327 | in conflict should the recipe be built. In other words, if the | ||
1328 | ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also | ||
1329 | appears in ``DISTRO_FEATURES`` within the current configuration, an | ||
1330 | error occurs and the build stops. | ||
1331 | |||
1332 | COPYLEFT_LICENSE_EXCLUDE | ||
1333 | A space-separated list of licenses to exclude from the source | ||
1334 | archived by the :ref:`archiver <ref-classes-archiver>` class. In | ||
1335 | other words, if a license in a recipe's | ||
1336 | :term:`LICENSE` value is in the value of | ||
1337 | ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the | ||
1338 | class. | ||
1339 | |||
1340 | .. note:: | ||
1341 | |||
1342 | The | ||
1343 | COPYLEFT_LICENSE_EXCLUDE | ||
1344 | variable takes precedence over the | ||
1345 | COPYLEFT_LICENSE_INCLUDE | ||
1346 | variable. | ||
1347 | |||
1348 | The default value, which is "CLOSED Proprietary", for | ||
1349 | ``COPYLEFT_LICENSE_EXCLUDE`` is set by the | ||
1350 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1351 | is inherited by the ``archiver`` class. | ||
1352 | |||
1353 | COPYLEFT_LICENSE_INCLUDE | ||
1354 | A space-separated list of licenses to include in the source archived | ||
1355 | by the :ref:`archiver <ref-classes-archiver>` class. In other | ||
1356 | words, if a license in a recipe's :term:`LICENSE` | ||
1357 | value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its | ||
1358 | source is archived by the class. | ||
1359 | |||
1360 | The default value is set by the | ||
1361 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1362 | is inherited by the ``archiver`` class. The default value includes | ||
1363 | "GPL*", "LGPL*", and "AGPL*". | ||
1364 | |||
1365 | COPYLEFT_PN_EXCLUDE | ||
1366 | A list of recipes to exclude in the source archived by the | ||
1367 | :ref:`archiver <ref-classes-archiver>` class. The | ||
1368 | ``COPYLEFT_PN_EXCLUDE`` variable overrides the license inclusion and | ||
1369 | exclusion caused through the | ||
1370 | :term:`COPYLEFT_LICENSE_INCLUDE` and | ||
1371 | :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1372 | variables, respectively. | ||
1373 | |||
1374 | The default value, which is "" indicating to not explicitly exclude | ||
1375 | any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the | ||
1376 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1377 | is inherited by the ``archiver`` class. | ||
1378 | |||
1379 | COPYLEFT_PN_INCLUDE | ||
1380 | A list of recipes to include in the source archived by the | ||
1381 | :ref:`archiver <ref-classes-archiver>` class. The | ||
1382 | ``COPYLEFT_PN_INCLUDE`` variable overrides the license inclusion and | ||
1383 | exclusion caused through the | ||
1384 | :term:`COPYLEFT_LICENSE_INCLUDE` and | ||
1385 | :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1386 | variables, respectively. | ||
1387 | |||
1388 | The default value, which is "" indicating to not explicitly include | ||
1389 | any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the | ||
1390 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1391 | is inherited by the ``archiver`` class. | ||
1392 | |||
1393 | COPYLEFT_RECIPE_TYPES | ||
1394 | A space-separated list of recipe types to include in the source | ||
1395 | archived by the :ref:`archiver <ref-classes-archiver>` class. | ||
1396 | Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``, | ||
1397 | ``crosssdk``, and ``cross-canadian``. | ||
1398 | |||
1399 | The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` | ||
1400 | is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` | ||
1401 | class, which is inherited by the ``archiver`` class. | ||
1402 | |||
1403 | COPY_LIC_DIRS | ||
1404 | If set to "1" along with the | ||
1405 | :term:`COPY_LIC_MANIFEST` variable, the | ||
1406 | OpenEmbedded build system copies into the image the license files, | ||
1407 | which are located in ``/usr/share/common-licenses``, for each | ||
1408 | package. The license files are placed in directories within the image | ||
1409 | itself during build time. | ||
1410 | |||
1411 | .. note:: | ||
1412 | |||
1413 | The | ||
1414 | COPY_LIC_DIRS | ||
1415 | does not offer a path for adding licenses for newly installed | ||
1416 | packages to an image, which might be most suitable for read-only | ||
1417 | filesystems that cannot be upgraded. See the | ||
1418 | LICENSE_CREATE_PACKAGE | ||
1419 | variable for additional information. You can also reference the " | ||
1420 | Providing License Text | ||
1421 | " section in the Yocto Project Development Tasks Manual for | ||
1422 | information on providing license text. | ||
1423 | |||
1424 | COPY_LIC_MANIFEST | ||
1425 | If set to "1", the OpenEmbedded build system copies the license | ||
1426 | manifest for the image to | ||
1427 | ``/usr/share/common-licenses/license.manifest`` within the image | ||
1428 | itself during build time. | ||
1429 | |||
1430 | .. note:: | ||
1431 | |||
1432 | The | ||
1433 | COPY_LIC_MANIFEST | ||
1434 | does not offer a path for adding licenses for newly installed | ||
1435 | packages to an image, which might be most suitable for read-only | ||
1436 | filesystems that cannot be upgraded. See the | ||
1437 | LICENSE_CREATE_PACKAGE | ||
1438 | variable for additional information. You can also reference the " | ||
1439 | Providing License Text | ||
1440 | " section in the Yocto Project Development Tasks Manual for | ||
1441 | information on providing license text. | ||
1442 | |||
1443 | CORE_IMAGE_EXTRA_INSTALL | ||
1444 | Specifies the list of packages to be added to the image. You should | ||
1445 | only set this variable in the ``local.conf`` configuration file found | ||
1446 | in the :term:`Build Directory`. | ||
1447 | |||
1448 | This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer | ||
1449 | supported. | ||
1450 | |||
1451 | COREBASE | ||
1452 | Specifies the parent directory of the OpenEmbedded-Core Metadata | ||
1453 | layer (i.e. ``meta``). | ||
1454 | |||
1455 | It is an important distinction that ``COREBASE`` points to the parent | ||
1456 | of this layer and not the layer itself. Consider an example where you | ||
1457 | have cloned the Poky Git repository and retained the ``poky`` name | ||
1458 | for your local copy of the repository. In this case, ``COREBASE`` | ||
1459 | points to the ``poky`` folder because it is the parent directory of | ||
1460 | the ``poky/meta`` layer. | ||
1461 | |||
1462 | COREBASE_FILES | ||
1463 | Lists files from the :term:`COREBASE` directory that | ||
1464 | should be copied other than the layers listed in the | ||
1465 | ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for | ||
1466 | the purpose of copying metadata from the OpenEmbedded build system | ||
1467 | into the extensible SDK. | ||
1468 | |||
1469 | Explicitly listing files in ``COREBASE`` is needed because it | ||
1470 | typically contains build directories and other files that should not | ||
1471 | normally be copied into the extensible SDK. Consequently, the value | ||
1472 | of ``COREBASE_FILES`` is used in order to only copy the files that | ||
1473 | are actually needed. | ||
1474 | |||
1475 | CPP | ||
1476 | The minimal command and arguments used to run the C preprocessor. | ||
1477 | |||
1478 | CPPFLAGS | ||
1479 | Specifies the flags to pass to the C pre-processor (i.e. to both the | ||
1480 | C and the C++ compilers). This variable is exported to an environment | ||
1481 | variable and thus made visible to the software being built during the | ||
1482 | compilation step. | ||
1483 | |||
1484 | Default initialization for ``CPPFLAGS`` varies depending on what is | ||
1485 | being built: | ||
1486 | |||
1487 | - :term:`TARGET_CPPFLAGS` when building for | ||
1488 | the target | ||
1489 | |||
1490 | - :term:`BUILD_CPPFLAGS` when building for the | ||
1491 | build host (i.e. ``-native``) | ||
1492 | |||
1493 | - :term:`BUILDSDK_CPPFLAGS` when building | ||
1494 | for an SDK (i.e. ``nativesdk-``) | ||
1495 | |||
1496 | CROSS_COMPILE | ||
1497 | The toolchain binary prefix for the target tools. The | ||
1498 | ``CROSS_COMPILE`` variable is the same as the | ||
1499 | :term:`TARGET_PREFIX` variable. | ||
1500 | |||
1501 | .. note:: | ||
1502 | |||
1503 | The OpenEmbedded build system sets the | ||
1504 | CROSS_COMPILE | ||
1505 | variable only in certain contexts (e.g. when building for kernel | ||
1506 | and kernel module recipes). | ||
1507 | |||
1508 | CVSDIR | ||
1509 | The directory in which files checked out under the CVS system are | ||
1510 | stored. | ||
1511 | |||
1512 | CXX | ||
1513 | The minimal command and arguments used to run the C++ compiler. | ||
1514 | |||
1515 | CXXFLAGS | ||
1516 | Specifies the flags to pass to the C++ compiler. This variable is | ||
1517 | exported to an environment variable and thus made visible to the | ||
1518 | software being built during the compilation step. | ||
1519 | |||
1520 | Default initialization for ``CXXFLAGS`` varies depending on what is | ||
1521 | being built: | ||
1522 | |||
1523 | - :term:`TARGET_CXXFLAGS` when building for | ||
1524 | the target | ||
1525 | |||
1526 | - :term:`BUILD_CXXFLAGS` when building for the | ||
1527 | build host (i.e. ``-native``) | ||
1528 | |||
1529 | - :term:`BUILDSDK_CXXFLAGS` when building | ||
1530 | for an SDK (i.e. ``nativesdk-``) | ||
1531 | |||
1532 | D | ||
1533 | The destination directory. The location in the :term:`Build Directory` | ||
1534 | where components are installed by the | ||
1535 | :ref:`ref-tasks-install` task. This location defaults | ||
1536 | to: | ||
1537 | :: | ||
1538 | |||
1539 | ${WORKDIR}/image | ||
1540 | |||
1541 | .. note:: | ||
1542 | |||
1543 | Tasks that read from or write to this directory should run under | ||
1544 | fakeroot | ||
1545 | . | ||
1546 | |||
1547 | DATE | ||
1548 | The date the build was started. Dates appear using the year, month, | ||
1549 | and day (YMD) format (e.g. "20150209" for February 9th, 2015). | ||
1550 | |||
1551 | DATETIME | ||
1552 | The date and time on which the current build started. The format is | ||
1553 | suitable for timestamps. | ||
1554 | |||
1555 | DEBIAN_NOAUTONAME | ||
1556 | When the :ref:`debian <ref-classes-debian>` class is inherited, | ||
1557 | which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a | ||
1558 | particular package should not be renamed according to Debian library | ||
1559 | package naming. You must use the package name as an override when you | ||
1560 | set this variable. Here is an example from the ``fontconfig`` recipe: | ||
1561 | :: | ||
1562 | |||
1563 | DEBIAN_NOAUTONAME_fontconfig-utils = "1" | ||
1564 | |||
1565 | DEBIANNAME | ||
1566 | When the :ref:`debian <ref-classes-debian>` class is inherited, | ||
1567 | which is the default behavior, ``DEBIANNAME`` allows you to override | ||
1568 | the library name for an individual package. Overriding the library | ||
1569 | name in these cases is rare. You must use the package name as an | ||
1570 | override when you set this variable. Here is an example from the | ||
1571 | ``dbus`` recipe: | ||
1572 | :: | ||
1573 | |||
1574 | DEBIANNAME_${PN} = "dbus-1" | ||
1575 | |||
1576 | DEBUG_BUILD | ||
1577 | Specifies to build packages with debugging information. This | ||
1578 | influences the value of the ``SELECTED_OPTIMIZATION`` variable. | ||
1579 | |||
1580 | DEBUG_OPTIMIZATION | ||
1581 | The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when | ||
1582 | compiling a system for debugging. This variable defaults to "-O | ||
1583 | -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". | ||
1584 | |||
1585 | DEFAULT_PREFERENCE | ||
1586 | Specifies a weak bias for recipe selection priority. | ||
1587 | |||
1588 | The most common usage of this is variable is to set it to "-1" within | ||
1589 | a recipe for a development version of a piece of software. Using the | ||
1590 | variable in this way causes the stable version of the recipe to build | ||
1591 | by default in the absence of ``PREFERRED_VERSION`` being used to | ||
1592 | build the development version. | ||
1593 | |||
1594 | .. note:: | ||
1595 | |||
1596 | The bias provided by | ||
1597 | DEFAULT_PREFERENCE | ||
1598 | is weak and is overridden by | ||
1599 | BBFILE_PRIORITY | ||
1600 | if that variable is different between two layers that contain | ||
1601 | different versions of the same recipe. | ||
1602 | |||
1603 | DEFAULTTUNE | ||
1604 | The default CPU and Application Binary Interface (ABI) tunings (i.e. | ||
1605 | the "tune") used by the OpenEmbedded build system. The | ||
1606 | ``DEFAULTTUNE`` helps define | ||
1607 | :term:`TUNE_FEATURES`. | ||
1608 | |||
1609 | The default tune is either implicitly or explicitly set by the | ||
1610 | machine (:term:`MACHINE`). However, you can override | ||
1611 | the setting using available tunes as defined with | ||
1612 | :term:`AVAILTUNES`. | ||
1613 | |||
1614 | DEPENDS | ||
1615 | Lists a recipe's build-time dependencies. These are dependencies on | ||
1616 | other recipes whose contents (e.g. headers and shared libraries) are | ||
1617 | needed by the recipe at build time. | ||
1618 | |||
1619 | As an example, consider a recipe ``foo`` that contains the following | ||
1620 | assignment: | ||
1621 | :: | ||
1622 | |||
1623 | DEPENDS = "bar" | ||
1624 | |||
1625 | The practical effect of the previous | ||
1626 | assignment is that all files installed by bar will be available in | ||
1627 | the appropriate staging sysroot, given by the | ||
1628 | :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the | ||
1629 | :ref:`ref-tasks-configure` task for ``foo`` runs. | ||
1630 | This mechanism is implemented by having ``do_configure`` depend on | ||
1631 | the :ref:`ref-tasks-populate_sysroot` task of | ||
1632 | each recipe listed in ``DEPENDS``, through a | ||
1633 | ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` | ||
1634 | declaration in the :ref:`base <ref-classes-base>` class. | ||
1635 | |||
1636 | .. note:: | ||
1637 | |||
1638 | It seldom is necessary to reference, for example, | ||
1639 | STAGING_DIR_HOST | ||
1640 | explicitly. The standard classes and build-related variables are | ||
1641 | configured to automatically use the appropriate staging sysroots. | ||
1642 | |||
1643 | As another example, ``DEPENDS`` can also be used to add utilities | ||
1644 | that run on the build machine during the build. For example, a recipe | ||
1645 | that makes use of a code generator built by the recipe ``codegen`` | ||
1646 | might have the following: | ||
1647 | :: | ||
1648 | |||
1649 | DEPENDS = "codegen-native" | ||
1650 | |||
1651 | For more | ||
1652 | information, see the :ref:`native <ref-classes-native>` class and | ||
1653 | the :term:`EXTRANATIVEPATH` variable. | ||
1654 | |||
1655 | .. note:: | ||
1656 | |||
1657 | - ``DEPENDS`` is a list of recipe names. Or, to be more precise, | ||
1658 | it is a list of :term:`PROVIDES` names, which | ||
1659 | usually match recipe names. Putting a package name such as | ||
1660 | "foo-dev" in ``DEPENDS`` does not make sense. Use "foo" | ||
1661 | instead, as this will put files from all the packages that make | ||
1662 | up ``foo``, which includes those from ``foo-dev``, into the | ||
1663 | sysroot. | ||
1664 | |||
1665 | - One recipe having another recipe in ``DEPENDS`` does not by | ||
1666 | itself add any runtime dependencies between the packages | ||
1667 | produced by the two recipes. However, as explained in the | ||
1668 | ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" | ||
1669 | section in the Yocto Project Overview and Concepts Manual, | ||
1670 | runtime dependencies will often be added automatically, meaning | ||
1671 | ``DEPENDS`` alone is sufficient for most recipes. | ||
1672 | |||
1673 | - Counterintuitively, ``DEPENDS`` is often necessary even for | ||
1674 | recipes that install precompiled components. For example, if | ||
1675 | ``libfoo`` is a precompiled library that links against | ||
1676 | ``libbar``, then linking against ``libfoo`` requires both | ||
1677 | ``libfoo`` and ``libbar`` to be available in the sysroot. | ||
1678 | Without a ``DEPENDS`` from the recipe that installs ``libfoo`` | ||
1679 | to the recipe that installs ``libbar``, other recipes might | ||
1680 | fail to link against ``libfoo``. | ||
1681 | |||
1682 | For information on runtime dependencies, see the | ||
1683 | :term:`RDEPENDS` variable. You can also see the | ||
1684 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | ||
1685 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | ||
1686 | BitBake User Manual for additional information on tasks and | ||
1687 | dependencies. | ||
1688 | |||
1689 | DEPLOY_DIR | ||
1690 | Points to the general area that the OpenEmbedded build system uses to | ||
1691 | place images, packages, SDKs, and other output files that are ready | ||
1692 | to be used outside of the build system. By default, this directory | ||
1693 | resides within the :term:`Build Directory` as | ||
1694 | ``${TMPDIR}/deploy``. | ||
1695 | |||
1696 | For more information on the structure of the Build Directory, see | ||
1697 | ":ref:`ref-manual/ref-structure:the build directory - \`\`build/\`\``" section. | ||
1698 | For more detail on the contents of the ``deploy`` directory, see the | ||
1699 | ":ref:`Images <images-dev-environment>`", ":ref:`Package | ||
1700 | Feeds <package-feeds-dev-environment>`", and | ||
1701 | ":ref:`sdk-dev-environment`" sections all in the | ||
1702 | Yocto Project Overview and Concepts Manual. | ||
1703 | |||
1704 | DEPLOY_DIR_DEB | ||
1705 | Points to the area that the OpenEmbedded build system uses to place | ||
1706 | Debian packages that are ready to be used outside of the build | ||
1707 | system. This variable applies only when | ||
1708 | :term:`PACKAGE_CLASSES` contains | ||
1709 | "package_deb". | ||
1710 | |||
1711 | The BitBake configuration file initially defines the | ||
1712 | ``DEPLOY_DIR_DEB`` variable as a sub-folder of | ||
1713 | :term:`DEPLOY_DIR`: | ||
1714 | :: | ||
1715 | |||
1716 | DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" | ||
1717 | |||
1718 | The :ref:`package_deb <ref-classes-package_deb>` class uses the | ||
1719 | ``DEPLOY_DIR_DEB`` variable to make sure the | ||
1720 | :ref:`ref-tasks-package_write_deb` task | ||
1721 | writes Debian packages into the appropriate folder. For more | ||
1722 | information on how packaging works, see the ":ref:`Package | ||
1723 | Feeds <package-feeds-dev-environment>`" section | ||
1724 | in the Yocto Project Overview and Concepts Manual. | ||
1725 | |||
1726 | DEPLOY_DIR_IMAGE | ||
1727 | Points to the area that the OpenEmbedded build system uses to place | ||
1728 | images and other associated output files that are ready to be | ||
1729 | deployed onto the target machine. The directory is machine-specific | ||
1730 | as it contains the ``${MACHINE}`` name. By default, this directory | ||
1731 | resides within the :term:`Build Directory` as | ||
1732 | ``${DEPLOY_DIR}/images/${MACHINE}/``. | ||
1733 | |||
1734 | For more information on the structure of the Build Directory, see | ||
1735 | ":ref:`ref-manual/ref-structure:the build directory - \`\`build/\`\``" section. | ||
1736 | For more detail on the contents of the ``deploy`` directory, see the | ||
1737 | ":ref:`Images <images-dev-environment>`" and | ||
1738 | ":ref:`sdk-dev-environment`" sections both in | ||
1739 | the Yocto Project Overview and Concepts Manual. | ||
1740 | |||
1741 | DEPLOY_DIR_IPK | ||
1742 | Points to the area that the OpenEmbedded build system uses to place | ||
1743 | IPK packages that are ready to be used outside of the build system. | ||
1744 | This variable applies only when | ||
1745 | :term:`PACKAGE_CLASSES` contains | ||
1746 | "package_ipk". | ||
1747 | |||
1748 | The BitBake configuration file initially defines this variable as a | ||
1749 | sub-folder of :term:`DEPLOY_DIR`: | ||
1750 | :: | ||
1751 | |||
1752 | DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" | ||
1753 | |||
1754 | The :ref:`package_ipk <ref-classes-package_ipk>` class uses the | ||
1755 | ``DEPLOY_DIR_IPK`` variable to make sure the | ||
1756 | :ref:`ref-tasks-package_write_ipk` task | ||
1757 | writes IPK packages into the appropriate folder. For more information | ||
1758 | on how packaging works, see the ":ref:`Package | ||
1759 | Feeds <package-feeds-dev-environment>`" section | ||
1760 | in the Yocto Project Overview and Concepts Manual. | ||
1761 | |||
1762 | DEPLOY_DIR_RPM | ||
1763 | Points to the area that the OpenEmbedded build system uses to place | ||
1764 | RPM packages that are ready to be used outside of the build system. | ||
1765 | This variable applies only when | ||
1766 | :term:`PACKAGE_CLASSES` contains | ||
1767 | "package_rpm". | ||
1768 | |||
1769 | The BitBake configuration file initially defines this variable as a | ||
1770 | sub-folder of :term:`DEPLOY_DIR`: | ||
1771 | :: | ||
1772 | |||
1773 | DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" | ||
1774 | |||
1775 | The :ref:`package_rpm <ref-classes-package_rpm>` class uses the | ||
1776 | ``DEPLOY_DIR_RPM`` variable to make sure the | ||
1777 | :ref:`ref-tasks-package_write_rpm` task | ||
1778 | writes RPM packages into the appropriate folder. For more information | ||
1779 | on how packaging works, see the ":ref:`Package | ||
1780 | Feeds <package-feeds-dev-environment>`" section | ||
1781 | in the Yocto Project Overview and Concepts Manual. | ||
1782 | |||
1783 | DEPLOY_DIR_TAR | ||
1784 | Points to the area that the OpenEmbedded build system uses to place | ||
1785 | tarballs that are ready to be used outside of the build system. This | ||
1786 | variable applies only when | ||
1787 | :term:`PACKAGE_CLASSES` contains | ||
1788 | "package_tar". | ||
1789 | |||
1790 | The BitBake configuration file initially defines this variable as a | ||
1791 | sub-folder of :term:`DEPLOY_DIR`: | ||
1792 | :: | ||
1793 | |||
1794 | DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar" | ||
1795 | |||
1796 | The :ref:`package_tar <ref-classes-package_tar>` class uses the | ||
1797 | ``DEPLOY_DIR_TAR`` variable to make sure the | ||
1798 | :ref:`ref-tasks-package_write_tar` task | ||
1799 | writes TAR packages into the appropriate folder. For more information | ||
1800 | on how packaging works, see the ":ref:`Package | ||
1801 | Feeds <package-feeds-dev-environment>`" section | ||
1802 | in the Yocto Project Overview and Concepts Manual. | ||
1803 | |||
1804 | DEPLOYDIR | ||
1805 | When inheriting the :ref:`deploy <ref-classes-deploy>` class, the | ||
1806 | ``DEPLOYDIR`` points to a temporary work area for deployed files that | ||
1807 | is set in the ``deploy`` class as follows: | ||
1808 | :: | ||
1809 | |||
1810 | DEPLOYDIR = "${WORKDIR}/deploy-${:term:`PN`}" | ||
1811 | |||
1812 | Recipes inheriting the ``deploy`` class should copy files to be | ||
1813 | deployed into ``DEPLOYDIR``, and the class will take care of copying | ||
1814 | them into :term:`DEPLOY_DIR_IMAGE` | ||
1815 | afterwards. | ||
1816 | |||
1817 | DESCRIPTION | ||
1818 | The package description used by package managers. If not set, | ||
1819 | ``DESCRIPTION`` takes the value of the :term:`SUMMARY` | ||
1820 | variable. | ||
1821 | |||
1822 | DISTRO | ||
1823 | The short name of the distribution. For information on the long name | ||
1824 | of the distribution, see the :term:`DISTRO_NAME` | ||
1825 | variable. | ||
1826 | |||
1827 | The ``DISTRO`` variable corresponds to a distribution configuration | ||
1828 | file whose root name is the same as the variable's argument and whose | ||
1829 | filename extension is ``.conf``. For example, the distribution | ||
1830 | configuration file for the Poky distribution is named ``poky.conf`` | ||
1831 | and resides in the ``meta-poky/conf/distro`` directory of the | ||
1832 | :term:`Source Directory`. | ||
1833 | |||
1834 | Within that ``poky.conf`` file, the ``DISTRO`` variable is set as | ||
1835 | follows: | ||
1836 | :: | ||
1837 | |||
1838 | DISTRO = "poky" | ||
1839 | |||
1840 | Distribution configuration files are located in a ``conf/distro`` | ||
1841 | directory within the :term:`Metadata` that contains the | ||
1842 | distribution configuration. The value for ``DISTRO`` must not contain | ||
1843 | spaces, and is typically all lower-case. | ||
1844 | |||
1845 | .. note:: | ||
1846 | |||
1847 | If the | ||
1848 | DISTRO | ||
1849 | variable is blank, a set of default configurations are used, which | ||
1850 | are specified within | ||
1851 | meta/conf/distro/defaultsetup.conf | ||
1852 | also in the Source Directory. | ||
1853 | |||
1854 | DISTRO_CODENAME | ||
1855 | Specifies a codename for the distribution being built. | ||
1856 | |||
1857 | DISTRO_EXTRA_RDEPENDS | ||
1858 | Specifies a list of distro-specific packages to add to all images. | ||
1859 | This variable takes affect through ``packagegroup-base`` so the | ||
1860 | variable only really applies to the more full-featured images that | ||
1861 | include ``packagegroup-base``. You can use this variable to keep | ||
1862 | distro policy out of generic images. As with all other distro | ||
1863 | variables, you set this variable in the distro ``.conf`` file. | ||
1864 | |||
1865 | DISTRO_EXTRA_RRECOMMENDS | ||
1866 | Specifies a list of distro-specific packages to add to all images if | ||
1867 | the packages exist. The packages might not exist or be empty (e.g. | ||
1868 | kernel modules). The list of packages are automatically installed but | ||
1869 | you can remove them. | ||
1870 | |||
1871 | DISTRO_FEATURES | ||
1872 | The software support you want in your distribution for various | ||
1873 | features. You define your distribution features in the distribution | ||
1874 | configuration file. | ||
1875 | |||
1876 | In most cases, the presence or absence of a feature in | ||
1877 | ``DISTRO_FEATURES`` is translated to the appropriate option supplied | ||
1878 | to the configure script during the | ||
1879 | :ref:`ref-tasks-configure` task for recipes that | ||
1880 | optionally support the feature. For example, specifying "x11" in | ||
1881 | ``DISTRO_FEATURES``, causes every piece of software built for the | ||
1882 | target that can optionally support X11 to have its X11 support | ||
1883 | enabled. | ||
1884 | |||
1885 | Two more examples are Bluetooth and NFS support. For a more complete | ||
1886 | list of features that ships with the Yocto Project and that you can | ||
1887 | provide with this variable, see the "`Distro | ||
1888 | Features <#ref-features-distro>`__" section. | ||
1889 | |||
1890 | DISTRO_FEATURES_BACKFILL | ||
1891 | Features to be added to ``DISTRO_FEATURES`` if not also present in | ||
1892 | ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. | ||
1893 | |||
1894 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | ||
1895 | not intended to be user-configurable. It is best to just reference | ||
1896 | the variable to see which distro features are being backfilled for | ||
1897 | all distro configurations. See the "`Feature | ||
1898 | Backfilling <#ref-features-backfill>`__" section for more | ||
1899 | information. | ||
1900 | |||
1901 | DISTRO_FEATURES_BACKFILL_CONSIDERED | ||
1902 | Features from ``DISTRO_FEATURES_BACKFILL`` that should not be | ||
1903 | backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See | ||
1904 | the "`Feature Backfilling <#ref-features-backfill>`__" section for | ||
1905 | more information. | ||
1906 | |||
1907 | DISTRO_FEATURES_DEFAULT | ||
1908 | A convenience variable that gives you the default list of distro | ||
1909 | features with the exception of any features specific to the C library | ||
1910 | (``libc``). | ||
1911 | |||
1912 | When creating a custom distribution, you might find it useful to be | ||
1913 | able to reuse the default | ||
1914 | :term:`DISTRO_FEATURES` options without the | ||
1915 | need to write out the full set. Here is an example that uses | ||
1916 | ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file: | ||
1917 | :: | ||
1918 | |||
1919 | DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" | ||
1920 | |||
1921 | DISTRO_FEATURES_FILTER_NATIVE | ||
1922 | Specifies a list of features that if present in the target | ||
1923 | :term:`DISTRO_FEATURES` value should be | ||
1924 | included in ``DISTRO_FEATURES`` when building native recipes. This | ||
1925 | variable is used in addition to the features filtered using the | ||
1926 | :term:`DISTRO_FEATURES_NATIVE` | ||
1927 | variable. | ||
1928 | |||
1929 | DISTRO_FEATURES_FILTER_NATIVESDK | ||
1930 | Specifies a list of features that if present in the target | ||
1931 | :term:`DISTRO_FEATURES` value should be | ||
1932 | included in ``DISTRO_FEATURES`` when building nativesdk recipes. This | ||
1933 | variable is used in addition to the features filtered using the | ||
1934 | :term:`DISTRO_FEATURES_NATIVESDK` | ||
1935 | variable. | ||
1936 | |||
1937 | DISTRO_FEATURES_NATIVE | ||
1938 | Specifies a list of features that should be included in | ||
1939 | :term:`DISTRO_FEATURES` when building native | ||
1940 | recipes. This variable is used in addition to the features filtered | ||
1941 | using the | ||
1942 | :term:`DISTRO_FEATURES_FILTER_NATIVE` | ||
1943 | variable. | ||
1944 | |||
1945 | DISTRO_FEATURES_NATIVESDK | ||
1946 | Specifies a list of features that should be included in | ||
1947 | :term:`DISTRO_FEATURES` when building | ||
1948 | nativesdk recipes. This variable is used in addition to the features | ||
1949 | filtered using the | ||
1950 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK` | ||
1951 | variable. | ||
1952 | |||
1953 | DISTRO_NAME | ||
1954 | The long name of the distribution. For information on the short name | ||
1955 | of the distribution, see the :term:`DISTRO` variable. | ||
1956 | |||
1957 | The ``DISTRO_NAME`` variable corresponds to a distribution | ||
1958 | configuration file whose root name is the same as the variable's | ||
1959 | argument and whose filename extension is ``.conf``. For example, the | ||
1960 | distribution configuration file for the Poky distribution is named | ||
1961 | ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory | ||
1962 | of the :term:`Source Directory`. | ||
1963 | |||
1964 | Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set | ||
1965 | as follows: | ||
1966 | :: | ||
1967 | |||
1968 | DISTRO_NAME = "Poky (Yocto Project Reference Distro)" | ||
1969 | |||
1970 | Distribution configuration files are located in a ``conf/distro`` | ||
1971 | directory within the :term:`Metadata` that contains the | ||
1972 | distribution configuration. | ||
1973 | |||
1974 | .. note:: | ||
1975 | |||
1976 | If the | ||
1977 | DISTRO_NAME | ||
1978 | variable is blank, a set of default configurations are used, which | ||
1979 | are specified within | ||
1980 | meta/conf/distro/defaultsetup.conf | ||
1981 | also in the Source Directory. | ||
1982 | |||
1983 | DISTRO_VERSION | ||
1984 | The version of the distribution. | ||
1985 | |||
1986 | DISTROOVERRIDES | ||
1987 | A colon-separated list of overrides specific to the current | ||
1988 | distribution. By default, this list includes the value of | ||
1989 | :term:`DISTRO`. | ||
1990 | |||
1991 | You can extend ``DISTROOVERRIDES`` to add extra overrides that should | ||
1992 | apply to the distribution. | ||
1993 | |||
1994 | The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it | ||
1995 | is included in the default value of | ||
1996 | :term:`OVERRIDES`. | ||
1997 | |||
1998 | DL_DIR | ||
1999 | The central download directory used by the build process to store | ||
2000 | downloads. By default, ``DL_DIR`` gets files suitable for mirroring | ||
2001 | for everything except Git repositories. If you want tarballs of Git | ||
2002 | repositories, use the | ||
2003 | :term:`BB_GENERATE_MIRROR_TARBALLS` | ||
2004 | variable. | ||
2005 | |||
2006 | You can set this directory by defining the ``DL_DIR`` variable in the | ||
2007 | ``conf/local.conf`` file. This directory is self-maintaining and you | ||
2008 | should not have to touch it. By default, the directory is | ||
2009 | ``downloads`` in the :term:`Build Directory`. | ||
2010 | :: | ||
2011 | |||
2012 | #DL_DIR ?= "${TOPDIR}/downloads" | ||
2013 | |||
2014 | To specify a different download directory, | ||
2015 | simply remove the comment from the line and provide your directory. | ||
2016 | |||
2017 | During a first build, the system downloads many different source code | ||
2018 | tarballs from various upstream projects. Downloading can take a | ||
2019 | while, particularly if your network connection is slow. Tarballs are | ||
2020 | all stored in the directory defined by ``DL_DIR`` and the build | ||
2021 | system looks there first to find source tarballs. | ||
2022 | |||
2023 | .. note:: | ||
2024 | |||
2025 | When wiping and rebuilding, you can preserve this directory to | ||
2026 | speed up this part of subsequent builds. | ||
2027 | |||
2028 | You can safely share this directory between multiple builds on the | ||
2029 | same development machine. For additional information on how the build | ||
2030 | process gets source files when working behind a firewall or proxy | ||
2031 | server, see this specific question in the | ||
2032 | "`FAQ <#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server>`__" | ||
2033 | chapter. You can also refer to the | ||
2034 | ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" | ||
2035 | Wiki page. | ||
2036 | |||
2037 | DOC_COMPRESS | ||
2038 | When inheriting the :ref:`compress_doc <ref-classes-compress_doc>` | ||
2039 | class, this variable sets the compression policy used when the | ||
2040 | OpenEmbedded build system compresses man pages and info pages. By | ||
2041 | default, the compression method used is gz (gzip). Other policies | ||
2042 | available are xz and bz2. | ||
2043 | |||
2044 | For information on policies and on how to use this variable, see the | ||
2045 | comments in the ``meta/classes/compress_doc.bbclass`` file. | ||
2046 | |||
2047 | EFI_PROVIDER | ||
2048 | When building bootable images (i.e. where ``hddimg``, ``iso``, or | ||
2049 | ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the | ||
2050 | ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The | ||
2051 | default is "grub-efi", but "systemd-boot" can be used instead. | ||
2052 | |||
2053 | See the :ref:`systemd-boot <ref-classes-systemd-boot>` and | ||
2054 | :ref:`image-live <ref-classes-image-live>` classes for more | ||
2055 | information. | ||
2056 | |||
2057 | ENABLE_BINARY_LOCALE_GENERATION | ||
2058 | Variable that controls which locales for ``glibc`` are generated | ||
2059 | during the build (useful if the target device has 64Mbytes of RAM or | ||
2060 | less). | ||
2061 | |||
2062 | ERR_REPORT_DIR | ||
2063 | When used with the :ref:`report-error <ref-classes-report-error>` | ||
2064 | class, specifies the path used for storing the debug files created by | ||
2065 | the :ref:`error reporting | ||
2066 | tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`, which | ||
2067 | allows you to submit build errors you encounter to a central | ||
2068 | database. By default, the value of this variable is | ||
2069 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. | ||
2070 | |||
2071 | You can set ``ERR_REPORT_DIR`` to the path you want the error | ||
2072 | reporting tool to store the debug files as follows in your | ||
2073 | ``local.conf`` file: | ||
2074 | :: | ||
2075 | |||
2076 | ERR_REPORT_DIR = "path" | ||
2077 | |||
2078 | ERROR_QA | ||
2079 | Specifies the quality assurance checks whose failures are reported as | ||
2080 | errors by the OpenEmbedded build system. You set this variable in | ||
2081 | your distribution configuration file. For a list of the checks you | ||
2082 | can control with this variable, see the | ||
2083 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | ||
2084 | |||
2085 | EXCLUDE_FROM_SHLIBS | ||
2086 | Triggers the OpenEmbedded build system's shared libraries resolver to | ||
2087 | exclude an entire package when scanning for shared libraries. | ||
2088 | |||
2089 | .. note:: | ||
2090 | |||
2091 | The shared libraries resolver's functionality results in part from | ||
2092 | the internal function | ||
2093 | package_do_shlibs | ||
2094 | , which is part of the | ||
2095 | do_package | ||
2096 | task. You should be aware that the shared libraries resolver might | ||
2097 | implicitly define some dependencies between packages. | ||
2098 | |||
2099 | The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the | ||
2100 | :term:`PRIVATE_LIBS` variable, which excludes a | ||
2101 | package's particular libraries only and not the whole package. | ||
2102 | |||
2103 | Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a | ||
2104 | particular package: | ||
2105 | :: | ||
2106 | |||
2107 | EXCLUDE_FROM_SHLIBS = "1" | ||
2108 | |||
2109 | EXCLUDE_FROM_WORLD | ||
2110 | Directs BitBake to exclude a recipe from world builds (i.e. | ||
2111 | ``bitbake world``). During world builds, BitBake locates, parses and | ||
2112 | builds all recipes found in every layer exposed in the | ||
2113 | ``bblayers.conf`` configuration file. | ||
2114 | |||
2115 | To exclude a recipe from a world build using this variable, set the | ||
2116 | variable to "1" in the recipe. | ||
2117 | |||
2118 | .. note:: | ||
2119 | |||
2120 | Recipes added to | ||
2121 | EXCLUDE_FROM_WORLD | ||
2122 | may still be built during a world build in order to satisfy | ||
2123 | dependencies of other recipes. Adding a recipe to | ||
2124 | EXCLUDE_FROM_WORLD | ||
2125 | only ensures that the recipe is not explicitly added to the list | ||
2126 | of build targets in a world build. | ||
2127 | |||
2128 | EXTENDPE | ||
2129 | Used with file and pathnames to create a prefix for a recipe's | ||
2130 | version based on the recipe's :term:`PE` value. If ``PE`` | ||
2131 | is set and greater than zero for a recipe, ``EXTENDPE`` becomes that | ||
2132 | value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1"). | ||
2133 | If a recipe's ``PE`` is not set (the default) or is equal to zero, | ||
2134 | ``EXTENDPE`` becomes "". | ||
2135 | |||
2136 | See the :term:`STAMP` variable for an example. | ||
2137 | |||
2138 | EXTENDPKGV | ||
2139 | The full package version specification as it appears on the final | ||
2140 | packages produced by a recipe. The variable's value is normally used | ||
2141 | to fix a runtime dependency to the exact same version of another | ||
2142 | package in the same recipe: | ||
2143 | :: | ||
2144 | |||
2145 | RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" | ||
2146 | |||
2147 | The dependency relationships are intended to force the package | ||
2148 | manager to upgrade these types of packages in lock-step. | ||
2149 | |||
2150 | EXTERNAL_KERNEL_TOOLS | ||
2151 | When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these | ||
2152 | tools are not in the source tree. | ||
2153 | |||
2154 | When kernel tools are available in the tree, they are preferred over | ||
2155 | any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS`` | ||
2156 | variable tells the OpenEmbedded build system to prefer the installed | ||
2157 | external tools. See the | ||
2158 | :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in | ||
2159 | ``meta/classes`` to see how the variable is used. | ||
2160 | |||
2161 | EXTERNALSRC | ||
2162 | When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` | ||
2163 | class, this variable points to the source tree, which is outside of | ||
2164 | the OpenEmbedded build system. When set, this variable sets the | ||
2165 | :term:`S` variable, which is what the OpenEmbedded build | ||
2166 | system uses to locate unpacked recipe source code. | ||
2167 | |||
2168 | For more information on ``externalsrc.bbclass``, see the | ||
2169 | ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You | ||
2170 | can also find information on how to use this variable in the | ||
2171 | ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" | ||
2172 | section in the Yocto Project Development Tasks Manual. | ||
2173 | |||
2174 | EXTERNALSRC_BUILD | ||
2175 | When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` | ||
2176 | class, this variable points to the directory in which the recipe's | ||
2177 | source code is built, which is outside of the OpenEmbedded build | ||
2178 | system. When set, this variable sets the :term:`B` variable, | ||
2179 | which is what the OpenEmbedded build system uses to locate the Build | ||
2180 | Directory. | ||
2181 | |||
2182 | For more information on ``externalsrc.bbclass``, see the | ||
2183 | ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You | ||
2184 | can also find information on how to use this variable in the | ||
2185 | ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`" | ||
2186 | section in the Yocto Project Development Tasks Manual. | ||
2187 | |||
2188 | EXTRA_AUTORECONF | ||
2189 | For recipes inheriting the :ref:`autotools <ref-classes-autotools>` | ||
2190 | class, you can use ``EXTRA_AUTORECONF`` to specify extra options to | ||
2191 | pass to the ``autoreconf`` command that is executed during the | ||
2192 | :ref:`ref-tasks-configure` task. | ||
2193 | |||
2194 | The default value is "--exclude=autopoint". | ||
2195 | |||
2196 | EXTRA_IMAGE_FEATURES | ||
2197 | A list of additional features to include in an image. When listing | ||
2198 | more than one feature, separate them with a space. | ||
2199 | |||
2200 | Typically, you configure this variable in your ``local.conf`` file, | ||
2201 | which is found in the :term:`Build Directory`. | ||
2202 | Although you can use this variable from within a recipe, best | ||
2203 | practices dictate that you do not. | ||
2204 | |||
2205 | .. note:: | ||
2206 | |||
2207 | To enable primary features from within the image recipe, use the | ||
2208 | IMAGE_FEATURES | ||
2209 | variable. | ||
2210 | |||
2211 | Here are some examples of features you can add: | ||
2212 | |||
2213 | - "dbg-pkgs" - Adds -dbg packages for all installed packages including | ||
2214 | symbol information for debugging and profiling. | ||
2215 | |||
2216 | - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and | ||
2217 | enables post-installation logging. See the 'allow-empty-password' and | ||
2218 | 'post-install-logging' features in the "`Image | ||
2219 | Features <#ref-features-image>`__" section for more information. | ||
2220 | - "dev-pkgs" - Adds -dev packages for all installed packages. This is | ||
2221 | useful if you want to develop against the libraries in the image. | ||
2222 | - "read-only-rootfs" - Creates an image whose root filesystem is | ||
2223 | read-only. See the | ||
2224 | ":ref:`dev-manual/dev-manual-common-tasks:creating a read-only root filesystem`" | ||
2225 | section in the Yocto Project Development Tasks Manual for more | ||
2226 | information | ||
2227 | - "tools-debug" - Adds debugging tools such as gdb and strace. | ||
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 | |||
2233 | For a complete list of image features that ships with the Yocto | ||
2234 | Project, see the "`Image Features <#ref-features-image>`__" section. | ||
2235 | |||
2236 | For an example that shows how to customize your image by using this | ||
2237 | variable, see the ":ref:`usingpoky-extend-customimage-imagefeatures`" | ||
2238 | section in the Yocto Project Development Tasks Manual. | ||
2239 | |||
2240 | EXTRA_IMAGECMD | ||
2241 | Specifies additional options for the image creation command that has | ||
2242 | been specified in :term:`IMAGE_CMD`. When setting | ||
2243 | this variable, use an override for the associated image type. Here is | ||
2244 | an example: | ||
2245 | :: | ||
2246 | |||
2247 | EXTRA_IMAGECMD_ext3 ?= "-i 4096" | ||
2248 | |||
2249 | EXTRA_IMAGEDEPENDS | ||
2250 | A list of recipes to build that do not provide packages for | ||
2251 | installing into the root filesystem. | ||
2252 | |||
2253 | Sometimes a recipe is required to build the final image but is not | ||
2254 | needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS`` | ||
2255 | variable to list these recipes and thus specify the dependencies. A | ||
2256 | typical example is a required bootloader in a machine configuration. | ||
2257 | |||
2258 | .. note:: | ||
2259 | |||
2260 | To add packages to the root filesystem, see the various | ||
2261 | \*RDEPENDS and \*RRECOMMENDS | ||
2262 | variables. | ||
2263 | |||
2264 | EXTRANATIVEPATH | ||
2265 | A list of subdirectories of | ||
2266 | ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` | ||
2267 | added to the beginning of the environment variable ``PATH``. As an | ||
2268 | example, the following prepends | ||
2269 | "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to | ||
2270 | ``PATH``: | ||
2271 | :: | ||
2272 | |||
2273 | EXTRANATIVEPATH = "foo bar" | ||
2274 | |||
2275 | EXTRA_OECMAKE | ||
2276 | Additional `CMake <https://cmake.org/overview/>`__ options. See the | ||
2277 | :ref:`cmake <ref-classes-cmake>` class for additional information. | ||
2278 | |||
2279 | EXTRA_OECONF | ||
2280 | Additional ``configure`` script options. See | ||
2281 | :term:`PACKAGECONFIG_CONFARGS` for | ||
2282 | additional information on passing configure script options. | ||
2283 | |||
2284 | EXTRA_OEMAKE | ||
2285 | Additional GNU ``make`` options. | ||
2286 | |||
2287 | Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the | ||
2288 | variable to specify any required GNU options. | ||
2289 | |||
2290 | :term:`PARALLEL_MAKE` and | ||
2291 | :term:`PARALLEL_MAKEINST` also make use of | ||
2292 | ``EXTRA_OEMAKE`` to pass the required flags. | ||
2293 | |||
2294 | EXTRA_OESCONS | ||
2295 | When inheriting the :ref:`scons <ref-classes-scons>` class, this | ||
2296 | variable specifies additional configuration options you want to pass | ||
2297 | to the ``scons`` command line. | ||
2298 | |||
2299 | EXTRA_USERS_PARAMS | ||
2300 | When inheriting the :ref:`extrausers <ref-classes-extrausers>` | ||
2301 | class, this variable provides image level user and group operations. | ||
2302 | This is a more global method of providing user and group | ||
2303 | configuration as compared to using the | ||
2304 | :ref:`useradd <ref-classes-useradd>` class, which ties user and | ||
2305 | group configurations to a specific recipe. | ||
2306 | |||
2307 | The set list of commands you can configure using the | ||
2308 | ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These | ||
2309 | commands map to the normal Unix commands of the same names: | ||
2310 | :: | ||
2311 | |||
2312 | # EXTRA_USERS_PARAMS = "\ | ||
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 | |||
2321 | FEATURE_PACKAGES | ||
2322 | Defines one or more packages to include in an image when a specific | ||
2323 | item is included in :term:`IMAGE_FEATURES`. | ||
2324 | When setting the value, ``FEATURE_PACKAGES`` should have the name of | ||
2325 | the feature item as an override. Here is an example: | ||
2326 | :: | ||
2327 | |||
2328 | FEATURE_PACKAGES_widget = "package1 package2" | ||
2329 | |||
2330 | In this example, if "widget" were added to ``IMAGE_FEATURES``, | ||
2331 | package1 and package2 would be included in the image. | ||
2332 | |||
2333 | .. note:: | ||
2334 | |||
2335 | Packages installed by features defined through | ||
2336 | FEATURE_PACKAGES | ||
2337 | are often package groups. While similarly named, you should not | ||
2338 | confuse the | ||
2339 | FEATURE_PACKAGES | ||
2340 | variable with package groups, which are discussed elsewhere in the | ||
2341 | documentation. | ||
2342 | |||
2343 | FEED_DEPLOYDIR_BASE_URI | ||
2344 | Points to the base URL of the server and location within the | ||
2345 | document-root that provides the metadata and packages required by | ||
2346 | OPKG to support runtime package management of IPK packages. You set | ||
2347 | this variable in your ``local.conf`` file. | ||
2348 | |||
2349 | Consider the following example: | ||
2350 | :: | ||
2351 | |||
2352 | FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" | ||
2353 | |||
2354 | This example assumes you are serving | ||
2355 | your packages over HTTP and your databases are located in a directory | ||
2356 | named ``BOARD-dir``, which is underneath your HTTP server's | ||
2357 | document-root. In this case, the OpenEmbedded build system generates | ||
2358 | a set of configuration files for you in your target that work with | ||
2359 | the feed. | ||
2360 | |||
2361 | FILES | ||
2362 | The list of files and directories that are placed in a package. The | ||
2363 | :term:`PACKAGES` variable lists the packages | ||
2364 | generated by a recipe. | ||
2365 | |||
2366 | To use the ``FILES`` variable, provide a package name override that | ||
2367 | identifies the resulting package. Then, provide a space-separated | ||
2368 | list of files or paths that identify the files you want included as | ||
2369 | part of the resulting package. Here is an example: | ||
2370 | :: | ||
2371 | |||
2372 | FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" | ||
2373 | |||
2374 | .. note:: | ||
2375 | |||
2376 | - When specifying files or paths, you can pattern match using | ||
2377 | Python's | ||
2378 | `glob <https://docs.python.org/3/library/glob.html>`_ | ||
2379 | syntax. For details on the syntax, see the documentation by | ||
2380 | following the previous link. | ||
2381 | |||
2382 | - When specifying paths as part of the ``FILES`` variable, it is | ||
2383 | good practice to use appropriate path variables. For example, | ||
2384 | use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` | ||
2385 | rather than ``/usr/bin``. You can find a list of these | ||
2386 | variables at the top of the ``meta/conf/bitbake.conf`` file in | ||
2387 | the :term:`Source Directory`. You will also | ||
2388 | find the default values of the various ``FILES_*`` variables in | ||
2389 | this file. | ||
2390 | |||
2391 | If some of the files you provide with the ``FILES`` variable are | ||
2392 | editable and you know they should not be overwritten during the | ||
2393 | package update process by the Package Management System (PMS), you | ||
2394 | can identify these files so that the PMS will not overwrite them. See | ||
2395 | the :term:`CONFFILES` variable for information on | ||
2396 | how to identify these files to the PMS. | ||
2397 | |||
2398 | FILES_SOLIBSDEV | ||
2399 | Defines the file specification to match | ||
2400 | :term:`SOLIBSDEV`. In other words, | ||
2401 | ``FILES_SOLIBSDEV`` defines the full path name of the development | ||
2402 | symbolic link (symlink) for shared libraries on the target platform. | ||
2403 | |||
2404 | The following statement from the ``bitbake.conf`` shows how it is | ||
2405 | set: | ||
2406 | :: | ||
2407 | |||
2408 | FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" | ||
2409 | |||
2410 | FILESEXTRAPATHS | ||
2411 | Extends the search path the OpenEmbedded build system uses when | ||
2412 | looking for files and patches as it processes recipes and append | ||
2413 | files. The default directories BitBake uses when it processes recipes | ||
2414 | are initially defined by the :term:`FILESPATH` | ||
2415 | variable. You can extend ``FILESPATH`` variable by using | ||
2416 | ``FILESEXTRAPATHS``. | ||
2417 | |||
2418 | Best practices dictate that you accomplish this by using | ||
2419 | ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you | ||
2420 | prepend paths as follows: | ||
2421 | :: | ||
2422 | |||
2423 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
2424 | |||
2425 | In the above example, the build system first | ||
2426 | looks for files in a directory that has the same name as the | ||
2427 | corresponding append file. | ||
2428 | |||
2429 | .. note:: | ||
2430 | |||
2431 | When extending ``FILESEXTRAPATHS``, be sure to use the immediate | ||
2432 | expansion (``:=``) operator. Immediate expansion makes sure that | ||
2433 | BitBake evaluates :term:`THISDIR` at the time the | ||
2434 | directive is encountered rather than at some later time when | ||
2435 | expansion might result in a directory that does not contain the | ||
2436 | files you need. | ||
2437 | |||
2438 | Also, include the trailing separating colon character if you are | ||
2439 | prepending. The trailing colon character is necessary because you | ||
2440 | are directing BitBake to extend the path by prepending directories | ||
2441 | to the search path. | ||
2442 | |||
2443 | Here is another common use: | ||
2444 | :: | ||
2445 | |||
2446 | FILESEXTRAPATHS_prepend := "${THISDIR}/files:" | ||
2447 | |||
2448 | In this example, the build system extends the | ||
2449 | ``FILESPATH`` variable to include a directory named ``files`` that is | ||
2450 | in the same directory as the corresponding append file. | ||
2451 | |||
2452 | This next example specifically adds three paths: | ||
2453 | :: | ||
2454 | |||
2455 | FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" | ||
2456 | |||
2457 | A final example shows how you can extend the search path and include | ||
2458 | a :term:`MACHINE`-specific override, which is useful | ||
2459 | in a BSP layer: | ||
2460 | :: | ||
2461 | |||
2462 | FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:" | ||
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 | ||
2467 | ``meta-intel/common/recipes-kernel/linux``. Here, the machine | ||
2468 | override is a special :term:`PACKAGE_ARCH` | ||
2469 | definition for multiple ``meta-intel`` machines. | ||
2470 | |||
2471 | .. note:: | ||
2472 | |||
2473 | For a layer that supports a single BSP, the override could just be | ||
2474 | the value of | ||
2475 | MACHINE | ||
2476 | . | ||
2477 | |||
2478 | By prepending paths in ``.bbappend`` files, you allow multiple append | ||
2479 | files that reside in different layers but are used for the same | ||
2480 | recipe to correctly extend the path. | ||
2481 | |||
2482 | FILESOVERRIDES | ||
2483 | A subset of :term:`OVERRIDES` used by the | ||
2484 | OpenEmbedded build system for creating | ||
2485 | :term:`FILESPATH`. The ``FILESOVERRIDES`` variable | ||
2486 | uses overrides to automatically extend the | ||
2487 | :term:`FILESPATH` variable. For an example of how | ||
2488 | that works, see the :term:`FILESPATH` variable | ||
2489 | description. Additionally, you find more information on how overrides | ||
2490 | are handled in the | ||
2491 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" | ||
2492 | section of the BitBake User Manual. | ||
2493 | |||
2494 | By default, the ``FILESOVERRIDES`` variable is defined as: | ||
2495 | :: | ||
2496 | |||
2497 | FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" | ||
2498 | |||
2499 | .. note:: | ||
2500 | |||
2501 | Do not hand-edit the | ||
2502 | FILESOVERRIDES | ||
2503 | variable. The values match up with expected overrides and are used | ||
2504 | in an expected manner by the build system. | ||
2505 | |||
2506 | FILESPATH | ||
2507 | The default set of directories the OpenEmbedded build system uses | ||
2508 | when searching for patches and files. | ||
2509 | |||
2510 | During the build process, BitBake searches each directory in | ||
2511 | ``FILESPATH`` in the specified order when looking for files and | ||
2512 | patches specified by each ``file://`` URI in a recipe's | ||
2513 | :term:`SRC_URI` statements. | ||
2514 | |||
2515 | The default value for the ``FILESPATH`` variable is defined in the | ||
2516 | ``base.bbclass`` class found in ``meta/classes`` in the | ||
2517 | :term:`Source Directory`: | ||
2518 | :: | ||
2519 | |||
2520 | FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ | ||
2521 | "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" | ||
2522 | |||
2523 | The | ||
2524 | ``FILESPATH`` variable is automatically extended using the overrides | ||
2525 | from the :term:`FILESOVERRIDES` variable. | ||
2526 | |||
2527 | .. note:: | ||
2528 | |||
2529 | - Do not hand-edit the ``FILESPATH`` variable. If you want the | ||
2530 | build system to look in directories other than the defaults, | ||
2531 | extend the ``FILESPATH`` variable by using the | ||
2532 | :term:`FILESEXTRAPATHS` variable. | ||
2533 | |||
2534 | - Be aware that the default ``FILESPATH`` directories do not map | ||
2535 | to directories in custom layers where append files | ||
2536 | (``.bbappend``) are used. If you want the build system to find | ||
2537 | patches or files that reside with your append files, you need | ||
2538 | to extend the ``FILESPATH`` variable by using the | ||
2539 | ``FILESEXTRAPATHS`` variable. | ||
2540 | |||
2541 | You can take advantage of this searching behavior in useful ways. For | ||
2542 | example, consider a case where the following directory structure | ||
2543 | exists for general and machine-specific configurations: | ||
2544 | :: | ||
2545 | |||
2546 | files/defconfig | ||
2547 | files/MACHINEA/defconfig | ||
2548 | files/MACHINEB/defconfig | ||
2549 | |||
2550 | Also in the example, the ``SRC_URI`` statement contains | ||
2551 | "file://defconfig". Given this scenario, you can set | ||
2552 | :term:`MACHINE` to "MACHINEA" and cause the build | ||
2553 | system to use files from ``files/MACHINEA``. Set ``MACHINE`` to | ||
2554 | "MACHINEB" and the build system uses files from ``files/MACHINEB``. | ||
2555 | Finally, for any machine other than "MACHINEA" and "MACHINEB", the | ||
2556 | build system uses files from ``files/defconfig``. | ||
2557 | |||
2558 | You can find out more about the patching process in the | ||
2559 | ":ref:`patching-dev-environment`" section | ||
2560 | in the Yocto Project Overview and Concepts Manual and the | ||
2561 | ":ref:`new-recipe-patching-code`" section in | ||
2562 | the Yocto Project Development Tasks Manual. See the | ||
2563 | :ref:`ref-tasks-patch` task as well. | ||
2564 | |||
2565 | FILESYSTEM_PERMS_TABLES | ||
2566 | Allows you to define your own file permissions settings table as part | ||
2567 | of your configuration for the packaging process. For example, suppose | ||
2568 | you need a consistent set of custom permissions for a set of groups | ||
2569 | and users across an entire work project. It is best to do this in the | ||
2570 | packages themselves but this is not always possible. | ||
2571 | |||
2572 | By default, the OpenEmbedded build system uses the ``fs-perms.txt``, | ||
2573 | which is located in the ``meta/files`` folder in the :term:`Source Directory`. | ||
2574 | If you create your own file | ||
2575 | permissions setting table, you should place it in your layer or the | ||
2576 | distro's layer. | ||
2577 | |||
2578 | You define the ``FILESYSTEM_PERMS_TABLES`` variable in the | ||
2579 | ``conf/local.conf`` file, which is found in the :term:`Build Directory`, | ||
2580 | to point to your custom | ||
2581 | ``fs-perms.txt``. You can specify more than a single file permissions | ||
2582 | setting table. The paths you specify to these files must be defined | ||
2583 | within the :term:`BBPATH` variable. | ||
2584 | |||
2585 | For guidance on how to create your own file permissions settings | ||
2586 | table file, examine the existing ``fs-perms.txt``. | ||
2587 | |||
2588 | FIT_HASH_ALG | ||
2589 | Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256. | ||
2590 | |||
2591 | FIT_SIGN_ALG | ||
2592 | Specifies the signature algorithm used in creating the FIT Image. | ||
2593 | For e.g. rsa2048. | ||
2594 | |||
2595 | FONT_EXTRA_RDEPENDS | ||
2596 | When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, | ||
2597 | this variable specifies the runtime dependencies for font packages. | ||
2598 | By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils". | ||
2599 | |||
2600 | FONT_PACKAGES | ||
2601 | When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, | ||
2602 | this variable identifies packages containing font files that need to | ||
2603 | be cached by Fontconfig. By default, the ``fontcache`` class assumes | ||
2604 | that fonts are in the recipe's main package (i.e. | ||
2605 | ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you | ||
2606 | need are in a package other than that main package. | ||
2607 | |||
2608 | FORCE_RO_REMOVE | ||
2609 | Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED`` | ||
2610 | during the generation of the root filesystem. | ||
2611 | |||
2612 | Set the variable to "1" to force the removal of these packages. | ||
2613 | |||
2614 | FULL_OPTIMIZATION | ||
2615 | The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when | ||
2616 | compiling an optimized system. This variable defaults to "-O2 -pipe | ||
2617 | ${DEBUG_FLAGS}". | ||
2618 | |||
2619 | GCCPIE | ||
2620 | Enables Position Independent Executables (PIE) within the GNU C | ||
2621 | Compiler (GCC). Enabling PIE in the GCC makes Return Oriented | ||
2622 | Programming (ROP) attacks much more difficult to execute. | ||
2623 | |||
2624 | By default the ``security_flags.inc`` file enables PIE by setting the | ||
2625 | variable as follows: | ||
2626 | :: | ||
2627 | |||
2628 | GCCPIE ?= "--enable-default-pie" | ||
2629 | |||
2630 | GCCVERSION | ||
2631 | Specifies the default version of the GNU C Compiler (GCC) used for | ||
2632 | compilation. By default, ``GCCVERSION`` is set to "8.x" in the | ||
2633 | ``meta/conf/distro/include/tcmode-default.inc`` include file: | ||
2634 | :: | ||
2635 | |||
2636 | GCCVERSION ?= "8.%" | ||
2637 | |||
2638 | You can override this value by setting it in a | ||
2639 | configuration file such as the ``local.conf``. | ||
2640 | |||
2641 | GDB | ||
2642 | The minimal command and arguments to run the GNU Debugger. | ||
2643 | |||
2644 | GITDIR | ||
2645 | The directory in which a local copy of a Git repository is stored | ||
2646 | when it is cloned. | ||
2647 | |||
2648 | GLIBC_GENERATE_LOCALES | ||
2649 | Specifies the list of GLIBC locales to generate should you not wish | ||
2650 | to generate all LIBC locals, which can be time consuming. | ||
2651 | |||
2652 | .. note:: | ||
2653 | |||
2654 | If you specifically remove the locale | ||
2655 | en_US.UTF-8 | ||
2656 | , you must set | ||
2657 | IMAGE_LINGUAS | ||
2658 | appropriately. | ||
2659 | |||
2660 | You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file. | ||
2661 | By default, all locales are generated. | ||
2662 | :: | ||
2663 | |||
2664 | GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" | ||
2665 | |||
2666 | GROUPADD_PARAM | ||
2667 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
2668 | this variable specifies for a package what parameters should be | ||
2669 | passed to the ``groupadd`` command if you wish to add a group to the | ||
2670 | system when the package is installed. | ||
2671 | |||
2672 | Here is an example from the ``dbus`` recipe: | ||
2673 | :: | ||
2674 | |||
2675 | GROUPADD_PARAM_${PN} = "-r netdev" | ||
2676 | |||
2677 | For information on the standard Linux shell command | ||
2678 | ``groupadd``, see http://linux.die.net/man/8/groupadd. | ||
2679 | |||
2680 | GROUPMEMS_PARAM | ||
2681 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
2682 | this variable specifies for a package what parameters should be | ||
2683 | passed to the ``groupmems`` command if you wish to modify the members | ||
2684 | of a group when the package is installed. | ||
2685 | |||
2686 | For information on the standard Linux shell command ``groupmems``, | ||
2687 | see http://linux.die.net/man/8/groupmems. | ||
2688 | |||
2689 | GRUB_GFXSERIAL | ||
2690 | Configures the GNU GRand Unified Bootloader (GRUB) to have graphics | ||
2691 | and serial in the boot menu. Set this variable to "1" in your | ||
2692 | ``local.conf`` or distribution configuration file to enable graphics | ||
2693 | and serial in the menu. | ||
2694 | |||
2695 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | ||
2696 | information on how this variable is used. | ||
2697 | |||
2698 | GRUB_OPTS | ||
2699 | Additional options to add to the GNU GRand Unified Bootloader (GRUB) | ||
2700 | configuration. Use a semi-colon character (``;``) to separate | ||
2701 | multiple options. | ||
2702 | |||
2703 | The ``GRUB_OPTS`` variable is optional. See the | ||
2704 | :ref:`grub-efi <ref-classes-grub-efi>` class for more information | ||
2705 | on how this variable is used. | ||
2706 | |||
2707 | GRUB_TIMEOUT | ||
2708 | Specifies the timeout before executing the default ``LABEL`` in the | ||
2709 | GNU GRand Unified Bootloader (GRUB). | ||
2710 | |||
2711 | The ``GRUB_TIMEOUT`` variable is optional. See the | ||
2712 | :ref:`grub-efi <ref-classes-grub-efi>` class for more information | ||
2713 | on how this variable is used. | ||
2714 | |||
2715 | GTKIMMODULES_PACKAGES | ||
2716 | When inheriting the | ||
2717 | :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class, | ||
2718 | this variable specifies the packages that contain the GTK+ input | ||
2719 | method modules being installed when the modules are in packages other | ||
2720 | than the main package. | ||
2721 | |||
2722 | HOMEPAGE | ||
2723 | Website where more information about the software the recipe is | ||
2724 | building can be found. | ||
2725 | |||
2726 | HOST_ARCH | ||
2727 | The name of the target architecture, which is normally the same as | ||
2728 | :term:`TARGET_ARCH`. The OpenEmbedded build system | ||
2729 | supports many architectures. Here is an example list of architectures | ||
2730 | supported. This list is by no means complete as the architecture is | ||
2731 | configurable: | ||
2732 | |||
2733 | - arm | ||
2734 | - i586 | ||
2735 | - x86_64 | ||
2736 | - powerpc | ||
2737 | - powerpc64 | ||
2738 | - mips | ||
2739 | - mipsel | ||
2740 | |||
2741 | HOST_CC_ARCH | ||
2742 | Specifies architecture-specific compiler flags that are passed to the | ||
2743 | C compiler. | ||
2744 | |||
2745 | Default initialization for ``HOST_CC_ARCH`` varies depending on what | ||
2746 | is being built: | ||
2747 | |||
2748 | - :term:`TARGET_CC_ARCH` when building for the | ||
2749 | target | ||
2750 | |||
2751 | - ``BUILD_CC_ARCH`` when building for the build host (i.e. | ||
2752 | ``-native``) | ||
2753 | |||
2754 | - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e. | ||
2755 | ``nativesdk-``) | ||
2756 | |||
2757 | HOST_OS | ||
2758 | Specifies the name of the target operating system, which is normally | ||
2759 | the same as the :term:`TARGET_OS`. The variable can | ||
2760 | be set to "linux" for ``glibc``-based systems and to "linux-musl" for | ||
2761 | ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and | ||
2762 | "linux-musleabi" values possible. | ||
2763 | |||
2764 | HOST_PREFIX | ||
2765 | Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX`` | ||
2766 | is normally the same as :term:`TARGET_PREFIX`. | ||
2767 | |||
2768 | HOST_SYS | ||
2769 | Specifies the system, including the architecture and the operating | ||
2770 | system, for which the build is occurring in the context of the | ||
2771 | current recipe. | ||
2772 | |||
2773 | The OpenEmbedded build system automatically sets this variable based | ||
2774 | on :term:`HOST_ARCH`, | ||
2775 | :term:`HOST_VENDOR`, and | ||
2776 | :term:`HOST_OS` variables. | ||
2777 | |||
2778 | .. note:: | ||
2779 | |||
2780 | You do not need to set the variable yourself. | ||
2781 | |||
2782 | Consider these two examples: | ||
2783 | |||
2784 | - Given a native recipe on a 32-bit x86 machine running Linux, the | ||
2785 | value is "i686-linux". | ||
2786 | |||
2787 | - Given a recipe being built for a little-endian MIPS target running | ||
2788 | Linux, the value might be "mipsel-linux". | ||
2789 | |||
2790 | HOSTTOOLS | ||
2791 | A space-separated list (filter) of tools on the build host that | ||
2792 | should be allowed to be called from within build tasks. Using this | ||
2793 | filter helps reduce the possibility of host contamination. If a tool | ||
2794 | specified in the value of ``HOSTTOOLS`` is not found on the build | ||
2795 | host, the OpenEmbedded build system produces an error and the build | ||
2796 | is not started. | ||
2797 | |||
2798 | For additional information, see | ||
2799 | :term:`HOSTTOOLS_NONFATAL`. | ||
2800 | |||
2801 | HOSTTOOLS_NONFATAL | ||
2802 | A space-separated list (filter) of tools on the build host that | ||
2803 | should be allowed to be called from within build tasks. Using this | ||
2804 | filter helps reduce the possibility of host contamination. Unlike | ||
2805 | :term:`HOSTTOOLS`, the OpenEmbedded build system | ||
2806 | does not produce an error if a tool specified in the value of | ||
2807 | ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can | ||
2808 | use ``HOSTTOOLS_NONFATAL`` to filter optional host tools. | ||
2809 | |||
2810 | HOST_VENDOR | ||
2811 | Specifies the name of the vendor. ``HOST_VENDOR`` is normally the | ||
2812 | same as :term:`TARGET_VENDOR`. | ||
2813 | |||
2814 | ICECC_DISABLED | ||
2815 | Disables or enables the ``icecc`` (Icecream) function. For more | ||
2816 | information on this function and best practices for using this | ||
2817 | variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`" | ||
2818 | section. | ||
2819 | |||
2820 | Setting this variable to "1" in your ``local.conf`` disables the | ||
2821 | function: | ||
2822 | :: | ||
2823 | |||
2824 | ICECC_DISABLED ??= "1" | ||
2825 | |||
2826 | To enable the function, set the variable as follows: | ||
2827 | :: | ||
2828 | |||
2829 | ICECC_DISABLED = "" | ||
2830 | |||
2831 | ICECC_ENV_EXEC | ||
2832 | Points to the ``icecc-create-env`` script that you provide. This | ||
2833 | variable is used by the :ref:`icecc <ref-classes-icecc>` class. You | ||
2834 | set this variable in your ``local.conf`` file. | ||
2835 | |||
2836 | If you do not point to a script that you provide, the OpenEmbedded | ||
2837 | build system uses the default script provided by the | ||
2838 | ``icecc-create-env.bb`` recipe, which is a modified version and not | ||
2839 | the one that comes with ``icecc``. | ||
2840 | |||
2841 | ICECC_PARALLEL_MAKE | ||
2842 | Extra options passed to the ``make`` command during the | ||
2843 | :ref:`ref-tasks-compile` task that specify parallel | ||
2844 | compilation. This variable usually takes the form of "-j x", where x | ||
2845 | represents the maximum number of parallel threads ``make`` can run. | ||
2846 | |||
2847 | .. note:: | ||
2848 | |||
2849 | The options passed affect builds on all enabled machines on the | ||
2850 | network, which are machines running the | ||
2851 | iceccd | ||
2852 | daemon. | ||
2853 | |||
2854 | If your enabled machines support multiple cores, coming up with the | ||
2855 | maximum number of parallel threads that gives you the best | ||
2856 | performance could take some experimentation since machine speed, | ||
2857 | network lag, available memory, and existing machine loads can all | ||
2858 | affect build time. Consequently, unlike the | ||
2859 | :term:`PARALLEL_MAKE` variable, there is no | ||
2860 | rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal | ||
2861 | performance. | ||
2862 | |||
2863 | If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not | ||
2864 | use it (i.e. the system does not detect and assign the number of | ||
2865 | cores as is done with ``PARALLEL_MAKE``). | ||
2866 | |||
2867 | ICECC_PATH | ||
2868 | The location of the ``icecc`` binary. You can set this variable in | ||
2869 | your ``local.conf`` file. If your ``local.conf`` file does not define | ||
2870 | this variable, the :ref:`icecc <ref-classes-icecc>` class attempts | ||
2871 | to define it by locating ``icecc`` using ``which``. | ||
2872 | |||
2873 | ICECC_USER_CLASS_BL | ||
2874 | Identifies user classes that you do not want the Icecream distributed | ||
2875 | compile support to consider. This variable is used by the | ||
2876 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | ||
2877 | your ``local.conf`` file. | ||
2878 | |||
2879 | When you list classes using this variable, you are "blacklisting" | ||
2880 | them from distributed compilation across remote hosts. Any classes | ||
2881 | you list will be distributed and compiled locally. | ||
2882 | |||
2883 | ICECC_USER_PACKAGE_BL | ||
2884 | Identifies user recipes that you do not want the Icecream distributed | ||
2885 | compile support to consider. This variable is used by the | ||
2886 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | ||
2887 | your ``local.conf`` file. | ||
2888 | |||
2889 | When you list packages using this variable, you are "blacklisting" | ||
2890 | them from distributed compilation across remote hosts. Any packages | ||
2891 | you list will be distributed and compiled locally. | ||
2892 | |||
2893 | ICECC_USER_PACKAGE_WL | ||
2894 | Identifies user recipes that use an empty | ||
2895 | :term:`PARALLEL_MAKE` variable that you want to | ||
2896 | force remote distributed compilation on using the Icecream | ||
2897 | distributed compile support. This variable is used by the | ||
2898 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | ||
2899 | your ``local.conf`` file. | ||
2900 | |||
2901 | IMAGE_BASENAME | ||
2902 | The base name of image output files. This variable defaults to the | ||
2903 | recipe name (``${``\ :term:`PN`\ ``}``). | ||
2904 | |||
2905 | IMAGE_BOOT_FILES | ||
2906 | A space-separated list of files installed into the boot partition | ||
2907 | when preparing an image using the Wic tool with the | ||
2908 | ``bootimg-partition`` or ``bootimg-efi`` source plugin. By default, | ||
2909 | the files are | ||
2910 | installed under the same name as the source files. To change the | ||
2911 | installed name, separate it from the original name with a semi-colon | ||
2912 | (;). Source files need to be located in | ||
2913 | :term:`DEPLOY_DIR_IMAGE`. Here are two | ||
2914 | examples: | ||
2915 | :: | ||
2916 | |||
2917 | IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" | ||
2918 | IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" | ||
2919 | |||
2920 | Alternatively, source files can be picked up using a glob pattern. In | ||
2921 | this case, the destination file must have the same name as the base | ||
2922 | name of the source file path. To install files into a directory | ||
2923 | within the target location, pass its name after a semi-colon (;). | ||
2924 | Here are two examples: | ||
2925 | :: | ||
2926 | |||
2927 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" | ||
2928 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" | ||
2929 | |||
2930 | The first example | ||
2931 | installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles`` | ||
2932 | into the root of the target partition. The second example installs | ||
2933 | the same files into a ``boot`` directory within the target partition. | ||
2934 | |||
2935 | You can find information on how to use the Wic tool in the | ||
2936 | ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`" | ||
2937 | section of the Yocto Project Development Tasks Manual. Reference | ||
2938 | material for Wic is located in the | ||
2939 | ":doc:`../ref-manual/ref-kickstart`" chapter. | ||
2940 | |||
2941 | IMAGE_CLASSES | ||
2942 | A list of classes that all images should inherit. You typically use | ||
2943 | this variable to specify the list of classes that register the | ||
2944 | different types of images the OpenEmbedded build system creates. | ||
2945 | |||
2946 | The default value for ``IMAGE_CLASSES`` is ``image_types``. You can | ||
2947 | set this variable in your ``local.conf`` or in a distribution | ||
2948 | configuration file. | ||
2949 | |||
2950 | For more information, see ``meta/classes/image_types.bbclass`` in the | ||
2951 | :term:`Source Directory`. | ||
2952 | |||
2953 | IMAGE_CMD | ||
2954 | Specifies the command to create the image file for a specific image | ||
2955 | type, which corresponds to the value set set in | ||
2956 | :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, | ||
2957 | ``btrfs``, and so forth). When setting this variable, you should use | ||
2958 | an override for the associated type. Here is an example: | ||
2959 | :: | ||
2960 | |||
2961 | IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ | ||
2962 | --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ | ||
2963 | ${EXTRA_IMAGECMD}" | ||
2964 | |||
2965 | You typically do not need to set this variable unless you are adding | ||
2966 | support for a new image type. For more examples on how to set this | ||
2967 | variable, see the :ref:`image_types <ref-classes-image_types>` | ||
2968 | class file, which is ``meta/classes/image_types.bbclass``. | ||
2969 | |||
2970 | IMAGE_DEVICE_TABLES | ||
2971 | Specifies one or more files that contain custom device tables that | ||
2972 | are passed to the ``makedevs`` command as part of creating an image. | ||
2973 | These files list basic device nodes that should be created under | ||
2974 | ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set, | ||
2975 | ``files/device_table-minimal.txt`` is used, which is located by | ||
2976 | :term:`BBPATH`. For details on how you should write | ||
2977 | device table files, see ``meta/files/device_table-minimal.txt`` as an | ||
2978 | example. | ||
2979 | |||
2980 | IMAGE_FEATURES | ||
2981 | The primary list of features to include in an image. Typically, you | ||
2982 | configure this variable in an image recipe. Although you can use this | ||
2983 | variable from your ``local.conf`` file, which is found in the | ||
2984 | :term:`Build Directory`, best practices dictate that you do | ||
2985 | not. | ||
2986 | |||
2987 | .. note:: | ||
2988 | |||
2989 | To enable extra features from outside the image recipe, use the | ||
2990 | EXTRA_IMAGE_FEATURES | ||
2991 | variable. | ||
2992 | |||
2993 | For a list of image features that ships with the Yocto Project, see | ||
2994 | the "`Image Features <#ref-features-image>`__" section. | ||
2995 | |||
2996 | For an example that shows how to customize your image by using this | ||
2997 | variable, see the ":ref:`usingpoky-extend-customimage-imagefeatures`" | ||
2998 | section in the Yocto Project Development Tasks Manual. | ||
2999 | |||
3000 | IMAGE_FSTYPES | ||
3001 | Specifies the formats the OpenEmbedded build system uses during the | ||
3002 | build when creating the root filesystem. For example, setting | ||
3003 | ``IMAGE_FSTYPES`` as follows causes the build system to create root | ||
3004 | filesystems using two formats: ``.ext3`` and ``.tar.bz2``: | ||
3005 | :: | ||
3006 | |||
3007 | IMAGE_FSTYPES = "ext3 tar.bz2" | ||
3008 | |||
3009 | For the complete list of supported image formats from which you can | ||
3010 | choose, see :term:`IMAGE_TYPES`. | ||
3011 | |||
3012 | .. note:: | ||
3013 | |||
3014 | - If an image recipe uses the "inherit image" line and you are | ||
3015 | setting ``IMAGE_FSTYPES`` inside the recipe, you must set | ||
3016 | ``IMAGE_FSTYPES`` prior to using the "inherit image" line. | ||
3017 | |||
3018 | - Due to the way the OpenEmbedded build system processes this | ||
3019 | variable, you cannot update its contents by using ``_append`` | ||
3020 | or ``_prepend``. You must use the ``+=`` operator to add one or | ||
3021 | more options to the ``IMAGE_FSTYPES`` variable. | ||
3022 | |||
3023 | IMAGE_INSTALL | ||
3024 | Used by recipes to specify the packages to install into an image | ||
3025 | through the :ref:`image <ref-classes-image>` class. Use the | ||
3026 | ``IMAGE_INSTALL`` variable with care to avoid ordering issues. | ||
3027 | |||
3028 | Image recipes set ``IMAGE_INSTALL`` to specify the packages to | ||
3029 | install into an image through ``image.bbclass``. Additionally, | ||
3030 | "helper" classes such as the | ||
3031 | :ref:`core-image <ref-classes-core-image>` class exist that can | ||
3032 | take lists used with ``IMAGE_FEATURES`` and turn them into | ||
3033 | auto-generated entries in ``IMAGE_INSTALL`` in addition to its | ||
3034 | default contents. | ||
3035 | |||
3036 | When you use this variable, it is best to use it as follows: | ||
3037 | :: | ||
3038 | |||
3039 | IMAGE_INSTALL_append = " package-name" | ||
3040 | |||
3041 | Be sure to include the space | ||
3042 | between the quotation character and the start of the package name or | ||
3043 | names. | ||
3044 | |||
3045 | .. note:: | ||
3046 | |||
3047 | - When working with a | ||
3048 | ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ | ||
3049 | image, do not use the ``IMAGE_INSTALL`` variable to specify | ||
3050 | packages for installation. Instead, use the | ||
3051 | :term:`PACKAGE_INSTALL` variable, which | ||
3052 | allows the initial RAM filesystem (initramfs) recipe to use a | ||
3053 | fixed set of packages and not be affected by ``IMAGE_INSTALL``. | ||
3054 | For information on creating an initramfs, see the | ||
3055 | ":ref:`building-an-initramfs-image`" | ||
3056 | section in the Yocto Project Development Tasks Manual. | ||
3057 | |||
3058 | - Using ``IMAGE_INSTALL`` with the | ||
3059 | :ref:`+= <bitbake:appending-and-prepending>` | ||
3060 | BitBake operator within the ``/conf/local.conf`` file or from | ||
3061 | within an image recipe is not recommended. Use of this operator | ||
3062 | in these ways can cause ordering issues. Since | ||
3063 | ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default | ||
3064 | value using the | ||
3065 | :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` | ||
3066 | operator, using a ``+=`` operation against ``IMAGE_INSTALL`` | ||
3067 | results in unexpected behavior when used within | ||
3068 | ``conf/local.conf``. Furthermore, the same operation from | ||
3069 | within an image recipe may or may not succeed depending on the | ||
3070 | specific situation. In both these cases, the behavior is | ||
3071 | contrary to how most users expect the ``+=`` operator to work. | ||
3072 | |||
3073 | IMAGE_LINGUAS | ||
3074 | Specifies the list of locales to install into the image during the | ||
3075 | root filesystem construction process. The OpenEmbedded build system | ||
3076 | automatically splits locale files, which are used for localization, | ||
3077 | into separate packages. Setting the ``IMAGE_LINGUAS`` variable | ||
3078 | ensures that any locale packages that correspond to packages already | ||
3079 | selected for installation into the image are also installed. Here is | ||
3080 | an example: | ||
3081 | :: | ||
3082 | |||
3083 | IMAGE_LINGUAS = "pt-br de-de" | ||
3084 | |||
3085 | In this example, the build system ensures any Brazilian Portuguese | ||
3086 | and German locale files that correspond to packages in the image are | ||
3087 | installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as | ||
3088 | ``*-locale-pt`` and ``*-locale-de``, since some software packages | ||
3089 | only provide locale files by language and not by country-specific | ||
3090 | language). | ||
3091 | |||
3092 | See the :term:`GLIBC_GENERATE_LOCALES` | ||
3093 | variable for information on generating GLIBC locales. | ||
3094 | |||
3095 | IMAGE_MANIFEST | ||
3096 | The manifest file for the image. This file lists all the installed | ||
3097 | packages that make up the image. The file contains package | ||
3098 | information on a line-per-package basis as follows: | ||
3099 | :: | ||
3100 | |||
3101 | packagename packagearch version | ||
3102 | |||
3103 | The :ref:`image <ref-classes-image>` class defines the manifest | ||
3104 | file as follows: | ||
3105 | :: | ||
3106 | |||
3107 | IMAGE_MANIFEST ="${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" | ||
3108 | |||
3109 | The location is | ||
3110 | derived using the :term:`DEPLOY_DIR_IMAGE` | ||
3111 | and :term:`IMAGE_NAME` variables. You can find | ||
3112 | information on how the image is created in the ":ref:`image-generation-dev-environment`" | ||
3113 | section in the Yocto Project Overview and Concepts Manual. | ||
3114 | |||
3115 | IMAGE_NAME | ||
3116 | The name of the output image files minus the extension. This variable | ||
3117 | is derived using the :term:`IMAGE_BASENAME`, | ||
3118 | :term:`MACHINE`, and :term:`DATETIME` | ||
3119 | variables: | ||
3120 | :: | ||
3121 | |||
3122 | IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}" | ||
3123 | |||
3124 | IMAGE_OVERHEAD_FACTOR | ||
3125 | Defines a multiplier that the build system applies to the initial | ||
3126 | image size for cases when the multiplier times the returned disk | ||
3127 | usage value for the image is greater than the sum of | ||
3128 | ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of | ||
3129 | the multiplier applied to the initial image size creates free disk | ||
3130 | space in the image as overhead. By default, the build process uses a | ||
3131 | multiplier of 1.3 for this variable. This default value results in | ||
3132 | 30% free disk space added to the image when this method is used to | ||
3133 | determine the final generated image size. You should be aware that | ||
3134 | post install scripts and the package management system uses disk | ||
3135 | space inside this overhead area. Consequently, the multiplier does | ||
3136 | not produce an image with all the theoretical free disk space. See | ||
3137 | ``IMAGE_ROOTFS_SIZE`` for information on how the build system | ||
3138 | determines the overall image size. | ||
3139 | |||
3140 | The default 30% free disk space typically gives the image enough room | ||
3141 | to boot and allows for basic post installs while still leaving a | ||
3142 | small amount of free disk space. If 30% free space is inadequate, you | ||
3143 | can increase the default value. For example, the following setting | ||
3144 | gives you 50% free space added to the image: | ||
3145 | :: | ||
3146 | |||
3147 | IMAGE_OVERHEAD_FACTOR = "1.5" | ||
3148 | |||
3149 | Alternatively, you can ensure a specific amount of free disk space is | ||
3150 | added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` | ||
3151 | variable. | ||
3152 | |||
3153 | IMAGE_PKGTYPE | ||
3154 | Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the | ||
3155 | OpenEmbedded build system. The variable is defined appropriately by | ||
3156 | the :ref:`package_deb <ref-classes-package_deb>`, | ||
3157 | :ref:`package_rpm <ref-classes-package_rpm>`, | ||
3158 | :ref:`package_ipk <ref-classes-package_ipk>`, or | ||
3159 | :ref:`package_tar <ref-classes-package_tar>` class. | ||
3160 | |||
3161 | .. note:: | ||
3162 | |||
3163 | The | ||
3164 | package_tar | ||
3165 | class is broken and is not supported. It is recommended that you | ||
3166 | do not use it. | ||
3167 | |||
3168 | The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and | ||
3169 | :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE`` | ||
3170 | for packaging up images and SDKs. | ||
3171 | |||
3172 | You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the | ||
3173 | variable is set indirectly through the appropriate | ||
3174 | :ref:`package_* <ref-classes-package>` class using the | ||
3175 | :term:`PACKAGE_CLASSES` variable. The | ||
3176 | OpenEmbedded build system uses the first package type (e.g. DEB, RPM, | ||
3177 | or IPK) that appears with the variable | ||
3178 | |||
3179 | .. note:: | ||
3180 | |||
3181 | Files using the | ||
3182 | .tar | ||
3183 | format are never used as a substitute packaging format for DEB, | ||
3184 | RPM, and IPK formatted files for your image or SDK. | ||
3185 | |||
3186 | IMAGE_POSTPROCESS_COMMAND | ||
3187 | Specifies a list of functions to call once the OpenEmbedded build | ||
3188 | system creates the final image output files. You can specify | ||
3189 | functions separated by semicolons: | ||
3190 | :: | ||
3191 | |||
3192 | IMAGE_POSTPROCESS_COMMAND += "function; ... " | ||
3193 | |||
3194 | If you need to pass the root filesystem path to a command within the | ||
3195 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
3196 | directory that becomes the root filesystem image. See the | ||
3197 | :term:`IMAGE_ROOTFS` variable for more | ||
3198 | information. | ||
3199 | |||
3200 | IMAGE_PREPROCESS_COMMAND | ||
3201 | Specifies a list of functions to call before the OpenEmbedded build | ||
3202 | system creates the final image output files. You can specify | ||
3203 | functions separated by semicolons: | ||
3204 | :: | ||
3205 | |||
3206 | IMAGE_PREPROCESS_COMMAND += "function; ... " | ||
3207 | |||
3208 | If you need to pass the root filesystem path to a command within the | ||
3209 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
3210 | directory that becomes the root filesystem image. See the | ||
3211 | :term:`IMAGE_ROOTFS` variable for more | ||
3212 | information. | ||
3213 | |||
3214 | IMAGE_ROOTFS | ||
3215 | The location of the root filesystem while it is under construction | ||
3216 | (i.e. during the :ref:`ref-tasks-rootfs` task). This | ||
3217 | variable is not configurable. Do not change it. | ||
3218 | |||
3219 | IMAGE_ROOTFS_ALIGNMENT | ||
3220 | Specifies the alignment for the output image file in Kbytes. If the | ||
3221 | size of the image is not a multiple of this value, then the size is | ||
3222 | rounded up to the nearest multiple of the value. The default value is | ||
3223 | "1". See :term:`IMAGE_ROOTFS_SIZE` for | ||
3224 | additional information. | ||
3225 | |||
3226 | IMAGE_ROOTFS_EXTRA_SPACE | ||
3227 | Defines additional free disk space created in the image in Kbytes. By | ||
3228 | default, this variable is set to "0". This free disk space is added | ||
3229 | to the image after the build system determines the image size as | ||
3230 | described in ``IMAGE_ROOTFS_SIZE``. | ||
3231 | |||
3232 | This variable is particularly useful when you want to ensure that a | ||
3233 | specific amount of free disk space is available on a device after an | ||
3234 | image is installed and running. For example, to be sure 5 Gbytes of | ||
3235 | free disk space is available, set the variable as follows: | ||
3236 | :: | ||
3237 | |||
3238 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" | ||
3239 | |||
3240 | For example, the Yocto Project Build Appliance specifically requests | ||
3241 | 40 Gbytes of extra space with the line: | ||
3242 | :: | ||
3243 | |||
3244 | IMAGE_ROOTFS_EXTRA_SPACE = "41943040" | ||
3245 | |||
3246 | IMAGE_ROOTFS_SIZE | ||
3247 | Defines the size in Kbytes for the generated image. The OpenEmbedded | ||
3248 | build system determines the final size for the generated image using | ||
3249 | an algorithm that takes into account the initial disk space used for | ||
3250 | the generated image, a requested size for the image, and requested | ||
3251 | additional free disk space to be added to the image. Programatically, | ||
3252 | the build system determines the final size of the generated image as | ||
3253 | follows: | ||
3254 | :: | ||
3255 | |||
3256 | if (image-du * overhead) < rootfs-size: | ||
3257 | internal-rootfs-size = rootfs-size + xspace | ||
3258 | else: | ||
3259 | internal-rootfs-size = (image-du * overhead) + xspace | ||
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 | |||
3267 | See the :term:`IMAGE_OVERHEAD_FACTOR` | ||
3268 | and :term:`IMAGE_ROOTFS_EXTRA_SPACE` | ||
3269 | variables for related information. | ||
3270 | |||
3271 | IMAGE_TYPEDEP | ||
3272 | Specifies a dependency from one image type on another. Here is an | ||
3273 | example from the :ref:`image-live <ref-classes-image-live>` class: | ||
3274 | :: | ||
3275 | |||
3276 | IMAGE_TYPEDEP_live = "ext3" | ||
3277 | |||
3278 | In the previous example, the variable ensures that when "live" is | ||
3279 | listed with the :term:`IMAGE_FSTYPES` variable, | ||
3280 | the OpenEmbedded build system produces an ``ext3`` image first since | ||
3281 | one of the components of the live image is an ``ext3`` formatted | ||
3282 | partition containing the root filesystem. | ||
3283 | |||
3284 | IMAGE_TYPES | ||
3285 | Specifies the complete list of supported image types by default: | ||
3286 | |||
3287 | - btrfs | ||
3288 | - container | ||
3289 | - cpio | ||
3290 | - cpio.gz | ||
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 | |||
3326 | For more information about these types of images, see | ||
3327 | ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`. | ||
3328 | |||
3329 | INC_PR | ||
3330 | Helps define the recipe revision for recipes that share a common | ||
3331 | ``include`` file. You can think of this variable as part of the | ||
3332 | recipe revision as set from within an include file. | ||
3333 | |||
3334 | Suppose, for example, you have a set of recipes that are used across | ||
3335 | several projects. And, within each of those recipes the revision (its | ||
3336 | :term:`PR` value) is set accordingly. In this case, when | ||
3337 | the revision of those recipes changes, the burden is on you to find | ||
3338 | all those recipes and be sure that they get changed to reflect the | ||
3339 | updated version of the recipe. In this scenario, it can get | ||
3340 | complicated when recipes that are used in many places and provide | ||
3341 | common functionality are upgraded to a new revision. | ||
3342 | |||
3343 | A more efficient way of dealing with this situation is to set the | ||
3344 | ``INC_PR`` variable inside the ``include`` files that the recipes | ||
3345 | share and then expand the ``INC_PR`` variable within the recipes to | ||
3346 | help define the recipe revision. | ||
3347 | |||
3348 | The following provides an example that shows how to use the | ||
3349 | ``INC_PR`` variable given a common ``include`` file that defines the | ||
3350 | variable. Once the variable is defined in the ``include`` file, you | ||
3351 | can use the variable to set the ``PR`` values in each recipe. You | ||
3352 | will notice that when you set a recipe's ``PR`` you can provide more | ||
3353 | granular revisioning by appending values to the ``INC_PR`` variable: | ||
3354 | :: | ||
3355 | |||
3356 | recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" | ||
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 | ||
3362 | first line of the example establishes the baseline revision to be | ||
3363 | used for all recipes that use the ``include`` file. The remaining | ||
3364 | lines in the example are from individual recipes and show how the | ||
3365 | ``PR`` value is set. | ||
3366 | |||
3367 | INCOMPATIBLE_LICENSE | ||
3368 | Specifies a space-separated list of license names (as they would | ||
3369 | appear in :term:`LICENSE`) that should be excluded | ||
3370 | from the build. Recipes that provide no alternatives to listed | ||
3371 | incompatible licenses are not built. Packages that are individually | ||
3372 | licensed with the specified incompatible licenses will be deleted. | ||
3373 | |||
3374 | .. note:: | ||
3375 | |||
3376 | This functionality is only regularly tested using the following | ||
3377 | setting: | ||
3378 | :: | ||
3379 | |||
3380 | INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" | ||
3381 | |||
3382 | |||
3383 | Although you can use other settings, you might be required to | ||
3384 | remove dependencies on or provide alternatives to components that | ||
3385 | are required to produce a functional system image. | ||
3386 | |||
3387 | .. note:: | ||
3388 | |||
3389 | It is possible to define a list of licenses that are allowed to be | ||
3390 | used instead of the licenses that are excluded. To do this, define | ||
3391 | a variable | ||
3392 | COMPATIBLE_LICENSES | ||
3393 | with the names of the licences that are allowed. Then define | ||
3394 | INCOMPATIBLE_LICENSE | ||
3395 | as: | ||
3396 | :: | ||
3397 | |||
3398 | INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}" | ||
3399 | |||
3400 | |||
3401 | This will result in | ||
3402 | INCOMPATIBLE_LICENSE | ||
3403 | containing the names of all licences from | ||
3404 | AVAILABLE_LICENSES | ||
3405 | except the ones specified in | ||
3406 | COMPATIBLE_LICENSES | ||
3407 | , thus only allowing the latter licences to be used. | ||
3408 | |||
3409 | INHERIT | ||
3410 | Causes the named class or classes to be inherited globally. Anonymous | ||
3411 | functions in the class or classes are not executed for the base | ||
3412 | configuration and in each individual recipe. The OpenEmbedded build | ||
3413 | system ignores changes to ``INHERIT`` in individual recipes. | ||
3414 | |||
3415 | For more information on ``INHERIT``, see the | ||
3416 | :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" | ||
3417 | section in the Bitbake User Manual. | ||
3418 | |||
3419 | INHERIT_DISTRO | ||
3420 | Lists classes that will be inherited at the distribution level. It is | ||
3421 | unlikely that you want to edit this variable. | ||
3422 | |||
3423 | The default value of the variable is set as follows in the | ||
3424 | ``meta/conf/distro/defaultsetup.conf`` file: | ||
3425 | :: | ||
3426 | |||
3427 | INHERIT_DISTRO ?= "debian devshell sstate license" | ||
3428 | |||
3429 | INHIBIT_DEFAULT_DEPS | ||
3430 | Prevents the default dependencies, namely the C compiler and standard | ||
3431 | C library (libc), from being added to :term:`DEPENDS`. | ||
3432 | This variable is usually used within recipes that do not require any | ||
3433 | compilation using the C compiler. | ||
3434 | |||
3435 | Set the variable to "1" to prevent the default dependencies from | ||
3436 | being added. | ||
3437 | |||
3438 | INHIBIT_PACKAGE_DEBUG_SPLIT | ||
3439 | Prevents the OpenEmbedded build system from splitting out debug | ||
3440 | information during packaging. By default, the build system splits out | ||
3441 | debugging information during the | ||
3442 | :ref:`ref-tasks-package` task. For more information on | ||
3443 | how debug information is split out, see the | ||
3444 | :term:`PACKAGE_DEBUG_SPLIT_STYLE` | ||
3445 | variable. | ||
3446 | |||
3447 | To prevent the build system from splitting out debug information | ||
3448 | during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as | ||
3449 | follows: | ||
3450 | :: | ||
3451 | |||
3452 | INHIBIT_PACKAGE_DEBUG_SPLIT = "1" | ||
3453 | |||
3454 | INHIBIT_PACKAGE_STRIP | ||
3455 | If set to "1", causes the build to not strip binaries in resulting | ||
3456 | packages and prevents the ``-dbg`` package from containing the source | ||
3457 | files. | ||
3458 | |||
3459 | By default, the OpenEmbedded build system strips binaries and puts | ||
3460 | the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. | ||
3461 | Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you | ||
3462 | plan to debug in general. | ||
3463 | |||
3464 | INHIBIT_SYSROOT_STRIP | ||
3465 | If set to "1", causes the build to not strip binaries in the | ||
3466 | resulting sysroot. | ||
3467 | |||
3468 | By default, the OpenEmbedded build system strips binaries in the | ||
3469 | resulting sysroot. When you specifically set the | ||
3470 | ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit | ||
3471 | this stripping. | ||
3472 | |||
3473 | If you want to use this variable, include the | ||
3474 | :ref:`staging <ref-classes-staging>` class. This class uses a | ||
3475 | ``sys_strip()`` function to test for the variable and acts | ||
3476 | accordingly. | ||
3477 | |||
3478 | .. note:: | ||
3479 | |||
3480 | Use of the | ||
3481 | INHIBIT_SYSROOT_STRIP | ||
3482 | variable occurs in rare and special circumstances. For example, | ||
3483 | suppose you are building bare-metal firmware by using an external | ||
3484 | GCC toolchain. Furthermore, even if the toolchain's binaries are | ||
3485 | strippable, other files exist that are needed for the build that | ||
3486 | are not strippable. | ||
3487 | |||
3488 | INITRAMFS_FSTYPES | ||
3489 | Defines the format for the output image of an initial RAM filesystem | ||
3490 | (initramfs), which is used during boot. Supported formats are the | ||
3491 | same as those supported by the | ||
3492 | :term:`IMAGE_FSTYPES` variable. | ||
3493 | |||
3494 | The default value of this variable, which is set in the | ||
3495 | ``meta/conf/bitbake.conf`` configuration file in the | ||
3496 | :term:`Source Directory`, is "cpio.gz". The Linux kernel's | ||
3497 | initramfs mechanism, as opposed to the initial RAM filesystem | ||
3498 | `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects | ||
3499 | an optionally compressed cpio archive. | ||
3500 | |||
3501 | INITRAMFS_IMAGE | ||
3502 | Specifies the :term:`PROVIDES` name of an image | ||
3503 | recipe that is used to build an initial RAM filesystem (initramfs) | ||
3504 | image. In other words, the ``INITRAMFS_IMAGE`` variable causes an | ||
3505 | additional recipe to be built as a dependency to whatever root | ||
3506 | filesystem recipe you might be using (e.g. ``core-image-sato``). The | ||
3507 | initramfs image recipe you provide should set | ||
3508 | :term:`IMAGE_FSTYPES` to | ||
3509 | :term:`INITRAMFS_FSTYPES`. | ||
3510 | |||
3511 | An initramfs image provides a temporary root filesystem used for | ||
3512 | early system initialization (e.g. loading of modules needed to locate | ||
3513 | and mount the "real" root filesystem). | ||
3514 | |||
3515 | .. note:: | ||
3516 | |||
3517 | See the | ||
3518 | meta/recipes-core/images/core-image-minimal-initramfs.bb | ||
3519 | recipe in the | ||
3520 | Source Directory | ||
3521 | for an example initramfs recipe. To select this sample recipe as | ||
3522 | the one built to provide the initramfs image, set | ||
3523 | INITRAMFS_IMAGE | ||
3524 | to "core-image-minimal-initramfs". | ||
3525 | |||
3526 | You can also find more information by referencing the | ||
3527 | ``meta-poky/conf/local.conf.sample.extended`` configuration file in | ||
3528 | the Source Directory, the :ref:`image <ref-classes-image>` class, | ||
3529 | and the :ref:`kernel <ref-classes-kernel>` class to see how to use | ||
3530 | the ``INITRAMFS_IMAGE`` variable. | ||
3531 | |||
3532 | If ``INITRAMFS_IMAGE`` is empty, which is the default, then no | ||
3533 | initramfs image is built. | ||
3534 | |||
3535 | For more information, you can also see the | ||
3536 | :term:`INITRAMFS_IMAGE_BUNDLE` | ||
3537 | variable, which allows the generated image to be bundled inside the | ||
3538 | kernel image. Additionally, for information on creating an initramfs | ||
3539 | image, see the ":ref:`building-an-initramfs-image`" section | ||
3540 | in the Yocto Project Development Tasks Manual. | ||
3541 | |||
3542 | INITRAMFS_IMAGE_BUNDLE | ||
3543 | Controls whether or not the image recipe specified by | ||
3544 | :term:`INITRAMFS_IMAGE` is run through an | ||
3545 | extra pass | ||
3546 | (:ref:`ref-tasks-bundle_initramfs`) during | ||
3547 | kernel compilation in order to build a single binary that contains | ||
3548 | both the kernel image and the initial RAM filesystem (initramfs) | ||
3549 | image. This makes use of the | ||
3550 | :term:`CONFIG_INITRAMFS_SOURCE` kernel | ||
3551 | feature. | ||
3552 | |||
3553 | .. note:: | ||
3554 | |||
3555 | Using an extra compilation pass to bundle the initramfs avoids a | ||
3556 | circular dependency between the kernel recipe and the initramfs | ||
3557 | recipe should the initramfs include kernel modules. Should that be | ||
3558 | the case, the initramfs recipe depends on the kernel for the | ||
3559 | kernel modules, and the kernel depends on the initramfs recipe | ||
3560 | since the initramfs is bundled inside the kernel image. | ||
3561 | |||
3562 | The combined binary is deposited into the ``tmp/deploy`` directory, | ||
3563 | which is part of the :term:`Build Directory`. | ||
3564 | |||
3565 | Setting the variable to "1" in a configuration file causes the | ||
3566 | OpenEmbedded build system to generate a kernel image with the | ||
3567 | initramfs specified in ``INITRAMFS_IMAGE`` bundled within: | ||
3568 | :: | ||
3569 | |||
3570 | INITRAMFS_IMAGE_BUNDLE = "1" | ||
3571 | |||
3572 | By default, the | ||
3573 | :ref:`kernel <ref-classes-kernel>` class sets this variable to a | ||
3574 | null string as follows: | ||
3575 | :: | ||
3576 | |||
3577 | INITRAMFS_IMAGE_BUNDLE ?= "" | ||
3578 | |||
3579 | .. note:: | ||
3580 | |||
3581 | You must set the | ||
3582 | INITRAMFS_IMAGE_BUNDLE | ||
3583 | variable in a configuration file. You cannot set the variable in a | ||
3584 | recipe file. | ||
3585 | |||
3586 | See the | ||
3587 | :yocto_git:`local.conf.sample.extended </cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended>` | ||
3588 | file for additional information. Also, for information on creating an | ||
3589 | initramfs, see the ":ref:`building-an-initramfs-image`" section | ||
3590 | in the Yocto Project Development Tasks Manual. | ||
3591 | |||
3592 | INITRAMFS_LINK_NAME | ||
3593 | The link name of the initial RAM filesystem image. This variable is | ||
3594 | set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3595 | follows: | ||
3596 | :: | ||
3597 | |||
3598 | INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" | ||
3599 | |||
3600 | The value of the | ||
3601 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | ||
3602 | file, has the following value: | ||
3603 | :: | ||
3604 | |||
3605 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3606 | |||
3607 | See the :term:`MACHINE` variable for additional | ||
3608 | information. | ||
3609 | |||
3610 | INITRAMFS_NAME | ||
3611 | The base name of the initial RAM filesystem image. This variable is | ||
3612 | set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3613 | follows: | ||
3614 | :: | ||
3615 | |||
3616 | INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" | ||
3617 | |||
3618 | The value of the :term:`KERNEL_ARTIFACT_NAME` | ||
3619 | variable, which is set in the same file, has the following value: | ||
3620 | :: | ||
3621 | |||
3622 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3623 | |||
3624 | INITRD | ||
3625 | Indicates list of filesystem images to concatenate and use as an | ||
3626 | initial RAM disk (``initrd``). | ||
3627 | |||
3628 | The ``INITRD`` variable is an optional variable used with the | ||
3629 | :ref:`image-live <ref-classes-image-live>` class. | ||
3630 | |||
3631 | INITRD_IMAGE | ||
3632 | When building a "live" bootable image (i.e. when | ||
3633 | :term:`IMAGE_FSTYPES` contains "live"), | ||
3634 | ``INITRD_IMAGE`` specifies the image recipe that should be built to | ||
3635 | provide the initial RAM disk image. The default value is | ||
3636 | "core-image-minimal-initramfs". | ||
3637 | |||
3638 | See the :ref:`image-live <ref-classes-image-live>` class for more | ||
3639 | information. | ||
3640 | |||
3641 | INITSCRIPT_NAME | ||
3642 | The filename of the initialization script as installed to | ||
3643 | ``${sysconfdir}/init.d``. | ||
3644 | |||
3645 | This variable is used in recipes when using ``update-rc.d.bbclass``. | ||
3646 | The variable is mandatory. | ||
3647 | |||
3648 | INITSCRIPT_PACKAGES | ||
3649 | A list of the packages that contain initscripts. If multiple packages | ||
3650 | are specified, you need to append the package name to the other | ||
3651 | ``INITSCRIPT_*`` as an override. | ||
3652 | |||
3653 | This variable is used in recipes when using ``update-rc.d.bbclass``. | ||
3654 | The variable is optional and defaults to the :term:`PN` | ||
3655 | variable. | ||
3656 | |||
3657 | INITSCRIPT_PARAMS | ||
3658 | Specifies the options to pass to ``update-rc.d``. Here is an example: | ||
3659 | :: | ||
3660 | |||
3661 | INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." | ||
3662 | |||
3663 | In this example, the script has a runlevel of 99, starts the script | ||
3664 | in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. | ||
3665 | |||
3666 | The variable's default value is "defaults", which is set in the | ||
3667 | :ref:`update-rc.d <ref-classes-update-rc.d>` class. | ||
3668 | |||
3669 | The value in ``INITSCRIPT_PARAMS`` is passed through to the | ||
3670 | ``update-rc.d`` command. For more information on valid parameters, | ||
3671 | please see the ``update-rc.d`` manual page at | ||
3672 | https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html | ||
3673 | |||
3674 | INSANE_SKIP | ||
3675 | Specifies the QA checks to skip for a specific package within a | ||
3676 | recipe. For example, to skip the check for symbolic link ``.so`` | ||
3677 | files in the main package of a recipe, add the following to the | ||
3678 | recipe. The package name override must be used, which in this example | ||
3679 | is ``${PN}``: | ||
3680 | :: | ||
3681 | |||
3682 | INSANE_SKIP_${PN} += "dev-so" | ||
3683 | |||
3684 | See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a | ||
3685 | list of the valid QA checks you can specify using this variable. | ||
3686 | |||
3687 | INSTALL_TIMEZONE_FILE | ||
3688 | By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. | ||
3689 | Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the | ||
3690 | configuration level to disable this behavior. | ||
3691 | |||
3692 | IPK_FEED_URIS | ||
3693 | When the IPK backend is in use and package management is enabled on | ||
3694 | the target, you can use this variable to set up ``opkg`` in the | ||
3695 | target image to point to package feeds on a nominated server. Once | ||
3696 | the feed is established, you can perform installations or upgrades | ||
3697 | using the package manager at runtime. | ||
3698 | |||
3699 | KARCH | ||
3700 | Defines the kernel architecture used when assembling the | ||
3701 | configuration. Architectures supported for this release are: | ||
3702 | |||
3703 | - powerpc | ||
3704 | - i386 | ||
3705 | - x86_64 | ||
3706 | - arm | ||
3707 | - qemu | ||
3708 | - mips | ||
3709 | |||
3710 | You define the ``KARCH`` variable in the :ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`. | ||
3711 | |||
3712 | KBRANCH | ||
3713 | A regular expression used by the build process to explicitly identify | ||
3714 | the kernel branch that is validated, patched, and configured during a | ||
3715 | build. You must set this variable to ensure the exact kernel branch | ||
3716 | you want is being used by the build process. | ||
3717 | |||
3718 | Values for this variable are set in the kernel's recipe file and the | ||
3719 | kernel's append file. For example, if you are using the | ||
3720 | ``linux-yocto_4.12`` kernel, the kernel recipe file is the | ||
3721 | ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH`` | ||
3722 | is set as follows in that kernel recipe file: | ||
3723 | :: | ||
3724 | |||
3725 | KBRANCH ?= "standard/base" | ||
3726 | |||
3727 | This variable is also used from the kernel's append file to identify | ||
3728 | the kernel branch specific to a particular machine or target | ||
3729 | hardware. Continuing with the previous kernel example, the kernel's | ||
3730 | append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the | ||
3731 | BSP layer for a given machine. For example, the append file for the | ||
3732 | Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA | ||
3733 | machines (``meta-yocto-bsp``) is named | ||
3734 | ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. | ||
3735 | Here are the related statements from that append file: | ||
3736 | :: | ||
3737 | |||
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 | ||
3744 | identify the kernel branch to use when building for each supported | ||
3745 | BSP. | ||
3746 | |||
3747 | KBUILD_DEFCONFIG | ||
3748 | When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>` | ||
3749 | class, specifies an "in-tree" kernel configuration file for use | ||
3750 | during a kernel build. | ||
3751 | |||
3752 | Typically, when using a ``defconfig`` to configure a kernel during a | ||
3753 | build, you place the file in your layer in the same manner as you | ||
3754 | would place patch files and configuration fragment files (i.e. | ||
3755 | "out-of-tree"). However, if you want to use a ``defconfig`` file that | ||
3756 | is part of the kernel tree (i.e. "in-tree"), you can use the | ||
3757 | ``KBUILD_DEFCONFIG`` variable and append the | ||
3758 | :term:`KMACHINE` variable to point to the | ||
3759 | ``defconfig`` file. | ||
3760 | |||
3761 | To use the variable, set it in the append file for your kernel recipe | ||
3762 | using the following form: | ||
3763 | :: | ||
3764 | |||
3765 | KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file | ||
3766 | |||
3767 | Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses | ||
3768 | a ``defconfig`` file named "bcm2709_defconfig": | ||
3769 | :: | ||
3770 | |||
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 | ||
3779 | information on how to use the ``KBUILD_DEFCONFIG`` variable, see the | ||
3780 | ":ref:`kernel-dev/kernel-dev-common:using an "in-tree" \`\`defconfig\`\` file`" | ||
3781 | section in the Yocto Project Linux Kernel Development Manual. | ||
3782 | |||
3783 | KERNEL_ALT_IMAGETYPE | ||
3784 | Specifies an alternate kernel image type for creation in addition to | ||
3785 | the kernel image type specified using the | ||
3786 | :term:`KERNEL_IMAGETYPE` variable. | ||
3787 | |||
3788 | KERNEL_ARTIFACT_NAME | ||
3789 | Specifies the name of all of the build artifacts. You can change the | ||
3790 | name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME`` | ||
3791 | variable. | ||
3792 | |||
3793 | The value of ``KERNEL_ARTIFACT_NAME``, which is set in the | ||
3794 | ``meta/classes/kernel-artifact-names.bbclass`` file, has the | ||
3795 | following default value: | ||
3796 | :: | ||
3797 | |||
3798 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3799 | |||
3800 | See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, and :term:`MACHINE` | ||
3801 | variables for additional information. | ||
3802 | |||
3803 | .. note:: | ||
3804 | |||
3805 | The IMAGE_VERSION_SUFFIX variable is set to DATETIME. | ||
3806 | |||
3807 | KERNEL_CLASSES | ||
3808 | A list of classes defining kernel image types that the | ||
3809 | :ref:`kernel <ref-classes-kernel>` class should inherit. You | ||
3810 | typically append this variable to enable extended image types. An | ||
3811 | example is the "kernel-fitimage", which enables fitImage support and | ||
3812 | resides in ``meta/classes/kernel-fitimage.bbclass``. You can register | ||
3813 | custom kernel image types with the ``kernel`` class using this | ||
3814 | variable. | ||
3815 | |||
3816 | KERNEL_DEVICETREE | ||
3817 | Specifies the name of the generated Linux kernel device tree (i.e. | ||
3818 | the ``.dtb``) file. | ||
3819 | |||
3820 | .. note:: | ||
3821 | |||
3822 | Legacy support exists for specifying the full path to the device | ||
3823 | tree. However, providing just the .dtb file is preferred. | ||
3824 | |||
3825 | In order to use this variable, the | ||
3826 | :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must | ||
3827 | be inherited. | ||
3828 | |||
3829 | KERNEL_DTB_LINK_NAME | ||
3830 | The link name of the kernel device tree binary (DTB). This variable | ||
3831 | is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3832 | follows: | ||
3833 | :: | ||
3834 | |||
3835 | KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
3836 | |||
3837 | The | ||
3838 | value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in | ||
3839 | the same file, has the following value: | ||
3840 | :: | ||
3841 | |||
3842 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3843 | |||
3844 | See the :term:`MACHINE` variable for additional | ||
3845 | information. | ||
3846 | |||
3847 | KERNEL_DTB_NAME | ||
3848 | The base name of the kernel device tree binary (DTB). This variable | ||
3849 | is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3850 | follows: | ||
3851 | :: | ||
3852 | |||
3853 | KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
3854 | |||
3855 | The value of the :term:`KERNEL_ARTIFACT_NAME` | ||
3856 | variable, which is set in the same file, has the following value: | ||
3857 | :: | ||
3858 | |||
3859 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3860 | |||
3861 | KERNEL_EXTRA_ARGS | ||
3862 | Specifies additional ``make`` command-line arguments the OpenEmbedded | ||
3863 | build system passes on when compiling the kernel. | ||
3864 | |||
3865 | KERNEL_FEATURES | ||
3866 | Includes additional kernel metadata. In the OpenEmbedded build | ||
3867 | system, the default Board Support Packages (BSPs) | ||
3868 | :term:`Metadata` is provided through the | ||
3869 | :term:`KMACHINE` and :term:`KBRANCH` | ||
3870 | variables. You can use the ``KERNEL_FEATURES`` variable from within | ||
3871 | the kernel recipe or kernel append file to further add metadata for | ||
3872 | all BSPs or specific BSPs. | ||
3873 | |||
3874 | The metadata you add through this variable includes config fragments | ||
3875 | and features descriptions, which usually includes patches as well as | ||
3876 | config fragments. You typically override the ``KERNEL_FEATURES`` | ||
3877 | variable for a specific machine. In this way, you can provide | ||
3878 | validated, but optional, sets of kernel configurations and features. | ||
3879 | |||
3880 | For example, the following example from the ``linux-yocto-rt_4.12`` | ||
3881 | kernel recipe adds "netfilter" and "taskstats" features to all BSPs | ||
3882 | as well as "virtio" configurations to all QEMU machines. The last two | ||
3883 | statements add specific configurations to targeted machine types: | ||
3884 | :: | ||
3885 | |||
3886 | KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" | ||
3887 | KERNEL_FEATURES_append = "${KERNEL_EXTRA_FEATURES}" | ||
3888 | KERNEL_FEATURES_append_qemuall = "cfg/virtio.scc" | ||
3889 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" | ||
3890 | KERNEL_FEATURES_append_qemux86-64 = "cfg/sound.scc" | ||
3891 | |||
3892 | KERNEL_FIT_LINK_NAME | ||
3893 | The link name of the kernel flattened image tree (FIT) image. This | ||
3894 | variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` | ||
3895 | file as follows: | ||
3896 | :: | ||
3897 | |||
3898 | KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
3899 | |||
3900 | The value of the | ||
3901 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | ||
3902 | file, has the following value: | ||
3903 | :: | ||
3904 | |||
3905 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3906 | |||
3907 | See the :term:`MACHINE` variable for additional | ||
3908 | information. | ||
3909 | |||
3910 | KERNEL_FIT_NAME | ||
3911 | The base name of the kernel flattened image tree (FIT) image. This | ||
3912 | variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` | ||
3913 | file as follows: | ||
3914 | :: | ||
3915 | |||
3916 | KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
3917 | |||
3918 | The value of the :term:`KERNEL_ARTIFACT_NAME` | ||
3919 | variable, which is set in the same file, has the following value: | ||
3920 | :: | ||
3921 | |||
3922 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3923 | |||
3924 | KERNEL_IMAGE_LINK_NAME | ||
3925 | The link name for the kernel image. This variable is set in the | ||
3926 | ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
3927 | :: | ||
3928 | |||
3929 | KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
3930 | |||
3931 | The value of | ||
3932 | the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | ||
3933 | file, has the following value: | ||
3934 | :: | ||
3935 | |||
3936 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3937 | |||
3938 | See the :term:`MACHINE` variable for additional | ||
3939 | information. | ||
3940 | |||
3941 | KERNEL_IMAGE_MAXSIZE | ||
3942 | Specifies the maximum size of the kernel image file in kilobytes. If | ||
3943 | ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is | ||
3944 | checked against the set value during the | ||
3945 | :ref:`ref-tasks-sizecheck` task. The task fails if | ||
3946 | the kernel image file is larger than the setting. | ||
3947 | |||
3948 | ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a | ||
3949 | limited amount of space in which the kernel image must be stored. | ||
3950 | |||
3951 | By default, this variable is not set, which means the size of the | ||
3952 | kernel image is not checked. | ||
3953 | |||
3954 | KERNEL_IMAGE_NAME | ||
3955 | The base name of the kernel image. This variable is set in the | ||
3956 | ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
3957 | :: | ||
3958 | |||
3959 | KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
3960 | |||
3961 | The value of the | ||
3962 | :term:`KERNEL_ARTIFACT_NAME` variable, | ||
3963 | which is set in the same file, has the following value: | ||
3964 | :: | ||
3965 | |||
3966 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3967 | |||
3968 | KERNEL_IMAGETYPE | ||
3969 | The type of kernel to build for a device, usually set by the machine | ||
3970 | configuration files and defaults to "zImage". This variable is used | ||
3971 | when building the kernel and is passed to ``make`` as the target to | ||
3972 | build. | ||
3973 | |||
3974 | If you want to build an alternate kernel image type, use the | ||
3975 | :term:`KERNEL_ALT_IMAGETYPE` variable. | ||
3976 | |||
3977 | KERNEL_MODULE_AUTOLOAD | ||
3978 | Lists kernel modules that need to be auto-loaded during boot. | ||
3979 | |||
3980 | .. note:: | ||
3981 | |||
3982 | This variable replaces the deprecated | ||
3983 | module_autoload | ||
3984 | variable. | ||
3985 | |||
3986 | You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it | ||
3987 | can be recognized by the kernel recipe or by an out-of-tree kernel | ||
3988 | module recipe (e.g. a machine configuration file, a distribution | ||
3989 | configuration file, an append file for the recipe, or the recipe | ||
3990 | itself). | ||
3991 | |||
3992 | Specify it as follows: | ||
3993 | :: | ||
3994 | |||
3995 | KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" | ||
3996 | |||
3997 | Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build | ||
3998 | system to populate the ``/etc/modules-load.d/modname.conf`` file with | ||
3999 | the list of modules to be auto-loaded on boot. The modules appear | ||
4000 | one-per-line in the file. Here is an example of the most common use | ||
4001 | case: | ||
4002 | :: | ||
4003 | |||
4004 | KERNEL_MODULE_AUTOLOAD += "module_name" | ||
4005 | |||
4006 | For information on how to populate the ``modname.conf`` file with | ||
4007 | ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable. | ||
4008 | |||
4009 | KERNEL_MODULE_PROBECONF | ||
4010 | Provides a list of modules for which the OpenEmbedded build system | ||
4011 | expects to find ``module_conf_``\ modname values that specify | ||
4012 | configuration for each of the modules. For information on how to | ||
4013 | provide those module configurations, see the | ||
4014 | :term:`module_conf_* <module_conf>` variable. | ||
4015 | |||
4016 | KERNEL_PATH | ||
4017 | The location of the kernel sources. This variable is set to the value | ||
4018 | of the :term:`STAGING_KERNEL_DIR` within | ||
4019 | the :ref:`module <ref-classes-module>` class. For information on | ||
4020 | how this variable is used, see the | ||
4021 | ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" | ||
4022 | section in the Yocto Project Linux Kernel Development Manual. | ||
4023 | |||
4024 | To help maximize compatibility with out-of-tree drivers used to build | ||
4025 | modules, the OpenEmbedded build system also recognizes and uses the | ||
4026 | :term:`KERNEL_SRC` variable, which is identical to | ||
4027 | the ``KERNEL_PATH`` variable. Both variables are common variables | ||
4028 | used by external Makefiles to point to the kernel source directory. | ||
4029 | |||
4030 | KERNEL_SRC | ||
4031 | The location of the kernel sources. This variable is set to the value | ||
4032 | of the :term:`STAGING_KERNEL_DIR` within | ||
4033 | the :ref:`module <ref-classes-module>` class. For information on | ||
4034 | how this variable is used, see the | ||
4035 | ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`" | ||
4036 | section in the Yocto Project Linux Kernel Development Manual. | ||
4037 | |||
4038 | To help maximize compatibility with out-of-tree drivers used to build | ||
4039 | modules, the OpenEmbedded build system also recognizes and uses the | ||
4040 | :term:`KERNEL_PATH` variable, which is identical | ||
4041 | to the ``KERNEL_SRC`` variable. Both variables are common variables | ||
4042 | used by external Makefiles to point to the kernel source directory. | ||
4043 | |||
4044 | KERNEL_VERSION | ||
4045 | Specifies the version of the kernel as extracted from ``version.h`` | ||
4046 | or ``utsrelease.h`` within the kernel sources. Effects of setting | ||
4047 | this variable do not take affect until the kernel has been | ||
4048 | configured. Consequently, attempting to refer to this variable in | ||
4049 | contexts prior to configuration will not work. | ||
4050 | |||
4051 | KERNELDEPMODDEPEND | ||
4052 | Specifies whether the data referenced through | ||
4053 | :term:`PKGDATA_DIR` is needed or not. The | ||
4054 | ``KERNELDEPMODDEPEND`` does not control whether or not that data | ||
4055 | exists, but simply whether or not it is used. If you do not need to | ||
4056 | use the data, set the ``KERNELDEPMODDEPEND`` variable in your | ||
4057 | ``initramfs`` recipe. Setting the variable there when the data is not | ||
4058 | needed avoids a potential dependency loop. | ||
4059 | |||
4060 | KFEATURE_DESCRIPTION | ||
4061 | Provides a short description of a configuration fragment. You use | ||
4062 | this variable in the ``.scc`` file that describes a configuration | ||
4063 | fragment file. Here is the variable used in a file named ``smp.scc`` | ||
4064 | to describe SMP being enabled: | ||
4065 | :: | ||
4066 | |||
4067 | define KFEATURE_DESCRIPTION "Enable SMP" | ||
4068 | |||
4069 | KMACHINE | ||
4070 | The machine as known by the kernel. Sometimes the machine name used | ||
4071 | by the kernel does not match the machine name used by the | ||
4072 | OpenEmbedded build system. For example, the machine name that the | ||
4073 | OpenEmbedded build system understands as ``core2-32-intel-common`` | ||
4074 | goes by a different name in the Linux Yocto kernel. The kernel | ||
4075 | understands that machine as ``intel-core2-32``. For cases like these, | ||
4076 | the ``KMACHINE`` variable maps the kernel machine name to the | ||
4077 | OpenEmbedded build system machine name. | ||
4078 | |||
4079 | These mappings between different names occur in the Yocto Linux | ||
4080 | Kernel's ``meta`` branch. As an example take a look in the | ||
4081 | ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: | ||
4082 | :: | ||
4083 | |||
4084 | LINUX_VERSION_core2-32-intel-common = "3.19.0" | ||
4085 | COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" | ||
4086 | SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" | ||
4087 | SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" | ||
4088 | KMACHINE_core2-32-intel-common = "intel-core2-32" | ||
4089 | KBRANCH_core2-32-intel-common = "standard/base" | ||
4090 | KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}" | ||
4091 | |||
4092 | The ``KMACHINE`` statement says | ||
4093 | that the kernel understands the machine name as "intel-core2-32". | ||
4094 | However, the OpenEmbedded build system understands the machine as | ||
4095 | "core2-32-intel-common". | ||
4096 | |||
4097 | KTYPE | ||
4098 | Defines the kernel type to be used in assembling the configuration. | ||
4099 | The linux-yocto recipes define "standard", "tiny", and "preempt-rt" | ||
4100 | kernel types. See the ":ref:`kernel-dev/kernel-dev-advanced:kernel types`" | ||
4101 | section in the | ||
4102 | Yocto Project Linux Kernel Development Manual for more information on | ||
4103 | kernel types. | ||
4104 | |||
4105 | You define the ``KTYPE`` variable in the | ||
4106 | :ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`. The | ||
4107 | value you use must match the value used for the | ||
4108 | :term:`LINUX_KERNEL_TYPE` value used by the | ||
4109 | kernel recipe. | ||
4110 | |||
4111 | LABELS | ||
4112 | Provides a list of targets for automatic configuration. | ||
4113 | |||
4114 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | ||
4115 | information on how this variable is used. | ||
4116 | |||
4117 | LAYERDEPENDS | ||
4118 | Lists the layers, separated by spaces, on which this recipe depends. | ||
4119 | Optionally, you can specify a specific layer version for a dependency | ||
4120 | by adding it to the end of the layer name. Here is an example: | ||
4121 | :: | ||
4122 | |||
4123 | LAYERDEPENDS_mylayer = "anotherlayer (=3)" | ||
4124 | |||
4125 | In this previous example, | ||
4126 | version 3 of "anotherlayer" is compared against | ||
4127 | :term:`LAYERVERSION`\ ``_anotherlayer``. | ||
4128 | |||
4129 | An error is produced if any dependency is missing or the version | ||
4130 | numbers (if specified) do not match exactly. This variable is used in | ||
4131 | the ``conf/layer.conf`` file and must be suffixed with the name of | ||
4132 | the specific layer (e.g. ``LAYERDEPENDS_mylayer``). | ||
4133 | |||
4134 | LAYERDIR | ||
4135 | When used inside the ``layer.conf`` configuration file, this variable | ||
4136 | provides the path of the current layer. This variable is not | ||
4137 | available outside of ``layer.conf`` and references are expanded | ||
4138 | immediately when parsing of the file completes. | ||
4139 | |||
4140 | LAYERRECOMMENDS | ||
4141 | Lists the layers, separated by spaces, recommended for use with this | ||
4142 | layer. | ||
4143 | |||
4144 | Optionally, you can specify a specific layer version for a | ||
4145 | recommendation by adding the version to the end of the layer name. | ||
4146 | Here is an example: | ||
4147 | :: | ||
4148 | |||
4149 | LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" | ||
4150 | |||
4151 | In this previous example, version 3 of "anotherlayer" is compared | ||
4152 | against ``LAYERVERSION_anotherlayer``. | ||
4153 | |||
4154 | This variable is used in the ``conf/layer.conf`` file and must be | ||
4155 | suffixed with the name of the specific layer (e.g. | ||
4156 | ``LAYERRECOMMENDS_mylayer``). | ||
4157 | |||
4158 | LAYERSERIES_COMPAT | ||
4159 | Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which | ||
4160 | a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable | ||
4161 | allows the layer maintainer to indicate which combinations of the | ||
4162 | layer and OE-Core can be expected to work. The variable gives the | ||
4163 | system a way to detect when a layer has not been tested with new | ||
4164 | releases of OE-Core (e.g. the layer is not maintained). | ||
4165 | |||
4166 | To specify the OE-Core versions for which a layer is compatible, use | ||
4167 | this variable in your layer's ``conf/layer.conf`` configuration file. | ||
4168 | For the list, use the Yocto Project | ||
4169 | :yocto_wiki:`Release Name </wiki/Releases>` (e.g. | ||
4170 | DISTRO_NAME_NO_CAP). To specify multiple OE-Core versions for the | ||
4171 | layer, use a space-separated list: | ||
4172 | :: | ||
4173 | |||
4174 | LAYERSERIES_COMPAT_layer_root_name = "DISTRO_NAME_NO_CAP DISTRO_NAME_NO_CAP_MINUS_ONE" | ||
4175 | |||
4176 | .. note:: | ||
4177 | |||
4178 | Setting | ||
4179 | LAYERSERIES_COMPAT | ||
4180 | is required by the Yocto Project Compatible version 2 standard. | ||
4181 | The OpenEmbedded build system produces a warning if the variable | ||
4182 | is not set for any given layer. | ||
4183 | |||
4184 | See the ":ref:`dev-manual/dev-manual-common-tasks:creating your own layer`" | ||
4185 | section in the Yocto Project Development Tasks Manual. | ||
4186 | |||
4187 | LAYERVERSION | ||
4188 | Optionally specifies the version of a layer as a single number. You | ||
4189 | can use this within :term:`LAYERDEPENDS` for | ||
4190 | another layer in order to depend on a specific version of the layer. | ||
4191 | This variable is used in the ``conf/layer.conf`` file and must be | ||
4192 | suffixed with the name of the specific layer (e.g. | ||
4193 | ``LAYERVERSION_mylayer``). | ||
4194 | |||
4195 | LD | ||
4196 | The minimal command and arguments used to run the linker. | ||
4197 | |||
4198 | LDFLAGS | ||
4199 | Specifies the flags to pass to the linker. This variable is exported | ||
4200 | to an environment variable and thus made visible to the software | ||
4201 | being built during the compilation step. | ||
4202 | |||
4203 | Default initialization for ``LDFLAGS`` varies depending on what is | ||
4204 | being built: | ||
4205 | |||
4206 | - :term:`TARGET_LDFLAGS` when building for the | ||
4207 | target | ||
4208 | |||
4209 | - :term:`BUILD_LDFLAGS` when building for the | ||
4210 | build host (i.e. ``-native``) | ||
4211 | |||
4212 | - :term:`BUILDSDK_LDFLAGS` when building for | ||
4213 | an SDK (i.e. ``nativesdk-``) | ||
4214 | |||
4215 | LEAD_SONAME | ||
4216 | Specifies the lead (or primary) compiled library file (i.e. ``.so``) | ||
4217 | that the :ref:`debian <ref-classes-debian>` class applies its | ||
4218 | naming policy to given a recipe that packages multiple libraries. | ||
4219 | |||
4220 | This variable works in conjunction with the ``debian`` class. | ||
4221 | |||
4222 | LIC_FILES_CHKSUM | ||
4223 | Checksums of the license text in the recipe source code. | ||
4224 | |||
4225 | This variable tracks changes in license text of the source code | ||
4226 | files. If the license text is changed, it will trigger a build | ||
4227 | failure, which gives the developer an opportunity to review any | ||
4228 | license change. | ||
4229 | |||
4230 | This variable must be defined for all recipes (unless | ||
4231 | :term:`LICENSE` is set to "CLOSED"). | ||
4232 | |||
4233 | For more information, see the ":ref:`usingpoky-configuring-lic_files_chksum`" | ||
4234 | section in the Yocto Project Development Tasks Manual. | ||
4235 | |||
4236 | LICENSE | ||
4237 | The list of source licenses for the recipe. Follow these rules: | ||
4238 | |||
4239 | - Do not use spaces within individual license names. | ||
4240 | |||
4241 | - Separate license names using \| (pipe) when there is a choice | ||
4242 | between licenses. | ||
4243 | |||
4244 | - Separate license names using & (ampersand) when multiple licenses | ||
4245 | exist that cover different parts of the source. | ||
4246 | |||
4247 | - You can use spaces between license names. | ||
4248 | |||
4249 | - For standard licenses, use the names of the files in | ||
4250 | ``meta/files/common-licenses/`` or the | ||
4251 | :term:`SPDXLICENSEMAP` flag names defined in | ||
4252 | ``meta/conf/licenses.conf``. | ||
4253 | |||
4254 | Here are some examples: | ||
4255 | :: | ||
4256 | |||
4257 | LICENSE = "LGPLv2.1 | GPLv3" | ||
4258 | LICENSE = "MPL-1 & LGPLv2.1" | ||
4259 | LICENSE = "GPLv2+" | ||
4260 | |||
4261 | The first example is from the | ||
4262 | recipes for Qt, which the user may choose to distribute under either | ||
4263 | the LGPL version 2.1 or GPL version 3. The second example is from | ||
4264 | Cairo where two licenses cover different parts of the source code. | ||
4265 | The final example is from ``sysstat``, which presents a single | ||
4266 | license. | ||
4267 | |||
4268 | You can also specify licenses on a per-package basis to handle | ||
4269 | situations where components of the output have different licenses. | ||
4270 | For example, a piece of software whose code is licensed under GPLv2 | ||
4271 | but has accompanying documentation licensed under the GNU Free | ||
4272 | Documentation License 1.2 could be specified as follows: | ||
4273 | :: | ||
4274 | |||
4275 | LICENSE = "GFDL-1.2 & GPLv2" | ||
4276 | LICENSE_${PN} = "GPLv2" | ||
4277 | LICENSE_${PN}-doc = "GFDL-1.2" | ||
4278 | |||
4279 | LICENSE_CREATE_PACKAGE | ||
4280 | Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded | ||
4281 | build system to create an extra package (i.e. | ||
4282 | ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add | ||
4283 | those packages to the | ||
4284 | :term:`RRECOMMENDS`\ ``_${PN}``. | ||
4285 | |||
4286 | The ``${PN}-lic`` package installs a directory in | ||
4287 | ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base | ||
4288 | name, and installs files in that directory that contain license and | ||
4289 | copyright information (i.e. copies of the appropriate license files | ||
4290 | from ``meta/common-licenses`` that match the licenses specified in | ||
4291 | the :term:`LICENSE` variable of the recipe metadata | ||
4292 | and copies of files marked in | ||
4293 | :term:`LIC_FILES_CHKSUM` as containing | ||
4294 | license text). | ||
4295 | |||
4296 | For related information on providing license text, see the | ||
4297 | :term:`COPY_LIC_DIRS` variable, the | ||
4298 | :term:`COPY_LIC_MANIFEST` variable, and the | ||
4299 | ":ref:`dev-manual/dev-manual-common-tasks:providing license text`" | ||
4300 | section in the Yocto Project Development Tasks Manual. | ||
4301 | |||
4302 | LICENSE_FLAGS | ||
4303 | Specifies additional flags for a recipe you must whitelist through | ||
4304 | :term:`LICENSE_FLAGS_WHITELIST` in | ||
4305 | order to allow the recipe to be built. When providing multiple flags, | ||
4306 | separate them with spaces. | ||
4307 | |||
4308 | This value is independent of :term:`LICENSE` and is | ||
4309 | typically used to mark recipes that might require additional licenses | ||
4310 | in order to be used in a commercial product. For more information, | ||
4311 | see the | ||
4312 | ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`" | ||
4313 | section in the Yocto Project Development Tasks Manual. | ||
4314 | |||
4315 | LICENSE_FLAGS_WHITELIST | ||
4316 | Lists license flags that when specified in | ||
4317 | :term:`LICENSE_FLAGS` within a recipe should not | ||
4318 | prevent that recipe from being built. This practice is otherwise | ||
4319 | known as "whitelisting" license flags. For more information, see the | ||
4320 | ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`" | ||
4321 | section in the Yocto Project Development Tasks Manual. | ||
4322 | |||
4323 | LICENSE_PATH | ||
4324 | Path to additional licenses used during the build. By default, the | ||
4325 | OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the | ||
4326 | directory that holds common license text used during the build. The | ||
4327 | ``LICENSE_PATH`` variable allows you to extend that location to other | ||
4328 | areas that have additional licenses: | ||
4329 | :: | ||
4330 | |||
4331 | LICENSE_PATH += "path-to-additional-common-licenses" | ||
4332 | |||
4333 | LINUX_KERNEL_TYPE | ||
4334 | Defines the kernel type to be used in assembling the configuration. | ||
4335 | The linux-yocto recipes define "standard", "tiny", and "preempt-rt" | ||
4336 | kernel types. See the ":ref:`kernel-dev/kernel-dev-advanced:kernel types`" | ||
4337 | section in the | ||
4338 | Yocto Project Linux Kernel Development Manual for more information on | ||
4339 | kernel types. | ||
4340 | |||
4341 | If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to | ||
4342 | "standard". Together with :term:`KMACHINE`, the | ||
4343 | ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by | ||
4344 | the kernel tools to find the appropriate description within the | ||
4345 | kernel :term:`Metadata` with which to build out the sources | ||
4346 | and configuration. | ||
4347 | |||
4348 | LINUX_VERSION | ||
4349 | The Linux version from ``kernel.org`` on which the Linux kernel image | ||
4350 | being built using the OpenEmbedded build system is based. You define | ||
4351 | this variable in the kernel recipe. For example, the | ||
4352 | ``linux-yocto-3.4.bb`` kernel recipe found in | ||
4353 | ``meta/recipes-kernel/linux`` defines the variables as follows: | ||
4354 | :: | ||
4355 | |||
4356 | LINUX_VERSION ?= "3.4.24" | ||
4357 | |||
4358 | The ``LINUX_VERSION`` variable is used to define :term:`PV` | ||
4359 | for the recipe: | ||
4360 | :: | ||
4361 | |||
4362 | PV = "${LINUX_VERSION}+git${SRCPV}" | ||
4363 | |||
4364 | LINUX_VERSION_EXTENSION | ||
4365 | A string extension compiled into the version string of the Linux | ||
4366 | kernel built with the OpenEmbedded build system. You define this | ||
4367 | variable in the kernel recipe. For example, the linux-yocto kernel | ||
4368 | recipes all define the variable as follows: | ||
4369 | :: | ||
4370 | |||
4371 | LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" | ||
4372 | |||
4373 | Defining this variable essentially sets the Linux kernel | ||
4374 | configuration item ``CONFIG_LOCALVERSION``, which is visible through | ||
4375 | the ``uname`` command. Here is an example that shows the extension | ||
4376 | assuming it was set as previously shown: | ||
4377 | :: | ||
4378 | |||
4379 | $ uname -r | ||
4380 | 3.7.0-rc8-custom | ||
4381 | |||
4382 | LOG_DIR | ||
4383 | Specifies the directory to which the OpenEmbedded build system writes | ||
4384 | overall log files. The default directory is ``${TMPDIR}/log``. | ||
4385 | |||
4386 | For the directory containing logs specific to each task, see the | ||
4387 | :term:`T` variable. | ||
4388 | |||
4389 | MACHINE | ||
4390 | Specifies the target device for which the image is built. You define | ||
4391 | ``MACHINE`` in the ``local.conf`` file found in the | ||
4392 | :term:`Build Directory`. By default, ``MACHINE`` is set to | ||
4393 | "qemux86", which is an x86-based architecture machine to be emulated | ||
4394 | using QEMU: | ||
4395 | :: | ||
4396 | |||
4397 | MACHINE ?= "qemux86" | ||
4398 | |||
4399 | The variable corresponds to a machine configuration file of the same | ||
4400 | name, through which machine-specific configurations are set. Thus, | ||
4401 | when ``MACHINE`` is set to "qemux86" there exists the corresponding | ||
4402 | ``qemux86.conf`` machine configuration file, which can be found in | ||
4403 | the :term:`Source Directory` in | ||
4404 | ``meta/conf/machine``. | ||
4405 | |||
4406 | The list of machines supported by the Yocto Project as shipped | ||
4407 | include the following: | ||
4408 | :: | ||
4409 | |||
4410 | MACHINE ?= "qemuarm" | ||
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 | ||
4423 | boards, which are provided in the ``meta-yocto-bsp`` layer. | ||
4424 | |||
4425 | .. note:: | ||
4426 | |||
4427 | Adding additional Board Support Package (BSP) layers to your | ||
4428 | configuration adds new possible settings for | ||
4429 | MACHINE | ||
4430 | . | ||
4431 | |||
4432 | MACHINE_ARCH | ||
4433 | Specifies the name of the machine-specific architecture. This | ||
4434 | variable is set automatically from :term:`MACHINE` or | ||
4435 | :term:`TUNE_PKGARCH`. You should not hand-edit | ||
4436 | the ``MACHINE_ARCH`` variable. | ||
4437 | |||
4438 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS | ||
4439 | A list of required machine-specific packages to install as part of | ||
4440 | the image being built. The build process depends on these packages | ||
4441 | being present. Furthermore, because this is a "machine-essential" | ||
4442 | variable, the list of packages are essential for the machine to boot. | ||
4443 | The impact of this variable affects images based on | ||
4444 | ``packagegroup-core-boot``, including the ``core-image-minimal`` | ||
4445 | image. | ||
4446 | |||
4447 | This variable is similar to the | ||
4448 | ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception | ||
4449 | that the image being built has a build dependency on the variable's | ||
4450 | list of packages. In other words, the image will not build if a file | ||
4451 | in this list is not found. | ||
4452 | |||
4453 | As an example, suppose the machine for which you are building | ||
4454 | requires ``example-init`` to be run during boot to initialize the | ||
4455 | hardware. In this case, you would use the following in the machine's | ||
4456 | ``.conf`` configuration file: | ||
4457 | :: | ||
4458 | |||
4459 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" | ||
4460 | |||
4461 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS | ||
4462 | A list of recommended machine-specific packages to install as part of | ||
4463 | the image being built. The build process does not depend on these | ||
4464 | packages being present. However, because this is a | ||
4465 | "machine-essential" variable, the list of packages are essential for | ||
4466 | the machine to boot. The impact of this variable affects images based | ||
4467 | on ``packagegroup-core-boot``, including the ``core-image-minimal`` | ||
4468 | image. | ||
4469 | |||
4470 | This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` | ||
4471 | variable with the exception that the image being built does not have | ||
4472 | a build dependency on the variable's list of packages. In other | ||
4473 | words, the image will still build if a package in this list is not | ||
4474 | found. Typically, this variable is used to handle essential kernel | ||
4475 | modules, whose functionality may be selected to be built into the | ||
4476 | kernel rather than as a module, in which case a package will not be | ||
4477 | produced. | ||
4478 | |||
4479 | Consider an example where you have a custom kernel where a specific | ||
4480 | touchscreen driver is required for the machine to be usable. However, | ||
4481 | the driver can be built as a module or into the kernel depending on | ||
4482 | the kernel configuration. If the driver is built as a module, you | ||
4483 | want it to be installed. But, when the driver is built into the | ||
4484 | kernel, you still want the build to succeed. This variable sets up a | ||
4485 | "recommends" relationship so that in the latter case, the build will | ||
4486 | not fail due to the missing package. To accomplish this, assuming the | ||
4487 | package for the module was called ``kernel-module-ab123``, you would | ||
4488 | use the following in the machine's ``.conf`` configuration file: | ||
4489 | :: | ||
4490 | |||
4491 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" | ||
4492 | |||
4493 | .. note:: | ||
4494 | |||
4495 | In this example, the | ||
4496 | kernel-module-ab123 | ||
4497 | recipe needs to explicitly set its | ||
4498 | PACKAGES | ||
4499 | variable to ensure that BitBake does not use the kernel recipe's | ||
4500 | PACKAGES_DYNAMIC | ||
4501 | variable to satisfy the dependency. | ||
4502 | |||
4503 | Some examples of these machine essentials are flash, screen, | ||
4504 | keyboard, mouse, or touchscreen drivers (depending on the machine). | ||
4505 | |||
4506 | MACHINE_EXTRA_RDEPENDS | ||
4507 | A list of machine-specific packages to install as part of the image | ||
4508 | being built that are not essential for the machine to boot. However, | ||
4509 | the build process for more fully-featured images depends on the | ||
4510 | packages being present. | ||
4511 | |||
4512 | This variable affects all images based on ``packagegroup-base``, | ||
4513 | which does not include the ``core-image-minimal`` or | ||
4514 | ``core-image-full-cmdline`` images. | ||
4515 | |||
4516 | The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable | ||
4517 | with the exception that the image being built has a build dependency | ||
4518 | on the variable's list of packages. In other words, the image will | ||
4519 | not build if a file in this list is not found. | ||
4520 | |||
4521 | An example is a machine that has WiFi capability but is not essential | ||
4522 | for the machine to boot the image. However, if you are building a | ||
4523 | more fully-featured image, you want to enable the WiFi. The package | ||
4524 | containing the firmware for the WiFi hardware is always expected to | ||
4525 | exist, so it is acceptable for the build process to depend upon | ||
4526 | finding the package. In this case, assuming the package for the | ||
4527 | firmware was called ``wifidriver-firmware``, you would use the | ||
4528 | following in the ``.conf`` file for the machine: | ||
4529 | :: | ||
4530 | |||
4531 | MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" | ||
4532 | |||
4533 | MACHINE_EXTRA_RRECOMMENDS | ||
4534 | A list of machine-specific packages to install as part of the image | ||
4535 | being built that are not essential for booting the machine. The image | ||
4536 | being built has no build dependency on this list of packages. | ||
4537 | |||
4538 | This variable affects only images based on ``packagegroup-base``, | ||
4539 | which does not include the ``core-image-minimal`` or | ||
4540 | ``core-image-full-cmdline`` images. | ||
4541 | |||
4542 | This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable | ||
4543 | with the exception that the image being built does not have a build | ||
4544 | dependency on the variable's list of packages. In other words, the | ||
4545 | image will build if a file in this list is not found. | ||
4546 | |||
4547 | An example is a machine that has WiFi capability but is not essential | ||
4548 | For the machine to boot the image. However, if you are building a | ||
4549 | more fully-featured image, you want to enable WiFi. In this case, the | ||
4550 | package containing the WiFi kernel module will not be produced if the | ||
4551 | WiFi driver is built into the kernel, in which case you still want | ||
4552 | the build to succeed instead of failing as a result of the package | ||
4553 | not being found. To accomplish this, assuming the package for the | ||
4554 | module was called ``kernel-module-examplewifi``, you would use the | ||
4555 | following in the ``.conf`` file for the machine: | ||
4556 | :: | ||
4557 | |||
4558 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" | ||
4559 | |||
4560 | MACHINE_FEATURES | ||
4561 | Specifies the list of hardware features the | ||
4562 | :term:`MACHINE` is capable of supporting. For related | ||
4563 | information on enabling features, see the | ||
4564 | :term:`DISTRO_FEATURES`, | ||
4565 | :term:`COMBINED_FEATURES`, and | ||
4566 | :term:`IMAGE_FEATURES` variables. | ||
4567 | |||
4568 | For a list of hardware features supported by the Yocto Project as | ||
4569 | shipped, see the "`Machine Features <#ref-features-machine>`__" | ||
4570 | section. | ||
4571 | |||
4572 | MACHINE_FEATURES_BACKFILL | ||
4573 | Features to be added to ``MACHINE_FEATURES`` if not also present in | ||
4574 | ``MACHINE_FEATURES_BACKFILL_CONSIDERED``. | ||
4575 | |||
4576 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | ||
4577 | not intended to be user-configurable. It is best to just reference | ||
4578 | the variable to see which machine features are being backfilled for | ||
4579 | all machine configurations. See the "`Feature | ||
4580 | Backfilling <#ref-features-backfill>`__" section for more | ||
4581 | information. | ||
4582 | |||
4583 | MACHINE_FEATURES_BACKFILL_CONSIDERED | ||
4584 | Features from ``MACHINE_FEATURES_BACKFILL`` that should not be | ||
4585 | backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See | ||
4586 | the "`Feature Backfilling <#ref-features-backfill>`__" section for | ||
4587 | more information. | ||
4588 | |||
4589 | MACHINEOVERRIDES | ||
4590 | A colon-separated list of overrides that apply to the current | ||
4591 | machine. By default, this list includes the value of | ||
4592 | :term:`MACHINE`. | ||
4593 | |||
4594 | You can extend ``MACHINEOVERRIDES`` to add extra overrides that | ||
4595 | should apply to a machine. For example, all machines emulated in QEMU | ||
4596 | (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named | ||
4597 | ``meta/conf/machine/include/qemu.inc`` that prepends the following | ||
4598 | override to ``MACHINEOVERRIDES``: | ||
4599 | :: | ||
4600 | |||
4601 | MACHINEOVERRIDES =. "qemuall:" | ||
4602 | |||
4603 | This | ||
4604 | override allows variables to be overriden for all machines emulated | ||
4605 | in QEMU, like in the following example from the ``connman-conf`` | ||
4606 | recipe: | ||
4607 | :: | ||
4608 | |||
4609 | SRC_URI_append_qemuall = "file://wired.config \ | ||
4610 | file://wired-setup \ | ||
4611 | " | ||
4612 | |||
4613 | The underlying mechanism behind | ||
4614 | ``MACHINEOVERRIDES`` is simply that it is included in the default | ||
4615 | value of :term:`OVERRIDES`. | ||
4616 | |||
4617 | MAINTAINER | ||
4618 | The email address of the distribution maintainer. | ||
4619 | |||
4620 | MIRRORS | ||
4621 | Specifies additional paths from which the OpenEmbedded build system | ||
4622 | gets source code. When the build system searches for source code, it | ||
4623 | first tries the local download directory. If that location fails, the | ||
4624 | build system tries locations defined by | ||
4625 | :term:`PREMIRRORS`, the upstream source, and then | ||
4626 | locations specified by ``MIRRORS`` in that order. | ||
4627 | |||
4628 | Assuming your distribution (:term:`DISTRO`) is "poky", | ||
4629 | the default value for ``MIRRORS`` is defined in the | ||
4630 | ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. | ||
4631 | |||
4632 | MLPREFIX | ||
4633 | Specifies a prefix has been added to :term:`PN` to create a | ||
4634 | special version of a recipe or package (i.e. a Multilib version). The | ||
4635 | variable is used in places where the prefix needs to be added to or | ||
4636 | removed from a the name (e.g. the :term:`BPN` variable). | ||
4637 | ``MLPREFIX`` gets set when a prefix has been added to ``PN``. | ||
4638 | |||
4639 | .. note:: | ||
4640 | |||
4641 | The "ML" in | ||
4642 | MLPREFIX | ||
4643 | stands for "MultiLib". This representation is historical and comes | ||
4644 | from a time when | ||
4645 | nativesdk | ||
4646 | was a suffix rather than a prefix on the recipe name. When | ||
4647 | nativesdk | ||
4648 | was turned into a prefix, it made sense to set | ||
4649 | MLPREFIX | ||
4650 | for it as well. | ||
4651 | |||
4652 | To help understand when ``MLPREFIX`` might be needed, consider when | ||
4653 | :term:`BBCLASSEXTEND` is used to provide a | ||
4654 | ``nativesdk`` version of a recipe in addition to the target version. | ||
4655 | If that recipe declares build-time dependencies on tasks in other | ||
4656 | recipes by using :term:`DEPENDS`, then a dependency on | ||
4657 | "foo" will automatically get rewritten to a dependency on | ||
4658 | "nativesdk-foo". However, dependencies like the following will not | ||
4659 | get rewritten automatically: | ||
4660 | :: | ||
4661 | |||
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 | |||
4670 | module_autoload | ||
4671 | This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD`` | ||
4672 | variable. You should replace all occurrences of ``module_autoload`` | ||
4673 | with additions to ``KERNEL_MODULE_AUTOLOAD``, for example: | ||
4674 | :: | ||
4675 | |||
4676 | module_autoload_rfcomm = "rfcomm" | ||
4677 | |||
4678 | should now be replaced with: | ||
4679 | :: | ||
4680 | |||
4681 | KERNEL_MODULE_AUTOLOAD += "rfcomm" | ||
4682 | |||
4683 | See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. | ||
4684 | |||
4685 | module_conf | ||
4686 | Specifies `modprobe.d <http://linux.die.net/man/5/modprobe.d>`_ | ||
4687 | syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` | ||
4688 | file. | ||
4689 | |||
4690 | You can use this variable anywhere that it can be recognized by the | ||
4691 | kernel recipe or out-of-tree kernel module recipe (e.g. a machine | ||
4692 | configuration file, a distribution configuration file, an append file | ||
4693 | for the recipe, or the recipe itself). If you use this variable, you | ||
4694 | must also be sure to list the module name in the | ||
4695 | :term:`KERNEL_MODULE_AUTOLOAD` | ||
4696 | variable. | ||
4697 | |||
4698 | Here is the general syntax: | ||
4699 | :: | ||
4700 | |||
4701 | module_conf_module_name = "modprobe.d-syntax" | ||
4702 | |||
4703 | You must use the kernel module name override. | ||
4704 | |||
4705 | Run ``man modprobe.d`` in the shell to find out more information on | ||
4706 | the exact syntax you want to provide with ``module_conf``. | ||
4707 | |||
4708 | Including ``module_conf`` causes the OpenEmbedded build system to | ||
4709 | populate the ``/etc/modprobe.d/modname.conf`` file with | ||
4710 | ``modprobe.d`` syntax lines. Here is an example that adds the options | ||
4711 | ``arg1`` and ``arg2`` to a module named ``mymodule``: | ||
4712 | :: | ||
4713 | |||
4714 | module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" | ||
4715 | |||
4716 | For information on how to specify kernel modules to auto-load on | ||
4717 | boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable. | ||
4718 | |||
4719 | MODULE_TARBALL_DEPLOY | ||
4720 | Controls creation of the ``modules-*.tgz`` file. Set this variable to | ||
4721 | "0" to disable creation of this file, which contains all of the | ||
4722 | kernel modules resulting from a kernel build. | ||
4723 | |||
4724 | MODULE_TARBALL_LINK_NAME | ||
4725 | The link name of the kernel module tarball. This variable is set in | ||
4726 | the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
4727 | :: | ||
4728 | |||
4729 | MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
4730 | |||
4731 | The value | ||
4732 | of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the | ||
4733 | same file, has the following value: | ||
4734 | :: | ||
4735 | |||
4736 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
4737 | |||
4738 | See the :term:`MACHINE` variable for additional information. | ||
4739 | |||
4740 | MODULE_TARBALL_NAME | ||
4741 | The base name of the kernel module tarball. This variable is set in | ||
4742 | the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
4743 | :: | ||
4744 | |||
4745 | MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
4746 | |||
4747 | The value of the :term:`KERNEL_ARTIFACT_NAME` variable, | ||
4748 | which is set in the same file, has the following value: | ||
4749 | :: | ||
4750 | |||
4751 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
4752 | |||
4753 | MULTIMACH_TARGET_SYS | ||
4754 | Uniquely identifies the type of the target system for which packages | ||
4755 | are being built. This variable allows output for different types of | ||
4756 | target systems to be put into different subdirectories of the same | ||
4757 | output directory. | ||
4758 | |||
4759 | The default value of this variable is: | ||
4760 | :: | ||
4761 | |||
4762 | ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} | ||
4763 | |||
4764 | Some classes (e.g. | ||
4765 | :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the | ||
4766 | ``MULTIMACH_TARGET_SYS`` value. | ||
4767 | |||
4768 | See the :term:`STAMP` variable for an example. See the | ||
4769 | :term:`STAGING_DIR_TARGET` variable for more information. | ||
4770 | |||
4771 | NATIVELSBSTRING | ||
4772 | A string identifying the host distribution. Strings consist of the | ||
4773 | host distributor ID followed by the release, as reported by the | ||
4774 | ``lsb_release`` tool or as read from ``/etc/lsb-release``. For | ||
4775 | example, when running a build on Ubuntu 12.10, the value is | ||
4776 | "Ubuntu-12.10". If this information is unable to be determined, the | ||
4777 | value resolves to "Unknown". | ||
4778 | |||
4779 | This variable is used by default to isolate native shared state | ||
4780 | packages for different distributions (e.g. to avoid problems with | ||
4781 | ``glibc`` version incompatibilities). Additionally, the variable is | ||
4782 | checked against | ||
4783 | :term:`SANITY_TESTED_DISTROS` if that | ||
4784 | variable is set. | ||
4785 | |||
4786 | NM | ||
4787 | The minimal command and arguments to run ``nm``. | ||
4788 | |||
4789 | NO_GENERIC_LICENSE | ||
4790 | Avoids QA errors when you use a non-common, non-CLOSED license in a | ||
4791 | recipe. Packages exist, such as the linux-firmware package, with many | ||
4792 | licenses that are not in any way common. Also, new licenses are added | ||
4793 | occasionally to avoid introducing a lot of common license files, | ||
4794 | which are only applicable to a specific package. | ||
4795 | ``NO_GENERIC_LICENSE`` is used to allow copying a license that does | ||
4796 | not exist in common licenses. | ||
4797 | |||
4798 | The following example shows how to add ``NO_GENERIC_LICENSE`` to a | ||
4799 | recipe: | ||
4800 | :: | ||
4801 | |||
4802 | NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" | ||
4803 | |||
4804 | The following is an example that | ||
4805 | uses the ``LICENSE.Abilis.txt`` file as the license from the fetched | ||
4806 | source: | ||
4807 | :: | ||
4808 | |||
4809 | NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" | ||
4810 | |||
4811 | NO_RECOMMENDATIONS | ||
4812 | Prevents installation of all "recommended-only" packages. | ||
4813 | Recommended-only packages are packages installed only through the | ||
4814 | :term:`RRECOMMENDS` variable). Setting the | ||
4815 | ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: :: | ||
4816 | |||
4817 | NO_RECOMMENDATIONS = "1" | ||
4818 | |||
4819 | You can set this variable globally in your ``local.conf`` file or you | ||
4820 | can attach it to a specific image recipe by using the recipe name | ||
4821 | override: :: | ||
4822 | |||
4823 | NO_RECOMMENDATIONS_pn-target_image = "1" | ||
4824 | |||
4825 | It is important to realize that if you choose to not install packages | ||
4826 | using this variable and some other packages are dependent on them | ||
4827 | (i.e. listed in a recipe's :term:`RDEPENDS` | ||
4828 | variable), the OpenEmbedded build system ignores your request and | ||
4829 | will install the packages to avoid dependency errors. | ||
4830 | |||
4831 | .. note:: | ||
4832 | |||
4833 | Some recommended packages might be required for certain system | ||
4834 | functionality, such as kernel modules. It is up to you to add | ||
4835 | packages with the IMAGE_INSTALL variable. | ||
4836 | |||
4837 | Support for this variable exists only when using the IPK and RPM | ||
4838 | packaging backend. Support does not exist for DEB. | ||
4839 | |||
4840 | See the :term:`BAD_RECOMMENDATIONS` and | ||
4841 | the :term:`PACKAGE_EXCLUDE` variables for | ||
4842 | related information. | ||
4843 | |||
4844 | NOAUTOPACKAGEDEBUG | ||
4845 | Disables auto package from splitting ``.debug`` files. If a recipe | ||
4846 | requires ``FILES_${PN}-dbg`` to be set manually, the | ||
4847 | ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the | ||
4848 | content of the debug package. For example: | ||
4849 | :: | ||
4850 | |||
4851 | NOAUTOPACKAGEDEBUG = "1" | ||
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 | |||
4856 | OBJCOPY | ||
4857 | The minimal command and arguments to run ``objcopy``. | ||
4858 | |||
4859 | OBJDUMP | ||
4860 | The minimal command and arguments to run ``objdump``. | ||
4861 | |||
4862 | OE_BINCONFIG_EXTRA_MANGLE | ||
4863 | When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, | ||
4864 | this variable specifies additional arguments passed to the "sed" | ||
4865 | command. The sed command alters any paths in configuration scripts | ||
4866 | that have been set up during compilation. Inheriting this class | ||
4867 | results in all paths in these scripts being changed to point into the | ||
4868 | ``sysroots/`` directory so that all builds that use the script will | ||
4869 | use the correct directories for the cross compiling layout. | ||
4870 | |||
4871 | See the ``meta/classes/binconfig.bbclass`` in the | ||
4872 | :term:`Source Directory` for details on how this class | ||
4873 | applies these additional sed command arguments. For general | ||
4874 | information on the ``binconfig`` class, see the | ||
4875 | ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. | ||
4876 | |||
4877 | OE_IMPORTS | ||
4878 | An internal variable used to tell the OpenEmbedded build system what | ||
4879 | Python modules to import for every Python function run by the system. | ||
4880 | |||
4881 | .. note:: | ||
4882 | |||
4883 | Do not set this variable. It is for internal use only. | ||
4884 | |||
4885 | OE_INIT_ENV_SCRIPT | ||
4886 | The name of the build environment setup script for the purposes of | ||
4887 | setting up the environment within the extensible SDK. The default | ||
4888 | value is "oe-init-build-env". | ||
4889 | |||
4890 | If you use a custom script to set up your build environment, set the | ||
4891 | ``OE_INIT_ENV_SCRIPT`` variable to its name. | ||
4892 | |||
4893 | OE_TERMINAL | ||
4894 | Controls how the OpenEmbedded build system spawns interactive | ||
4895 | terminals on the host development system (e.g. using the BitBake | ||
4896 | command with the ``-c devshell`` command-line option). For more | ||
4897 | information, see the ":ref:`platdev-appdev-devshell`" section in | ||
4898 | the Yocto Project Development Tasks Manual. | ||
4899 | |||
4900 | You can use the following values for the ``OE_TERMINAL`` variable: | ||
4901 | |||
4902 | - auto | ||
4903 | - gnome | ||
4904 | - xfce | ||
4905 | - rxvt | ||
4906 | - screen | ||
4907 | - konsole | ||
4908 | - none | ||
4909 | |||
4910 | OEROOT | ||
4911 | The directory from which the top-level build environment setup script | ||
4912 | is sourced. The Yocto Project provides a top-level build environment | ||
4913 | setup script: ````` <#structure-core-script>`__. When you run this | ||
4914 | script, the ``OEROOT`` variable resolves to the directory that | ||
4915 | contains the script. | ||
4916 | |||
4917 | For additional information on how this variable is used, see the | ||
4918 | initialization script. | ||
4919 | |||
4920 | OLDEST_KERNEL | ||
4921 | Declares the oldest version of the Linux kernel that the produced | ||
4922 | binaries must support. This variable is passed into the build of the | ||
4923 | Embedded GNU C Library (``glibc``). | ||
4924 | |||
4925 | The default for this variable comes from the | ||
4926 | ``meta/conf/bitbake.conf`` configuration file. You can override this | ||
4927 | default by setting the variable in a custom distribution | ||
4928 | configuration file. | ||
4929 | |||
4930 | OVERRIDES | ||
4931 | A colon-separated list of overrides that currently apply. Overrides | ||
4932 | are a BitBake mechanism that allows variables to be selectively | ||
4933 | overridden at the end of parsing. The set of overrides in | ||
4934 | ``OVERRIDES`` represents the "state" during building, which includes | ||
4935 | the current recipe being built, the machine for which it is being | ||
4936 | built, and so forth. | ||
4937 | |||
4938 | As an example, if the string "an-override" appears as an element in | ||
4939 | the colon-separated list in ``OVERRIDES``, then the following | ||
4940 | assignment will override ``FOO`` with the value "overridden" at the | ||
4941 | end of parsing: | ||
4942 | :: | ||
4943 | |||
4944 | FOO_an-override = "overridden" | ||
4945 | |||
4946 | See the | ||
4947 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" | ||
4948 | section in the BitBake User Manual for more information on the | ||
4949 | overrides mechanism. | ||
4950 | |||
4951 | The default value of ``OVERRIDES`` includes the values of the | ||
4952 | :term:`CLASSOVERRIDE`, | ||
4953 | :term:`MACHINEOVERRIDES`, and | ||
4954 | :term:`DISTROOVERRIDES` variables. Another | ||
4955 | important override included by default is ``pn-${PN}``. This override | ||
4956 | allows variables to be set for a single recipe within configuration | ||
4957 | (``.conf``) files. Here is an example: | ||
4958 | :: | ||
4959 | |||
4960 | FOO_pn-myrecipe = "myrecipe-specific value" | ||
4961 | |||
4962 | .. note:: | ||
4963 | |||
4964 | An easy way to see what overrides apply is to search for | ||
4965 | OVERRIDES | ||
4966 | in the output of the | ||
4967 | bitbake -e | ||
4968 | command. See the " | ||
4969 | Viewing Variable Values | ||
4970 | " section in the Yocto Project Development Tasks Manual for more | ||
4971 | information. | ||
4972 | |||
4973 | P | ||
4974 | The recipe name and version. ``P`` is comprised of the following: | ||
4975 | :: | ||
4976 | |||
4977 | ${PN}-${PV} | ||
4978 | |||
4979 | PACKAGE_ADD_METADATA | ||
4980 | This variable defines additional metdata to add to packages. | ||
4981 | |||
4982 | You may find you need to inject additional metadata into packages. | ||
4983 | This variable allows you to do that by setting the injected data as | ||
4984 | the value. Multiple fields can be added by splitting the content with | ||
4985 | the literal separator "\n". | ||
4986 | |||
4987 | The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable | ||
4988 | to do package type specific settings. It can also be made package | ||
4989 | specific by using the package name as a suffix. | ||
4990 | |||
4991 | You can find out more about applying this variable in the | ||
4992 | ":ref:`dev-manual/dev-manual-common-tasks:adding custom metadata to packages`" | ||
4993 | section in the Yocto Project Development Tasks Manual. | ||
4994 | |||
4995 | PACKAGE_ARCH | ||
4996 | The architecture of the resulting package or packages. | ||
4997 | |||
4998 | By default, the value of this variable is set to | ||
4999 | :term:`TUNE_PKGARCH` when building for the | ||
5000 | target, :term:`BUILD_ARCH` when building for the | ||
5001 | build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the | ||
5002 | SDK. | ||
5003 | |||
5004 | .. note:: | ||
5005 | |||
5006 | See | ||
5007 | SDK_ARCH | ||
5008 | for more information. | ||
5009 | |||
5010 | However, if your recipe's output packages are built specific to the | ||
5011 | target machine rather than generally for the architecture of the | ||
5012 | machine, you should set ``PACKAGE_ARCH`` to the value of | ||
5013 | :term:`MACHINE_ARCH` in the recipe as follows: | ||
5014 | :: | ||
5015 | |||
5016 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
5017 | |||
5018 | PACKAGE_ARCHS | ||
5019 | Specifies a list of architectures compatible with the target machine. | ||
5020 | This variable is set automatically and should not normally be | ||
5021 | hand-edited. Entries are separated using spaces and listed in order | ||
5022 | of priority. The default value for ``PACKAGE_ARCHS`` is "all any | ||
5023 | noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". | ||
5024 | |||
5025 | PACKAGE_BEFORE_PN | ||
5026 | Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so | ||
5027 | that those added packages can pick up files that would normally be | ||
5028 | included in the default package. | ||
5029 | |||
5030 | PACKAGE_CLASSES | ||
5031 | This variable, which is set in the ``local.conf`` configuration file | ||
5032 | found in the ``conf`` folder of the | ||
5033 | :term:`Build Directory`, specifies the package manager the | ||
5034 | OpenEmbedded build system uses when packaging data. | ||
5035 | |||
5036 | You can provide one or more of the following arguments for the | ||
5037 | variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk | ||
5038 | package_tar" | ||
5039 | |||
5040 | .. note:: | ||
5041 | |||
5042 | While it is a legal option, the | ||
5043 | package_tar | ||
5044 | class has limited functionality due to no support for package | ||
5045 | dependencies by that backend. Therefore, it is recommended that | ||
5046 | you do not use it. | ||
5047 | |||
5048 | The build system uses only the first argument in the list as the | ||
5049 | package manager when creating your image or SDK. However, packages | ||
5050 | will be created using any additional packaging classes you specify. | ||
5051 | For example, if you use the following in your ``local.conf`` file: | ||
5052 | :: | ||
5053 | |||
5054 | PACKAGE_CLASSES ?= "package_ipk" | ||
5055 | |||
5056 | The OpenEmbedded build system uses | ||
5057 | the IPK package manager to create your image or SDK. | ||
5058 | |||
5059 | For information on packaging and build performance effects as a | ||
5060 | result of the package manager in use, see the | ||
5061 | ":ref:`package.bbclass <ref-classes-package>`" section. | ||
5062 | |||
5063 | PACKAGE_DEBUG_SPLIT_STYLE | ||
5064 | Determines how to split up the binary and debug information when | ||
5065 | creating ``*-dbg`` packages to be used with the GNU Project Debugger | ||
5066 | (GDB). | ||
5067 | |||
5068 | With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control | ||
5069 | where debug information, which can include or exclude source files, | ||
5070 | is stored: | ||
5071 | |||
5072 | - ".debug": Debug symbol files are placed next to the binary in a | ||
5073 | ``.debug`` directory on the target. For example, if a binary is | ||
5074 | installed into ``/bin``, the corresponding debug symbol files are | ||
5075 | installed in ``/bin/.debug``. Source files are placed in | ||
5076 | ``/usr/src/debug``. | ||
5077 | |||
5078 | - "debug-file-directory": Debug symbol files are placed under | ||
5079 | ``/usr/lib/debug`` on the target, and separated by the path from | ||
5080 | where the binary is installed. For example, if a binary is | ||
5081 | installed in ``/bin``, the corresponding debug symbols are | ||
5082 | installed in ``/usr/lib/debug/bin``. Source files are placed in | ||
5083 | ``/usr/src/debug``. | ||
5084 | |||
5085 | - "debug-without-src": The same behavior as ".debug" previously | ||
5086 | described with the exception that no source files are installed. | ||
5087 | |||
5088 | - "debug-with-srcpkg": The same behavior as ".debug" previously | ||
5089 | described with the exception that all source files are placed in a | ||
5090 | separate ``*-src`` pkg. This is the default behavior. | ||
5091 | |||
5092 | You can find out more about debugging using GDB by reading the | ||
5093 | ":ref:`platdev-gdb-remotedebug`" section | ||
5094 | in the Yocto Project Development Tasks Manual. | ||
5095 | |||
5096 | PACKAGE_EXCLUDE_COMPLEMENTARY | ||
5097 | Prevents specific packages from being installed when you are | ||
5098 | installing complementary packages. | ||
5099 | |||
5100 | You might find that you want to prevent installing certain packages | ||
5101 | when you are installing complementary packages. For example, if you | ||
5102 | are using :term:`IMAGE_FEATURES` to install | ||
5103 | ``dev-pkgs``, you might not want to install all packages from a | ||
5104 | particular multilib. If you find yourself in this situation, you can | ||
5105 | use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular | ||
5106 | expressions to match the packages you want to exclude. | ||
5107 | |||
5108 | PACKAGE_EXCLUDE | ||
5109 | Lists packages that should not be installed into an image. For | ||
5110 | example: | ||
5111 | :: | ||
5112 | |||
5113 | PACKAGE_EXCLUDE = "package_name package_name package_name ..." | ||
5114 | |||
5115 | You can set this variable globally in your ``local.conf`` file or you | ||
5116 | can attach it to a specific image recipe by using the recipe name | ||
5117 | override: | ||
5118 | :: | ||
5119 | |||
5120 | PACKAGE_EXCLUDE_pn-target_image = "package_name" | ||
5121 | |||
5122 | If you choose to not install a package using this variable and some | ||
5123 | other package is dependent on it (i.e. listed in a recipe's | ||
5124 | :term:`RDEPENDS` variable), the OpenEmbedded build | ||
5125 | system generates a fatal installation error. Because the build system | ||
5126 | halts the process with a fatal error, you can use the variable with | ||
5127 | an iterative development process to remove specific components from a | ||
5128 | system. | ||
5129 | |||
5130 | Support for this variable exists only when using the IPK and RPM | ||
5131 | packaging backend. Support does not exist for DEB. | ||
5132 | |||
5133 | See the :term:`NO_RECOMMENDATIONS` and the | ||
5134 | :term:`BAD_RECOMMENDATIONS` variables for | ||
5135 | related information. | ||
5136 | |||
5137 | PACKAGE_EXTRA_ARCHS | ||
5138 | Specifies the list of architectures compatible with the device CPU. | ||
5139 | This variable is useful when you build for several different devices | ||
5140 | that use miscellaneous processors such as XScale and ARM926-EJS. | ||
5141 | |||
5142 | PACKAGE_FEED_ARCHS | ||
5143 | Optionally specifies the package architectures used as part of the | ||
5144 | package feed URIs during the build. When used, the | ||
5145 | ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed | ||
5146 | URI, which is constructed using the | ||
5147 | :term:`PACKAGE_FEED_URIS` and | ||
5148 | :term:`PACKAGE_FEED_BASE_PATHS` | ||
5149 | variables. | ||
5150 | |||
5151 | .. note:: | ||
5152 | |||
5153 | You can use the | ||
5154 | PACKAGE_FEEDS_ARCHS | ||
5155 | variable to whitelist specific package architectures. If you do | ||
5156 | not need to whitelist specific architectures, which is a common | ||
5157 | case, you can omit this variable. Omitting the variable results in | ||
5158 | all available architectures for the current machine being included | ||
5159 | into remote package feeds. | ||
5160 | |||
5161 | Consider the following example where the ``PACKAGE_FEED_URIS``, | ||
5162 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | ||
5163 | defined in your ``local.conf`` file: | ||
5164 | :: | ||
5165 | |||
5166 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | ||
5167 | https://example.com/packagerepos/updates" | ||
5168 | PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" | ||
5169 | PACKAGE_FEED_ARCHS = "all core2-64" | ||
5170 | |||
5171 | Given these settings, the resulting package feeds are as follows: | ||
5172 | :: | ||
5173 | |||
5174 | https://example.com/packagerepos/release/rpm/all | ||
5175 | https://example.com/packagerepos/release/rpm/core2-64 | ||
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 | |||
5183 | PACKAGE_FEED_BASE_PATHS | ||
5184 | Specifies the base path used when constructing package feed URIs. The | ||
5185 | ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a | ||
5186 | package feed URI used by the OpenEmbedded build system. The base path | ||
5187 | lies between the :term:`PACKAGE_FEED_URIS` | ||
5188 | and :term:`PACKAGE_FEED_ARCHS` variables. | ||
5189 | |||
5190 | Consider the following example where the ``PACKAGE_FEED_URIS``, | ||
5191 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | ||
5192 | defined in your ``local.conf`` file: | ||
5193 | :: | ||
5194 | |||
5195 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | ||
5196 | https://example.com/packagerepos/updates" | ||
5197 | PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" | ||
5198 | PACKAGE_FEED_ARCHS = "all core2-64" | ||
5199 | |||
5200 | Given these settings, the resulting package feeds are as follows: | ||
5201 | :: | ||
5202 | |||
5203 | https://example.com/packagerepos/release/rpm/all | ||
5204 | https://example.com/packagerepos/release/rpm/core2-64 | ||
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 | |||
5212 | PACKAGE_FEED_URIS | ||
5213 | Specifies the front portion of the package feed URI used by the | ||
5214 | OpenEmbedded build system. Each final package feed URI is comprised | ||
5215 | of ``PACKAGE_FEED_URIS``, | ||
5216 | :term:`PACKAGE_FEED_BASE_PATHS`, and | ||
5217 | :term:`PACKAGE_FEED_ARCHS` variables. | ||
5218 | |||
5219 | Consider the following example where the ``PACKAGE_FEED_URIS``, | ||
5220 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | ||
5221 | defined in your ``local.conf`` file: | ||
5222 | :: | ||
5223 | |||
5224 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | ||
5225 | https://example.com/packagerepos/updates" | ||
5226 | PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" | ||
5227 | PACKAGE_FEED_ARCHS = "all core2-64" | ||
5228 | |||
5229 | Given these settings, the resulting package feeds are as follows: | ||
5230 | :: | ||
5231 | |||
5232 | https://example.com/packagerepos/release/rpm/all | ||
5233 | https://example.com/packagerepos/release/rpm/core2-64 | ||
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 | |||
5241 | PACKAGE_INSTALL | ||
5242 | The final list of packages passed to the package manager for | ||
5243 | installation into the image. | ||
5244 | |||
5245 | Because the package manager controls actual installation of all | ||
5246 | packages, the list of packages passed using ``PACKAGE_INSTALL`` is | ||
5247 | not the final list of packages that are actually installed. This | ||
5248 | variable is internal to the image construction code. Consequently, in | ||
5249 | general, you should use the | ||
5250 | :term:`IMAGE_INSTALL` variable to specify | ||
5251 | packages for installation. The exception to this is when working with | ||
5252 | the | ||
5253 | ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ | ||
5254 | image. When working with an initial RAM filesystem (initramfs) image, | ||
5255 | use the ``PACKAGE_INSTALL`` variable. For information on creating an | ||
5256 | initramfs, see the ":ref:`building-an-initramfs-image`" section | ||
5257 | in the Yocto Project Development Tasks Manual. | ||
5258 | |||
5259 | PACKAGE_INSTALL_ATTEMPTONLY | ||
5260 | Specifies a list of packages the OpenEmbedded build system attempts | ||
5261 | to install when creating an image. If a listed package fails to | ||
5262 | install, the build system does not generate an error. This variable | ||
5263 | is generally not user-defined. | ||
5264 | |||
5265 | PACKAGE_PREPROCESS_FUNCS | ||
5266 | Specifies a list of functions run to pre-process the | ||
5267 | :term:`PKGD` directory prior to splitting the files out | ||
5268 | to individual packages. | ||
5269 | |||
5270 | PACKAGE_WRITE_DEPS | ||
5271 | Specifies a list of dependencies for post-installation and | ||
5272 | pre-installation scripts on native/cross tools. If your | ||
5273 | post-installation or pre-installation script can execute at rootfs | ||
5274 | creation time rather than on the target but depends on a native tool | ||
5275 | in order to execute, you need to list the tools in | ||
5276 | ``PACKAGE_WRITE_DEPS``. | ||
5277 | |||
5278 | For information on running post-installation scripts, see the | ||
5279 | ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`" | ||
5280 | section in the Yocto Project Development Tasks Manual. | ||
5281 | |||
5282 | PACKAGECONFIG | ||
5283 | This variable provides a means of enabling or disabling features of a | ||
5284 | recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in | ||
5285 | recipes when you specify features and then arguments that define | ||
5286 | feature behaviors. Here is the basic block structure (broken over | ||
5287 | multiple lines for readability): | ||
5288 | :: | ||
5289 | |||
5290 | PACKAGECONFIG ??= "f1 f2 f3 ..." | ||
5291 | PACKAGECONFIG[f1] = "\ | ||
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 | |||
5301 | The ``PACKAGECONFIG`` variable itself specifies a space-separated | ||
5302 | list of the features to enable. Following the features, you can | ||
5303 | determine the behavior of each feature by providing up to six | ||
5304 | order-dependent arguments, which are separated by commas. You can | ||
5305 | omit any argument you like but must retain the separating commas. The | ||
5306 | order is important and specifies the following: | ||
5307 | |||
5308 | 1. Extra arguments that should be added to the configure script | ||
5309 | argument list (:term:`EXTRA_OECONF` or | ||
5310 | :term:`PACKAGECONFIG_CONFARGS`) if | ||
5311 | the feature is enabled. | ||
5312 | |||
5313 | 2. Extra arguments that should be added to ``EXTRA_OECONF`` or | ||
5314 | ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. | ||
5315 | |||
5316 | 3. Additional build dependencies (:term:`DEPENDS`) | ||
5317 | that should be added if the feature is enabled. | ||
5318 | |||
5319 | 4. Additional runtime dependencies (:term:`RDEPENDS`) | ||
5320 | that should be added if the feature is enabled. | ||
5321 | |||
5322 | 5. Additional runtime recommendations | ||
5323 | (:term:`RRECOMMENDS`) that should be added if | ||
5324 | the feature is enabled. | ||
5325 | |||
5326 | 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` | ||
5327 | settings for this feature. | ||
5328 | |||
5329 | Consider the following ``PACKAGECONFIG`` block taken from the | ||
5330 | ``librsvg`` recipe. In this example the feature is ``gtk``, which has | ||
5331 | three arguments that determine the feature's behavior. | ||
5332 | :: | ||
5333 | |||
5334 | PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" | ||
5335 | |||
5336 | The | ||
5337 | ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is | ||
5338 | enabled. In this case, ``--with-gtk3`` is added to the configure | ||
5339 | script argument list and ``gtk+3`` is added to ``DEPENDS``. On the | ||
5340 | other hand, if the feature is disabled say through a ``.bbappend`` | ||
5341 | file in another layer, then the second argument ``--without-gtk3`` is | ||
5342 | added to the configure script instead. | ||
5343 | |||
5344 | The basic ``PACKAGECONFIG`` structure previously described holds true | ||
5345 | regardless of whether you are creating a block or changing a block. | ||
5346 | When creating a block, use the structure inside your recipe. | ||
5347 | |||
5348 | If you want to change an existing ``PACKAGECONFIG`` block, you can do | ||
5349 | so one of two ways: | ||
5350 | |||
5351 | - *Append file:* Create an append file named | ||
5352 | recipename\ ``.bbappend`` in your layer and override the value of | ||
5353 | ``PACKAGECONFIG``. You can either completely override the | ||
5354 | variable: | ||
5355 | :: | ||
5356 | |||
5357 | PACKAGECONFIG = "f4 f5" | ||
5358 | |||
5359 | Or, you can just append the variable: | ||
5360 | :: | ||
5361 | |||
5362 | PACKAGECONFIG_append = " f4" | ||
5363 | |||
5364 | - *Configuration file:* This method is identical to changing the | ||
5365 | block through an append file except you edit your ``local.conf`` | ||
5366 | or ``mydistro.conf`` file. As with append files previously | ||
5367 | described, you can either completely override the variable: | ||
5368 | PACKAGECONFIG_pn-recipename = "f4 f5" Or, you can just amend the | ||
5369 | variable: | ||
5370 | :: | ||
5371 | |||
5372 | PACKAGECONFIG_append_pn-recipename = " f4" | ||
5373 | |||
5374 | PACKAGECONFIG_CONFARGS | ||
5375 | A space-separated list of configuration options generated from the | ||
5376 | :term:`PACKAGECONFIG` setting. | ||
5377 | |||
5378 | Classes such as :ref:`autotools <ref-classes-autotools>` and | ||
5379 | :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to | ||
5380 | pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``, | ||
5381 | respectively. If you are using ``PACKAGECONFIG`` but not a class that | ||
5382 | handles the ``do_configure`` task, then you need to use | ||
5383 | ``PACKAGECONFIG_CONFARGS`` appropriately. | ||
5384 | |||
5385 | PACKAGEGROUP_DISABLE_COMPLEMENTARY | ||
5386 | For recipes inheriting the | ||
5387 | :ref:`packagegroup <ref-classes-packagegroup>` class, setting | ||
5388 | ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the | ||
5389 | normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) | ||
5390 | should not be automatically created by the ``packagegroup`` recipe, | ||
5391 | which is the default behavior. | ||
5392 | |||
5393 | PACKAGES | ||
5394 | The list of packages the recipe creates. The default value is the | ||
5395 | following: | ||
5396 | :: | ||
5397 | |||
5398 | ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} | ||
5399 | |||
5400 | During packaging, the :ref:`ref-tasks-package` task | ||
5401 | goes through ``PACKAGES`` and uses the :term:`FILES` | ||
5402 | variable corresponding to each package to assign files to the | ||
5403 | package. If a file matches the ``FILES`` variable for more than one | ||
5404 | package in ``PACKAGES``, it will be assigned to the earliest | ||
5405 | (leftmost) package. | ||
5406 | |||
5407 | Packages in the variable's list that are empty (i.e. where none of | ||
5408 | the patterns in ``FILES_``\ pkg match any files installed by the | ||
5409 | :ref:`ref-tasks-install` task) are not generated, | ||
5410 | unless generation is forced through the | ||
5411 | :term:`ALLOW_EMPTY` variable. | ||
5412 | |||
5413 | PACKAGES_DYNAMIC | ||
5414 | A promise that your recipe satisfies runtime dependencies for | ||
5415 | optional modules that are found in other recipes. | ||
5416 | ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it | ||
5417 | only states that they should be satisfied. For example, if a hard, | ||
5418 | runtime dependency (:term:`RDEPENDS`) of another | ||
5419 | package is satisfied at build time through the ``PACKAGES_DYNAMIC`` | ||
5420 | variable, but a package with the module name is never actually | ||
5421 | produced, then the other package will be broken. Thus, if you attempt | ||
5422 | to include that package in an image, you will get a dependency | ||
5423 | failure from the packaging system during the | ||
5424 | :ref:`ref-tasks-rootfs` task. | ||
5425 | |||
5426 | Typically, if there is a chance that such a situation can occur and | ||
5427 | the package that is not created is valid without the dependency being | ||
5428 | satisfied, then you should use :term:`RRECOMMENDS` | ||
5429 | (a soft runtime dependency) instead of ``RDEPENDS``. | ||
5430 | |||
5431 | For an example of how to use the ``PACKAGES_DYNAMIC`` variable when | ||
5432 | you are splitting packages, see the | ||
5433 | ":ref:`dev-manual/dev-manual-common-tasks:handling optional module packaging`" | ||
5434 | section in the Yocto Project Development Tasks Manual. | ||
5435 | |||
5436 | PACKAGESPLITFUNCS | ||
5437 | Specifies a list of functions run to perform additional splitting of | ||
5438 | files into individual packages. Recipes can either prepend to this | ||
5439 | variable or prepend to the ``populate_packages`` function in order to | ||
5440 | perform additional package splitting. In either case, the function | ||
5441 | should set :term:`PACKAGES`, | ||
5442 | :term:`FILES`, :term:`RDEPENDS` and | ||
5443 | other packaging variables appropriately in order to perform the | ||
5444 | desired splitting. | ||
5445 | |||
5446 | PARALLEL_MAKE | ||
5447 | Extra options passed to the ``make`` command during the | ||
5448 | :ref:`ref-tasks-compile` task in order to specify | ||
5449 | parallel compilation on the local build host. This variable is | ||
5450 | usually in the form "-j x", where x represents the maximum number of | ||
5451 | parallel threads ``make`` can run. | ||
5452 | |||
5453 | .. note:: | ||
5454 | |||
5455 | In order for | ||
5456 | PARALLEL_MAKE | ||
5457 | to be effective, | ||
5458 | make | ||
5459 | must be called with | ||
5460 | ${ | ||
5461 | EXTRA_OEMAKE | ||
5462 | } | ||
5463 | . An easy way to ensure this is to use the | ||
5464 | oe_runmake | ||
5465 | function. | ||
5466 | |||
5467 | By default, the OpenEmbedded build system automatically sets this | ||
5468 | variable to be equal to the number of cores the build system uses. | ||
5469 | |||
5470 | .. note:: | ||
5471 | |||
5472 | If the software being built experiences dependency issues during | ||
5473 | the | ||
5474 | do_compile | ||
5475 | task that result in race conditions, you can clear the | ||
5476 | PARALLEL_MAKE | ||
5477 | variable within the recipe as a workaround. For information on | ||
5478 | addressing race conditions, see the " | ||
5479 | Debugging Parallel Make Races | ||
5480 | " section in the Yocto Project Development Tasks Manual. | ||
5481 | |||
5482 | For single socket systems (i.e. one CPU), you should not have to | ||
5483 | override this variable to gain optimal parallelism during builds. | ||
5484 | However, if you have very large systems that employ multiple physical | ||
5485 | CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is | ||
5486 | not set higher than "-j 20". | ||
5487 | |||
5488 | For more information on speeding up builds, see the | ||
5489 | ":ref:`dev-manual/dev-manual-common-tasks:speeding up a build`" | ||
5490 | section in the Yocto Project Development Tasks Manual. | ||
5491 | |||
5492 | PARALLEL_MAKEINST | ||
5493 | Extra options passed to the ``make install`` command during the | ||
5494 | :ref:`ref-tasks-install` task in order to specify | ||
5495 | parallel installation. This variable defaults to the value of | ||
5496 | :term:`PARALLEL_MAKE`. | ||
5497 | |||
5498 | .. note:: | ||
5499 | |||
5500 | In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must | ||
5501 | be called with | ||
5502 | ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy | ||
5503 | way to ensure this is to use the ``oe_runmake`` function. | ||
5504 | |||
5505 | If the software being built experiences dependency issues during | ||
5506 | the ``do_install`` task that result in race conditions, you can | ||
5507 | clear the ``PARALLEL_MAKEINST`` variable within the recipe as a | ||
5508 | workaround. For information on addressing race conditions, see the | ||
5509 | ":ref:`dev-manual/dev-manual-common-tasks:debugging parallel make races`" | ||
5510 | section in the Yocto Project Development Tasks Manual. | ||
5511 | |||
5512 | PATCHRESOLVE | ||
5513 | Determines the action to take when a patch fails. You can set this | ||
5514 | variable to one of two values: "noop" and "user". | ||
5515 | |||
5516 | The default value of "noop" causes the build to simply fail when the | ||
5517 | OpenEmbedded build system cannot successfully apply a patch. Setting | ||
5518 | the value to "user" causes the build system to launch a shell and | ||
5519 | places you in the right location so that you can manually resolve the | ||
5520 | conflicts. | ||
5521 | |||
5522 | Set this variable in your ``local.conf`` file. | ||
5523 | |||
5524 | PATCHTOOL | ||
5525 | Specifies the utility used to apply patches for a recipe during the | ||
5526 | :ref:`ref-tasks-patch` task. You can specify one of | ||
5527 | three utilities: "patch", "quilt", or "git". The default utility used | ||
5528 | is "quilt" except for the quilt-native recipe itself. Because the | ||
5529 | quilt tool is not available at the time quilt-native is being | ||
5530 | patched, it uses "patch". | ||
5531 | |||
5532 | If you wish to use an alternative patching tool, set the variable in | ||
5533 | the recipe using one of the following: | ||
5534 | :: | ||
5535 | |||
5536 | PATCHTOOL = "patch" | ||
5537 | PATCHTOOL = "quilt" | ||
5538 | PATCHTOOL = "git" | ||
5539 | |||
5540 | PE | ||
5541 | The epoch of the recipe. By default, this variable is unset. The | ||
5542 | variable is used to make upgrades possible when the versioning scheme | ||
5543 | changes in some backwards incompatible way. | ||
5544 | |||
5545 | ``PE`` is the default value of the :term:`PKGE` variable. | ||
5546 | |||
5547 | PF | ||
5548 | Specifies the recipe or package name and includes all version and | ||
5549 | revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and | ||
5550 | ``bash-4.2-r1/``). This variable is comprised of the following: | ||
5551 | ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} | ||
5552 | |||
5553 | PIXBUF_PACKAGES | ||
5554 | When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>` | ||
5555 | class, this variable identifies packages that contain the pixbuf | ||
5556 | loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache`` | ||
5557 | class assumes that the loaders are in the recipe's main package (i.e. | ||
5558 | ``${``\ :term:`PN`\ ``}``). Use this variable if the | ||
5559 | loaders you need are in a package other than that main package. | ||
5560 | |||
5561 | PKG | ||
5562 | The name of the resulting package created by the OpenEmbedded build | ||
5563 | system. | ||
5564 | |||
5565 | .. note:: | ||
5566 | |||
5567 | When using the | ||
5568 | PKG | ||
5569 | variable, you must use a package name override. | ||
5570 | |||
5571 | For example, when the :ref:`debian <ref-classes-debian>` class | ||
5572 | renames the output package, it does so by setting | ||
5573 | ``PKG_packagename``. | ||
5574 | |||
5575 | PKG_CONFIG_PATH | ||
5576 | The path to ``pkg-config`` files for the current build context. | ||
5577 | ``pkg-config`` reads this variable from the environment. | ||
5578 | |||
5579 | PKGD | ||
5580 | Points to the destination directory for files to be packaged before | ||
5581 | they are split into individual packages. This directory defaults to | ||
5582 | the following: | ||
5583 | :: | ||
5584 | |||
5585 | ${WORKDIR}/package | ||
5586 | |||
5587 | Do not change this default. | ||
5588 | |||
5589 | PKGDATA_DIR | ||
5590 | Points to a shared, global-state directory that holds data generated | ||
5591 | during the packaging process. During the packaging process, the | ||
5592 | :ref:`ref-tasks-packagedata` task packages data | ||
5593 | for each recipe and installs it into this temporary, shared area. | ||
5594 | This directory defaults to the following, which you should not | ||
5595 | change: | ||
5596 | :: | ||
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`" | ||
5602 | section in the Yocto Project Overview and Concepts Manual and the | ||
5603 | ":ref:`dev-manual/dev-manual-common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``" | ||
5604 | section in the Yocto Project Development Tasks Manual. For more | ||
5605 | information on the shared, global-state directory, see | ||
5606 | :term:`STAGING_DIR_HOST`. | ||
5607 | |||
5608 | PKGDEST | ||
5609 | Points to the parent directory for files to be packaged after they | ||
5610 | have been split into individual packages. This directory defaults to | ||
5611 | the following: | ||
5612 | :: | ||
5613 | |||
5614 | ${WORKDIR}/packages-split | ||
5615 | |||
5616 | Under this directory, the build system creates directories for each | ||
5617 | package specified in :term:`PACKAGES`. Do not change | ||
5618 | this default. | ||
5619 | |||
5620 | PKGDESTWORK | ||
5621 | Points to a temporary work area where the | ||
5622 | :ref:`ref-tasks-package` task saves package metadata. | ||
5623 | The ``PKGDESTWORK`` location defaults to the following: | ||
5624 | :: | ||
5625 | |||
5626 | ${WORKDIR}/pkgdata | ||
5627 | |||
5628 | Do not change this default. | ||
5629 | |||
5630 | The :ref:`ref-tasks-packagedata` task copies the | ||
5631 | package metadata from ``PKGDESTWORK`` to | ||
5632 | :term:`PKGDATA_DIR` to make it available globally. | ||
5633 | |||
5634 | PKGE | ||
5635 | The epoch of the package(s) built by the recipe. By default, ``PKGE`` | ||
5636 | is set to :term:`PE`. | ||
5637 | |||
5638 | PKGR | ||
5639 | The revision of the package(s) built by the recipe. By default, | ||
5640 | ``PKGR`` is set to :term:`PR`. | ||
5641 | |||
5642 | PKGV | ||
5643 | The version of the package(s) built by the recipe. By default, | ||
5644 | ``PKGV`` is set to :term:`PV`. | ||
5645 | |||
5646 | PN | ||
5647 | This variable can have two separate functions depending on the | ||
5648 | context: a recipe name or a resulting package name. | ||
5649 | |||
5650 | ``PN`` refers to a recipe name in the context of a file used by the | ||
5651 | OpenEmbedded build system as input to create a package. The name is | ||
5652 | normally extracted from the recipe file name. For example, if the | ||
5653 | recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` | ||
5654 | will be "expat". | ||
5655 | |||
5656 | The variable refers to a package name in the context of a file | ||
5657 | created or produced by the OpenEmbedded build system. | ||
5658 | |||
5659 | If applicable, the ``PN`` variable also contains any special suffix | ||
5660 | or prefix. For example, using ``bash`` to build packages for the | ||
5661 | native machine, ``PN`` is ``bash-native``. Using ``bash`` to build | ||
5662 | packages for the target and for Multilib, ``PN`` would be ``bash`` | ||
5663 | and ``lib64-bash``, respectively. | ||
5664 | |||
5665 | PNBLACKLIST | ||
5666 | Lists recipes you do not want the OpenEmbedded build system to build. | ||
5667 | This variable works in conjunction with the | ||
5668 | :ref:`blacklist <ref-classes-blacklist>` class, which is inherited | ||
5669 | globally. | ||
5670 | |||
5671 | To prevent a recipe from being built, use the ``PNBLACKLIST`` | ||
5672 | variable in your ``local.conf`` file. Here is an example that | ||
5673 | prevents ``myrecipe`` from being built: | ||
5674 | :: | ||
5675 | |||
5676 | PNBLACKLIST[myrecipe] = "Not supported by our organization." | ||
5677 | |||
5678 | POPULATE_SDK_POST_HOST_COMMAND | ||
5679 | Specifies a list of functions to call once the OpenEmbedded build | ||
5680 | system has created the host part of the SDK. You can specify | ||
5681 | functions separated by semicolons: | ||
5682 | :: | ||
5683 | |||
5684 | POPULATE_SDK_POST_HOST_COMMAND += "function; ... " | ||
5685 | |||
5686 | If you need to pass the SDK path to a command within a function, you | ||
5687 | can use ``${SDK_DIR}``, which points to the parent directory used by | ||
5688 | the OpenEmbedded build system when creating SDK output. See the | ||
5689 | :term:`SDK_DIR` variable for more information. | ||
5690 | |||
5691 | POPULATE_SDK_POST_TARGET_COMMAND | ||
5692 | Specifies a list of functions to call once the OpenEmbedded build | ||
5693 | system has created the target part of the SDK. You can specify | ||
5694 | functions separated by semicolons: | ||
5695 | :: | ||
5696 | |||
5697 | POPULATE_SDK_POST_TARGET_COMMAND += "function; ... " | ||
5698 | |||
5699 | If you need to pass the SDK path to a command within a function, you | ||
5700 | can use ``${SDK_DIR}``, which points to the parent directory used by | ||
5701 | the OpenEmbedded build system when creating SDK output. See the | ||
5702 | :term:`SDK_DIR` variable for more information. | ||
5703 | |||
5704 | PR | ||
5705 | The revision of the recipe. The default value for this variable is | ||
5706 | "r0". Subsequent revisions of the recipe conventionally have the | ||
5707 | values "r1", "r2", and so forth. When :term:`PV` increases, | ||
5708 | ``PR`` is conventionally reset to "r0". | ||
5709 | |||
5710 | .. note:: | ||
5711 | |||
5712 | The OpenEmbedded build system does not need the aid of | ||
5713 | PR | ||
5714 | to know when to rebuild a recipe. The build system uses the task | ||
5715 | input checksums | ||
5716 | along with the | ||
5717 | stamp | ||
5718 | and | ||
5719 | shared state cache | ||
5720 | mechanisms. | ||
5721 | |||
5722 | The ``PR`` variable primarily becomes significant when a package | ||
5723 | manager dynamically installs packages on an already built image. In | ||
5724 | this case, ``PR``, which is the default value of | ||
5725 | :term:`PKGR`, helps the package manager distinguish which | ||
5726 | package is the most recent one in cases where many packages have the | ||
5727 | same ``PV`` (i.e. ``PKGV``). A component having many packages with | ||
5728 | the same ``PV`` usually means that the packages all install the same | ||
5729 | upstream version, but with later (``PR``) version packages including | ||
5730 | packaging fixes. | ||
5731 | |||
5732 | .. note:: | ||
5733 | |||
5734 | PR | ||
5735 | does not need to be increased for changes that do not change the | ||
5736 | package contents or metadata. | ||
5737 | |||
5738 | Because manually managing ``PR`` can be cumbersome and error-prone, | ||
5739 | an automated solution exists. See the | ||
5740 | ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`" section | ||
5741 | in the Yocto Project Development Tasks Manual for more information. | ||
5742 | |||
5743 | PREFERRED_PROVIDER | ||
5744 | If multiple recipes provide the same item, this variable determines | ||
5745 | which recipe is preferred and thus provides the item (i.e. the | ||
5746 | preferred provider). You should always suffix this variable with the | ||
5747 | name of the provided item. And, you should define the variable using | ||
5748 | the preferred recipe's name (:term:`PN`). Here is a common | ||
5749 | example: | ||
5750 | :: | ||
5751 | |||
5752 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | ||
5753 | |||
5754 | In the previous example, multiple recipes are providing "virtual/kernel". | ||
5755 | The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of | ||
5756 | the recipe you prefer to provide "virtual/kernel". | ||
5757 | |||
5758 | Following are more examples: | ||
5759 | :: | ||
5760 | |||
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`" | ||
5766 | section in the Yocto Project Development Tasks Manual. | ||
5767 | |||
5768 | .. note:: | ||
5769 | |||
5770 | If you use a | ||
5771 | virtual/\* | ||
5772 | item with | ||
5773 | PREFERRED_PROVIDER | ||
5774 | , then any recipe that | ||
5775 | PROVIDES | ||
5776 | that item but is not selected (defined) by | ||
5777 | PREFERRED_PROVIDER | ||
5778 | is prevented from building, which is usually desirable since this | ||
5779 | mechanism is designed to select between mutually exclusive | ||
5780 | alternative providers. | ||
5781 | |||
5782 | PREFERRED_VERSION | ||
5783 | If multiple versions of recipes exist, this variable determines which | ||
5784 | version is given preference. You must always suffix the variable with | ||
5785 | the :term:`PN` you want to select, and you should set the | ||
5786 | :term:`PV` accordingly for precedence. | ||
5787 | |||
5788 | The ``PREFERRED_VERSION`` variable supports limited wildcard use | ||
5789 | through the "``%``" character. You can use the character to match any | ||
5790 | number of characters, which can be useful when specifying versions | ||
5791 | that contain long revision numbers that potentially change. Here are | ||
5792 | two examples: | ||
5793 | :: | ||
5794 | |||
5795 | PREFERRED_VERSION_python = "3.4.0" | ||
5796 | PREFERRED_VERSION_linux-yocto = "5.0%" | ||
5797 | |||
5798 | .. note:: | ||
5799 | |||
5800 | The use of the "%" character is limited in that it only works at the end of the | ||
5801 | string. You cannot use the wildcard character in any other | ||
5802 | location of the string. | ||
5803 | |||
5804 | The specified version is matched against :term:`PV`, which | ||
5805 | does not necessarily match the version part of the recipe's filename. | ||
5806 | For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` | ||
5807 | where ``foo_git.bb`` contains the following assignment: | ||
5808 | :: | ||
5809 | |||
5810 | PV = "1.1+git${SRCPV}" | ||
5811 | |||
5812 | In this case, the correct way to select | ||
5813 | ``foo_git.bb`` is by using an assignment such as the following: | ||
5814 | :: | ||
5815 | |||
5816 | PREFERRED_VERSION_foo = "1.1+git%" | ||
5817 | |||
5818 | Compare that previous example | ||
5819 | against the following incorrect example, which does not work: | ||
5820 | :: | ||
5821 | |||
5822 | PREFERRED_VERSION_foo = "git" | ||
5823 | |||
5824 | Sometimes the ``PREFERRED_VERSION`` variable can be set by | ||
5825 | configuration files in a way that is hard to change. You can use | ||
5826 | :term:`OVERRIDES` to set a machine-specific | ||
5827 | override. Here is an example: | ||
5828 | :: | ||
5829 | |||
5830 | PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%" | ||
5831 | |||
5832 | Although not recommended, worst case, you can also use the | ||
5833 | "forcevariable" override, which is the strongest override possible. | ||
5834 | Here is an example: | ||
5835 | :: | ||
5836 | |||
5837 | PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%" | ||
5838 | |||
5839 | .. note:: | ||
5840 | |||
5841 | The \_forcevariable override is not handled specially. This override | ||
5842 | only works because the default value of OVERRIDES includes "forcevariable". | ||
5843 | |||
5844 | PREMIRRORS | ||
5845 | Specifies additional paths from which the OpenEmbedded build system | ||
5846 | gets source code. When the build system searches for source code, it | ||
5847 | first tries the local download directory. If that location fails, the | ||
5848 | build system tries locations defined by ``PREMIRRORS``, the upstream | ||
5849 | source, and then locations specified by | ||
5850 | :term:`MIRRORS` in that order. | ||
5851 | |||
5852 | Assuming your distribution (:term:`DISTRO`) is "poky", | ||
5853 | the default value for ``PREMIRRORS`` is defined in the | ||
5854 | ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. | ||
5855 | |||
5856 | Typically, you could add a specific server for the build system to | ||
5857 | attempt before any others by adding something like the following to | ||
5858 | the ``local.conf`` configuration file in the | ||
5859 | :term:`Build Directory`: | ||
5860 | :: | ||
5861 | |||
5862 | PREMIRRORS_prepend = "\ | ||
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 | ||
5869 | build system to intercept Git, FTP, HTTP, and HTTPS requests and | ||
5870 | direct them to the ``http://`` sources mirror. You can use | ||
5871 | ``file://`` URLs to point to local directories or network shares as | ||
5872 | well. | ||
5873 | |||
5874 | PRIORITY | ||
5875 | Indicates the importance of a package. | ||
5876 | |||
5877 | ``PRIORITY`` is considered to be part of the distribution policy | ||
5878 | because the importance of any given recipe depends on the purpose for | ||
5879 | which the distribution is being produced. Thus, ``PRIORITY`` is not | ||
5880 | normally set within recipes. | ||
5881 | |||
5882 | You can set ``PRIORITY`` to "required", "standard", "extra", and | ||
5883 | "optional", which is the default. | ||
5884 | |||
5885 | PRIVATE_LIBS | ||
5886 | Specifies libraries installed within a recipe that should be ignored | ||
5887 | by the OpenEmbedded build system's shared library resolver. This | ||
5888 | variable is typically used when software being built by a recipe has | ||
5889 | its own private versions of a library normally provided by another | ||
5890 | recipe. In this case, you would not want the package containing the | ||
5891 | private libraries to be set as a dependency on other unrelated | ||
5892 | packages that should instead depend on the package providing the | ||
5893 | standard version of the library. | ||
5894 | |||
5895 | Libraries specified in this variable should be specified by their | ||
5896 | file name. For example, from the Firefox recipe in meta-browser: | ||
5897 | :: | ||
5898 | |||
5899 | PRIVATE_LIBS = "libmozjs.so \ | ||
5900 | libxpcom.so \ | ||
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`" | ||
5909 | section in the Yocto Project Overview and Concepts Manual. | ||
5910 | |||
5911 | PROVIDES | ||
5912 | A list of aliases by which a particular recipe can be known. By | ||
5913 | default, a recipe's own ``PN`` is implicitly already in its | ||
5914 | ``PROVIDES`` list and therefore does not need to mention that it | ||
5915 | provides itself. If a recipe uses ``PROVIDES``, the additional | ||
5916 | aliases are synonyms for the recipe and can be useful for satisfying | ||
5917 | dependencies of other recipes during the build as specified by | ||
5918 | ``DEPENDS``. | ||
5919 | |||
5920 | Consider the following example ``PROVIDES`` statement from the recipe | ||
5921 | file ``eudev_3.2.9.bb``: | ||
5922 | :: | ||
5923 | |||
5924 | PROVIDES = "udev" | ||
5925 | |||
5926 | The ``PROVIDES`` statement | ||
5927 | results in the "eudev" recipe also being available as simply "udev". | ||
5928 | |||
5929 | .. note:: | ||
5930 | |||
5931 | Given that a recipe's own recipe name is already implicitly in its | ||
5932 | own | ||
5933 | PROVIDES | ||
5934 | list, it is unnecessary to add aliases with the "+=" operator; | ||
5935 | using a simple assignment will be sufficient. In other words, | ||
5936 | while you could write: | ||
5937 | :: | ||
5938 | |||
5939 | PROVIDES += "udev" | ||
5940 | |||
5941 | |||
5942 | in the above, the "+=" is overkill and unnecessary. | ||
5943 | |||
5944 | In addition to providing recipes under alternate names, the | ||
5945 | ``PROVIDES`` mechanism is also used to implement virtual targets. A | ||
5946 | virtual target is a name that corresponds to some particular | ||
5947 | functionality (e.g. a Linux kernel). Recipes that provide the | ||
5948 | functionality in question list the virtual target in ``PROVIDES``. | ||
5949 | Recipes that depend on the functionality in question can include the | ||
5950 | virtual target in ``DEPENDS`` to leave the choice of provider open. | ||
5951 | |||
5952 | Conventionally, virtual targets have names on the form | ||
5953 | "virtual/function" (e.g. "virtual/kernel"). The slash is simply part | ||
5954 | of the name and has no syntactical significance. | ||
5955 | |||
5956 | The :term:`PREFERRED_PROVIDER` variable is | ||
5957 | used to select which particular recipe provides a virtual target. | ||
5958 | |||
5959 | .. note:: | ||
5960 | |||
5961 | A corresponding mechanism for virtual runtime dependencies | ||
5962 | (packages) exists. However, the mechanism does not depend on any | ||
5963 | special functionality beyond ordinary variable assignments. For | ||
5964 | example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of | ||
5965 | the component that manages the ``/dev`` directory. | ||
5966 | |||
5967 | Setting the "preferred provider" for runtime dependencies is as | ||
5968 | simple as using the following assignment in a configuration file: | ||
5969 | :: | ||
5970 | |||
5971 | VIRTUAL-RUNTIME_dev_manager = "udev" | ||
5972 | |||
5973 | |||
5974 | PRSERV_HOST | ||
5975 | The network based :term:`PR` service host and port. | ||
5976 | |||
5977 | The ``conf/local.conf.sample.extended`` configuration file in the | ||
5978 | :term:`Source Directory` shows how the | ||
5979 | ``PRSERV_HOST`` variable is set: | ||
5980 | :: | ||
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 | ||
5987 | set ``PRSERV_HOST`` to other values to use a remote PR service. | ||
5988 | |||
5989 | PTEST_ENABLED | ||
5990 | Specifies whether or not :ref:`Package | ||
5991 | Test <dev-manual/dev-manual-common-tasks:testing packages with ptest>` (ptest) | ||
5992 | functionality is enabled when building a recipe. You should not set | ||
5993 | this variable directly. Enabling and disabling building Package Tests | ||
5994 | at build time should be done by adding "ptest" to (or removing it | ||
5995 | from) :term:`DISTRO_FEATURES`. | ||
5996 | |||
5997 | PV | ||
5998 | The version of the recipe. The version is normally extracted from the | ||
5999 | recipe filename. For example, if the recipe is named | ||
6000 | ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1". | ||
6001 | ``PV`` is generally not overridden within a recipe unless it is | ||
6002 | building an unstable (i.e. development) version from a source code | ||
6003 | repository (e.g. Git or Subversion). | ||
6004 | |||
6005 | ``PV`` is the default value of the :term:`PKGV` variable. | ||
6006 | |||
6007 | PYTHON_ABI | ||
6008 | When used by recipes that inherit the | ||
6009 | :ref:`distutils3 <ref-classes-distutils3>`, | ||
6010 | :ref:`setuptools3 <ref-classes-setuptools3>`, | ||
6011 | :ref:`distutils <ref-classes-distutils>`, or | ||
6012 | :ref:`setuptools <ref-classes-setuptools>` classes, denotes the | ||
6013 | Application Binary Interface (ABI) currently in use for Python. By | ||
6014 | default, the ABI is "m". You do not have to set this variable as the | ||
6015 | OpenEmbedded build system sets it for you. | ||
6016 | |||
6017 | The OpenEmbedded build system uses the ABI to construct directory | ||
6018 | names used when installing the Python headers and libraries in | ||
6019 | sysroot (e.g. ``.../python3.3m/...``). | ||
6020 | |||
6021 | Recipes that inherit the ``distutils`` class during cross-builds also | ||
6022 | use this variable to locate the headers and libraries of the | ||
6023 | appropriate Python that the extension is targeting. | ||
6024 | |||
6025 | PYTHON_PN | ||
6026 | When used by recipes that inherit the | ||
6027 | `distutils3 <ref-classes-distutils3>`, | ||
6028 | :ref:`setuptools3 <ref-classes-setuptools3>`, | ||
6029 | :ref:`distutils <ref-classes-distutils>`, or | ||
6030 | :ref:`setuptools <ref-classes-setuptools>` classes, specifies the | ||
6031 | major Python version being built. For Python 3.x, ``PYTHON_PN`` would | ||
6032 | be "python3". You do not have to set this variable as the | ||
6033 | OpenEmbedded build system automatically sets it for you. | ||
6034 | |||
6035 | The variable allows recipes to use common infrastructure such as the | ||
6036 | following: | ||
6037 | :: | ||
6038 | |||
6039 | DEPENDS += "${PYTHON_PN}-native" | ||
6040 | |||
6041 | In the previous example, | ||
6042 | the version of the dependency is ``PYTHON_PN``. | ||
6043 | |||
6044 | RANLIB | ||
6045 | The minimal command and arguments to run ``ranlib``. | ||
6046 | |||
6047 | RCONFLICTS | ||
6048 | The list of packages that conflict with packages. Note that packages | ||
6049 | will not be installed if conflicting packages are not first removed. | ||
6050 | |||
6051 | Like all package-controlling variables, you must always use them in | ||
6052 | conjunction with a package name override. Here is an example: | ||
6053 | :: | ||
6054 | |||
6055 | RCONFLICTS_${PN} = "another_conflicting_package_name" | ||
6056 | |||
6057 | BitBake, which the OpenEmbedded build system uses, supports | ||
6058 | specifying versioned dependencies. Although the syntax varies | ||
6059 | depending on the packaging format, BitBake hides these differences | ||
6060 | from you. Here is the general syntax to specify versions with the | ||
6061 | ``RCONFLICTS`` variable: | ||
6062 | :: | ||
6063 | |||
6064 | RCONFLICTS_${PN} = "package (operator version)" | ||
6065 | |||
6066 | For ``operator``, you can specify the following: = < > <= | ||
6067 | >= For example, the following sets up a dependency on version 1.2 or | ||
6068 | greater of the package ``foo``: | ||
6069 | :: | ||
6070 | |||
6071 | RCONFLICTS_${PN} = "foo (>= 1.2)" | ||
6072 | |||
6073 | RDEPENDS | ||
6074 | Lists runtime dependencies of a package. These dependencies are other | ||
6075 | packages that must be installed in order for the package to function | ||
6076 | correctly. As an example, the following assignment declares that the | ||
6077 | package ``foo`` needs the packages ``bar`` and ``baz`` to be | ||
6078 | installed: | ||
6079 | :: | ||
6080 | |||
6081 | RDEPENDS_foo = "bar baz" | ||
6082 | |||
6083 | The most common types of package | ||
6084 | runtime dependencies are automatically detected and added. Therefore, | ||
6085 | most recipes do not need to set ``RDEPENDS``. For more information, | ||
6086 | see the | ||
6087 | ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`" | ||
6088 | section in the Yocto Project Overview and Concepts Manual. | ||
6089 | |||
6090 | The practical effect of the above ``RDEPENDS`` assignment is that | ||
6091 | ``bar`` and ``baz`` will be declared as dependencies inside the | ||
6092 | package ``foo`` when it is written out by one of the | ||
6093 | ```do_package_write_*`` <#ref-tasks-package_write_deb>`__ tasks. | ||
6094 | Exactly how this is done depends on which package format is used, | ||
6095 | which is determined by | ||
6096 | :term:`PACKAGE_CLASSES`. When the | ||
6097 | corresponding package manager installs the package, it will know to | ||
6098 | also install the packages on which it depends. | ||
6099 | |||
6100 | To ensure that the packages ``bar`` and ``baz`` get built, the | ||
6101 | previous ``RDEPENDS`` assignment also causes a task dependency to be | ||
6102 | added. This dependency is from the recipe's | ||
6103 | :ref:`ref-tasks-build` (not to be confused with | ||
6104 | :ref:`ref-tasks-compile`) task to the | ||
6105 | ``do_package_write_*`` task of the recipes that build ``bar`` and | ||
6106 | ``baz``. | ||
6107 | |||
6108 | The names of the packages you list within ``RDEPENDS`` must be the | ||
6109 | names of other packages - they cannot be recipe names. Although | ||
6110 | package names and recipe names usually match, the important point | ||
6111 | here is that you are providing package names within the ``RDEPENDS`` | ||
6112 | variable. For an example of the default list of packages created from | ||
6113 | a recipe, see the :term:`PACKAGES` variable. | ||
6114 | |||
6115 | Because the ``RDEPENDS`` variable applies to packages being built, | ||
6116 | you should always use the variable in a form with an attached package | ||
6117 | name (remember that a single recipe can build multiple packages). For | ||
6118 | example, suppose you are building a development package that depends | ||
6119 | on the ``perl`` package. In this case, you would use the following | ||
6120 | ``RDEPENDS`` statement: | ||
6121 | :: | ||
6122 | |||
6123 | RDEPENDS_${PN}-dev += "perl" | ||
6124 | |||
6125 | In the example, | ||
6126 | the development package depends on the ``perl`` package. Thus, the | ||
6127 | ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of | ||
6128 | the variable. | ||
6129 | |||
6130 | .. note:: | ||
6131 | |||
6132 | RDEPENDS_${PN}-dev | ||
6133 | includes | ||
6134 | ${ | ||
6135 | PN | ||
6136 | } | ||
6137 | by default. This default is set in the BitBake configuration file | ||
6138 | ( | ||
6139 | meta/conf/bitbake.conf | ||
6140 | ). Be careful not to accidentally remove | ||
6141 | ${PN} | ||
6142 | when modifying | ||
6143 | RDEPENDS_${PN}-dev | ||
6144 | . Use the "+=" operator rather than the "=" operator. | ||
6145 | |||
6146 | The package names you use with ``RDEPENDS`` must appear as they would | ||
6147 | in the ``PACKAGES`` variable. The :term:`PKG` variable | ||
6148 | allows a different name to be used for the final package (e.g. the | ||
6149 | :ref:`debian <ref-classes-debian>` class uses this to rename | ||
6150 | packages), but this final package name cannot be used with | ||
6151 | ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be | ||
6152 | independent of the package format used. | ||
6153 | |||
6154 | BitBake, which the OpenEmbedded build system uses, supports | ||
6155 | specifying versioned dependencies. Although the syntax varies | ||
6156 | depending on the packaging format, BitBake hides these differences | ||
6157 | from you. Here is the general syntax to specify versions with the | ||
6158 | ``RDEPENDS`` variable: | ||
6159 | :: | ||
6160 | |||
6161 | RDEPENDS_${PN} = "package (operator version)" | ||
6162 | |||
6163 | For operator, you can specify the following: = < > <= >= For version, | ||
6164 | provide the version number. | ||
6165 | |||
6166 | .. note:: | ||
6167 | |||
6168 | You can use | ||
6169 | EXTENDPKGV | ||
6170 | to provide a full package version specification. | ||
6171 | |||
6172 | For example, the following sets up a dependency on version 1.2 or | ||
6173 | greater of the package ``foo``: | ||
6174 | :: | ||
6175 | |||
6176 | RDEPENDS_${PN} = "foo (>= 1.2)" | ||
6177 | |||
6178 | For information on build-time dependencies, see the | ||
6179 | :term:`DEPENDS` variable. You can also see the | ||
6180 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | ||
6181 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | ||
6182 | BitBake User Manual for additional information on tasks and | ||
6183 | dependencies. | ||
6184 | |||
6185 | REQUIRED_DISTRO_FEATURES | ||
6186 | When inheriting the | ||
6187 | :ref:`distro_features_check <ref-classes-distro_features_check>` | ||
6188 | class, this variable identifies distribution features that must exist | ||
6189 | in the current configuration in order for the OpenEmbedded build | ||
6190 | system to build the recipe. In other words, if the | ||
6191 | ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not | ||
6192 | appear in ``DISTRO_FEATURES`` within the current configuration, an | ||
6193 | error occurs and the build stops. | ||
6194 | |||
6195 | RM_WORK_EXCLUDE | ||
6196 | With ``rm_work`` enabled, this variable specifies a list of recipes | ||
6197 | whose work directories should not be removed. See the | ||
6198 | ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more | ||
6199 | details. | ||
6200 | |||
6201 | ROOT_HOME | ||
6202 | Defines the root home directory. By default, this directory is set as | ||
6203 | follows in the BitBake configuration file: | ||
6204 | :: | ||
6205 | |||
6206 | ROOT_HOME ??= "/home/root" | ||
6207 | |||
6208 | .. note:: | ||
6209 | |||
6210 | This default value is likely used because some embedded solutions | ||
6211 | prefer to have a read-only root filesystem and prefer to keep | ||
6212 | writeable data in one place. | ||
6213 | |||
6214 | You can override the default by setting the variable in any layer or | ||
6215 | in the ``local.conf`` file. Because the default is set using a "weak" | ||
6216 | assignment (i.e. "??="), you can use either of the following forms to | ||
6217 | define your override: | ||
6218 | :: | ||
6219 | |||
6220 | ROOT_HOME = "/root" | ||
6221 | ROOT_HOME ?= "/root" | ||
6222 | |||
6223 | These | ||
6224 | override examples use ``/root``, which is probably the most commonly | ||
6225 | used override. | ||
6226 | |||
6227 | ROOTFS | ||
6228 | Indicates a filesystem image to include as the root filesystem. | ||
6229 | |||
6230 | The ``ROOTFS`` variable is an optional variable used with the | ||
6231 | :ref:`image-live <ref-classes-image-live>` class. | ||
6232 | |||
6233 | ROOTFS_POSTINSTALL_COMMAND | ||
6234 | Specifies a list of functions to call after the OpenEmbedded build | ||
6235 | system has installed packages. You can specify functions separated by | ||
6236 | semicolons: | ||
6237 | :: | ||
6238 | |||
6239 | ROOTFS_POSTINSTALL_COMMAND += "function; ... " | ||
6240 | |||
6241 | If you need to pass the root filesystem path to a command within a | ||
6242 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6243 | directory that becomes the root filesystem image. See the | ||
6244 | :term:`IMAGE_ROOTFS` variable for more | ||
6245 | information. | ||
6246 | |||
6247 | ROOTFS_POSTPROCESS_COMMAND | ||
6248 | Specifies a list of functions to call once the OpenEmbedded build | ||
6249 | system has created the root filesystem. You can specify functions | ||
6250 | separated by semicolons: | ||
6251 | :: | ||
6252 | |||
6253 | ROOTFS_POSTPROCESS_COMMAND += "function; ... " | ||
6254 | |||
6255 | If you need to pass the root filesystem path to a command within a | ||
6256 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6257 | directory that becomes the root filesystem image. See the | ||
6258 | :term:`IMAGE_ROOTFS` variable for more | ||
6259 | information. | ||
6260 | |||
6261 | ROOTFS_POSTUNINSTALL_COMMAND | ||
6262 | Specifies a list of functions to call after the OpenEmbedded build | ||
6263 | system has removed unnecessary packages. When runtime package | ||
6264 | management is disabled in the image, several packages are removed | ||
6265 | including ``base-passwd``, ``shadow``, and ``update-alternatives``. | ||
6266 | You can specify functions separated by semicolons: | ||
6267 | :: | ||
6268 | |||
6269 | ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " | ||
6270 | |||
6271 | If you need to pass the root filesystem path to a command within a | ||
6272 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6273 | directory that becomes the root filesystem image. See the | ||
6274 | :term:`IMAGE_ROOTFS` variable for more | ||
6275 | information. | ||
6276 | |||
6277 | ROOTFS_PREPROCESS_COMMAND | ||
6278 | Specifies a list of functions to call before the OpenEmbedded build | ||
6279 | system has created the root filesystem. You can specify functions | ||
6280 | separated by semicolons: | ||
6281 | :: | ||
6282 | |||
6283 | ROOTFS_PREPROCESS_COMMAND += "function; ... " | ||
6284 | |||
6285 | If you need to pass the root filesystem path to a command within a | ||
6286 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6287 | directory that becomes the root filesystem image. See the | ||
6288 | :term:`IMAGE_ROOTFS` variable for more | ||
6289 | information. | ||
6290 | |||
6291 | RPROVIDES | ||
6292 | A list of package name aliases that a package also provides. These | ||
6293 | aliases are useful for satisfying runtime dependencies of other | ||
6294 | packages both during the build and on the target (as specified by | ||
6295 | ``RDEPENDS``). | ||
6296 | |||
6297 | .. note:: | ||
6298 | |||
6299 | A package's own name is implicitly already in its | ||
6300 | RPROVIDES | ||
6301 | list. | ||
6302 | |||
6303 | As with all package-controlling variables, you must always use the | ||
6304 | variable in conjunction with a package name override. Here is an | ||
6305 | example: | ||
6306 | :: | ||
6307 | |||
6308 | RPROVIDES_${PN} = "widget-abi-2" | ||
6309 | |||
6310 | RRECOMMENDS | ||
6311 | A list of packages that extends the usability of a package being | ||
6312 | built. The package being built does not depend on this list of | ||
6313 | packages in order to successfully build, but rather uses them for | ||
6314 | extended usability. To specify runtime dependencies for packages, see | ||
6315 | the ``RDEPENDS`` variable. | ||
6316 | |||
6317 | The package manager will automatically install the ``RRECOMMENDS`` | ||
6318 | list of packages when installing the built package. However, you can | ||
6319 | prevent listed packages from being installed by using the | ||
6320 | :term:`BAD_RECOMMENDATIONS`, | ||
6321 | :term:`NO_RECOMMENDATIONS`, and | ||
6322 | :term:`PACKAGE_EXCLUDE` variables. | ||
6323 | |||
6324 | Packages specified in ``RRECOMMENDS`` need not actually be produced. | ||
6325 | However, a recipe must exist that provides each package, either | ||
6326 | through the :term:`PACKAGES` or | ||
6327 | :term:`PACKAGES_DYNAMIC` variables or the | ||
6328 | :term:`RPROVIDES` variable, or an error will occur | ||
6329 | during the build. If such a recipe does exist and the package is not | ||
6330 | produced, the build continues without error. | ||
6331 | |||
6332 | Because the ``RRECOMMENDS`` variable applies to packages being built, | ||
6333 | you should always attach an override to the variable to specify the | ||
6334 | particular package whose usability is being extended. For example, | ||
6335 | suppose you are building a development package that is extended to | ||
6336 | support wireless functionality. In this case, you would use the | ||
6337 | following: | ||
6338 | :: | ||
6339 | |||
6340 | RRECOMMENDS_${PN}-dev += "wireless_package_name" | ||
6341 | |||
6342 | In the | ||
6343 | example, the package name (``${PN}-dev``) must appear as it would in | ||
6344 | the ``PACKAGES`` namespace before any renaming of the output package | ||
6345 | by classes such as ``debian.bbclass``. | ||
6346 | |||
6347 | BitBake, which the OpenEmbedded build system uses, supports | ||
6348 | specifying versioned recommends. Although the syntax varies depending | ||
6349 | on the packaging format, BitBake hides these differences from you. | ||
6350 | Here is the general syntax to specify versions with the | ||
6351 | ``RRECOMMENDS`` variable: | ||
6352 | :: | ||
6353 | |||
6354 | RRECOMMENDS_${PN} = "package (operator version)" | ||
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 | |||
6370 | RREPLACES | ||
6371 | A list of packages replaced by a package. The package manager uses | ||
6372 | this variable to determine which package should be installed to | ||
6373 | replace other package(s) during an upgrade. In order to also have the | ||
6374 | other package(s) removed at the same time, you must add the name of | ||
6375 | the other package to the ``RCONFLICTS`` variable. | ||
6376 | |||
6377 | As with all package-controlling variables, you must use this variable | ||
6378 | in conjunction with a package name override. Here is an example: | ||
6379 | :: | ||
6380 | |||
6381 | RREPLACES_${PN} = "other_package_being_replaced" | ||
6382 | |||
6383 | BitBake, which the OpenEmbedded build system uses, supports | ||
6384 | specifying versioned replacements. Although the syntax varies | ||
6385 | depending on the packaging format, BitBake hides these differences | ||
6386 | from you. Here is the general syntax to specify versions with the | ||
6387 | ``RREPLACES`` variable: | ||
6388 | :: | ||
6389 | |||
6390 | RREPLACES_${PN} = "package (operator version)" | ||
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 | |||
6406 | RSUGGESTS | ||
6407 | A list of additional packages that you can suggest for installation | ||
6408 | by the package manager at the time a package is installed. Not all | ||
6409 | package managers support this functionality. | ||
6410 | |||
6411 | As with all package-controlling variables, you must always use this | ||
6412 | variable in conjunction with a package name override. Here is an | ||
6413 | example: | ||
6414 | :: | ||
6415 | |||
6416 | RSUGGESTS_${PN} = "useful_package another_package" | ||
6417 | |||
6418 | S | ||
6419 | The location in the :term:`Build Directory` where | ||
6420 | unpacked recipe source code resides. By default, this directory is | ||
6421 | ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, | ||
6422 | where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe | ||
6423 | version. If the source tarball extracts the code to a directory named | ||
6424 | anything other than ``${BPN}-${PV}``, or if the source code is | ||
6425 | fetched from an SCM such as Git or Subversion, then you must set | ||
6426 | ``S`` in the recipe so that the OpenEmbedded build system knows where | ||
6427 | to find the unpacked source. | ||
6428 | |||
6429 | As an example, assume a :term:`Source Directory` | ||
6430 | top-level folder named ``poky`` and a default Build Directory at | ||
6431 | ``poky/build``. In this case, the work directory the build system | ||
6432 | uses to keep the unpacked recipe for ``db`` is the following: | ||
6433 | :: | ||
6434 | |||
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 | |||
6439 | This next example assumes a Git repository. By default, Git | ||
6440 | repositories are cloned to ``${WORKDIR}/git`` during | ||
6441 | :ref:`ref-tasks-fetch`. Since this path is different | ||
6442 | from the default value of ``S``, you must set it specifically so the | ||
6443 | source can be located: | ||
6444 | :: | ||
6445 | |||
6446 | SRC_URI = "git://path/to/repo.git" | ||
6447 | S = "${WORKDIR}/git" | ||
6448 | |||
6449 | SANITY_REQUIRED_UTILITIES | ||
6450 | Specifies a list of command-line utilities that should be checked for | ||
6451 | during the initial sanity checking process when running BitBake. If | ||
6452 | any of the utilities are not installed on the build host, then | ||
6453 | BitBake immediately exits with an error. | ||
6454 | |||
6455 | SANITY_TESTED_DISTROS | ||
6456 | A list of the host distribution identifiers that the build system has | ||
6457 | been tested against. Identifiers consist of the host distributor ID | ||
6458 | followed by the release, as reported by the ``lsb_release`` tool or | ||
6459 | as read from ``/etc/lsb-release``. Separate the list items with | ||
6460 | explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is | ||
6461 | not empty and the current value of | ||
6462 | :term:`NATIVELSBSTRING` does not appear in the | ||
6463 | list, then the build system reports a warning that indicates the | ||
6464 | current host distribution has not been tested as a build host. | ||
6465 | |||
6466 | SDK_ARCH | ||
6467 | The target architecture for the SDK. Typically, you do not directly | ||
6468 | set this variable. Instead, use :term:`SDKMACHINE`. | ||
6469 | |||
6470 | SDK_DEPLOY | ||
6471 | The directory set up and used by the | ||
6472 | :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which | ||
6473 | the SDK is deployed. The ``populate_sdk_base`` class defines | ||
6474 | ``SDK_DEPLOY`` as follows: | ||
6475 | :: | ||
6476 | |||
6477 | SDK_DEPLOY = "${TMPDIR}/deploy/sdk" | ||
6478 | |||
6479 | SDK_DIR | ||
6480 | The parent directory used by the OpenEmbedded build system when | ||
6481 | creating SDK output. The | ||
6482 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines | ||
6483 | the variable as follows: | ||
6484 | :: | ||
6485 | |||
6486 | SDK_DIR = "${WORKDIR}/sdk" | ||
6487 | |||
6488 | .. note:: | ||
6489 | |||
6490 | The | ||
6491 | SDK_DIR | ||
6492 | directory is a temporary directory as it is part of | ||
6493 | WORKDIR | ||
6494 | . The final output directory is | ||
6495 | SDK_DEPLOY | ||
6496 | . | ||
6497 | |||
6498 | SDK_EXT_TYPE | ||
6499 | Controls whether or not shared state artifacts are copied into the | ||
6500 | extensible SDK. The default value of "full" copies all of the | ||
6501 | required shared state artifacts into the extensible SDK. The value | ||
6502 | "minimal" leaves these artifacts out of the SDK. | ||
6503 | |||
6504 | .. note:: | ||
6505 | |||
6506 | If you set the variable to "minimal", you need to ensure | ||
6507 | SSTATE_MIRRORS | ||
6508 | is set in the SDK's configuration to enable the artifacts to be | ||
6509 | fetched as needed. | ||
6510 | |||
6511 | SDK_HOST_MANIFEST | ||
6512 | The manifest file for the host part of the SDK. This file lists all | ||
6513 | the installed packages that make up the host part of the SDK. The | ||
6514 | file contains package information on a line-per-package basis as | ||
6515 | follows: | ||
6516 | :: | ||
6517 | |||
6518 | packagename packagearch version | ||
6519 | |||
6520 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | ||
6521 | defines the manifest file as follows: | ||
6522 | :: | ||
6523 | |||
6524 | SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" | ||
6525 | |||
6526 | The location is derived using the :term:`SDK_DEPLOY` and | ||
6527 | :term:`TOOLCHAIN_OUTPUTNAME` variables. | ||
6528 | |||
6529 | SDK_INCLUDE_PKGDATA | ||
6530 | When set to "1", specifies to include the packagedata for all recipes | ||
6531 | in the "world" target in the extensible SDK. Including this data | ||
6532 | allows the ``devtool search`` command to find these recipes in search | ||
6533 | results, as well as allows the ``devtool add`` command to map | ||
6534 | dependencies more effectively. | ||
6535 | |||
6536 | .. note:: | ||
6537 | |||
6538 | Enabling the | ||
6539 | SDK_INCLUDE_PKGDATA | ||
6540 | variable significantly increases build time because all of world | ||
6541 | needs to be built. Enabling the variable also slightly increases | ||
6542 | the size of the extensible SDK. | ||
6543 | |||
6544 | SDK_INCLUDE_TOOLCHAIN | ||
6545 | When set to "1", specifies to include the toolchain in the extensible | ||
6546 | SDK. Including the toolchain is useful particularly when | ||
6547 | :term:`SDK_EXT_TYPE` is set to "minimal" to keep | ||
6548 | the SDK reasonably small but you still want to provide a usable | ||
6549 | toolchain. For example, suppose you want to use the toolchain from an | ||
6550 | IDE or from other tools and you do not want to perform additional | ||
6551 | steps to install the toolchain. | ||
6552 | |||
6553 | The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if | ||
6554 | ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if | ||
6555 | ``SDK_EXT_TYPE`` is set to "full". | ||
6556 | |||
6557 | SDK_INHERIT_BLACKLIST | ||
6558 | A list of classes to remove from the :term:`INHERIT` | ||
6559 | value globally within the extensible SDK configuration. The | ||
6560 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the | ||
6561 | default value: | ||
6562 | :: | ||
6563 | |||
6564 | SDK_INHERIT_BLACKLIST ?= "buildhistory icecc" | ||
6565 | |||
6566 | Some classes are not generally applicable within the extensible SDK | ||
6567 | context. You can use this variable to disable those classes. | ||
6568 | |||
6569 | For additional information on how to customize the extensible SDK's | ||
6570 | configuration, see the | ||
6571 | ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`" | ||
6572 | section in the Yocto Project Application Development and the | ||
6573 | Extensible Software Development Kit (eSDK) manual. | ||
6574 | |||
6575 | SDK_LOCAL_CONF_BLACKLIST | ||
6576 | A list of variables not allowed through from the OpenEmbedded build | ||
6577 | system configuration into the extensible SDK configuration. Usually, | ||
6578 | these are variables that are specific to the machine on which the | ||
6579 | build system is running and thus would be potentially problematic | ||
6580 | within the extensible SDK. | ||
6581 | |||
6582 | By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the | ||
6583 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and | ||
6584 | excludes the following variables: | ||
6585 | |||
6586 | - :term:`CONF_VERSION` | ||
6587 | - :term:`BB_NUMBER_THREADS` | ||
6588 | - :term:`bitbake:BB_NUMBER_PARSE_THREADS` | ||
6589 | - :term:`PARALLEL_MAKE` | ||
6590 | - :term:`PRSERV_HOST` | ||
6591 | - :term:`SSTATE_MIRRORS` :term:`DL_DIR` | ||
6592 | - :term:`SSTATE_DIR` :term:`TMPDIR` | ||
6593 | - :term:`BB_SERVER_TIMEOUT` | ||
6594 | |||
6595 | For additional information on how to customize the extensible SDK's | ||
6596 | configuration, see the | ||
6597 | ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`" | ||
6598 | section in the Yocto Project Application Development and the | ||
6599 | Extensible Software Development Kit (eSDK) manual. | ||
6600 | |||
6601 | SDK_LOCAL_CONF_WHITELIST | ||
6602 | A list of variables allowed through from the OpenEmbedded build | ||
6603 | system configuration into the extensible SDK configuration. By | ||
6604 | default, the list of variables is empty and is set in the | ||
6605 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. | ||
6606 | |||
6607 | This list overrides the variables specified using the | ||
6608 | :term:`SDK_LOCAL_CONF_BLACKLIST` | ||
6609 | variable as well as any variables identified by automatic | ||
6610 | blacklisting due to the "/" character being found at the start of the | ||
6611 | value, which is usually indicative of being a path and thus might not | ||
6612 | be valid on the system where the SDK is installed. | ||
6613 | |||
6614 | For additional information on how to customize the extensible SDK's | ||
6615 | configuration, see the | ||
6616 | ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`" | ||
6617 | section in the Yocto Project Application Development and the | ||
6618 | Extensible Software Development Kit (eSDK) manual. | ||
6619 | |||
6620 | SDK_NAME | ||
6621 | The base name for SDK output files. The name is derived from the | ||
6622 | :term:`DISTRO`, :term:`TCLIBC`, | ||
6623 | :term:`SDK_ARCH`, | ||
6624 | :term:`IMAGE_BASENAME`, and | ||
6625 | :term:`TUNE_PKGARCH` variables: | ||
6626 | :: | ||
6627 | |||
6628 | SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" | ||
6629 | |||
6630 | SDK_OS | ||
6631 | Specifies the operating system for which the SDK will be built. The | ||
6632 | default value is the value of :term:`BUILD_OS`. | ||
6633 | |||
6634 | SDK_OUTPUT | ||
6635 | The location used by the OpenEmbedded build system when creating SDK | ||
6636 | output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` | ||
6637 | class defines the variable as follows: | ||
6638 | :: | ||
6639 | |||
6640 | SDK_DIR = "${WORKDIR}/sdk" | ||
6641 | SDK_OUTPUT = "${SDK_DIR}/image" | ||
6642 | SDK_DEPLOY = "${DEPLOY_DIR}/sdk" | ||
6643 | |||
6644 | .. note:: | ||
6645 | |||
6646 | The SDK_OUTPUT directory is a temporary directory as it is part of | ||
6647 | WORKDIR by way of SDK_DIR. The final output directory is | ||
6648 | SDK_DEPLOY. | ||
6649 | |||
6650 | SDK_PACKAGE_ARCHS | ||
6651 | Specifies a list of architectures compatible with the SDK machine. | ||
6652 | This variable is set automatically and should not normally be | ||
6653 | hand-edited. Entries are separated using spaces and listed in order | ||
6654 | of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any | ||
6655 | noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". | ||
6656 | |||
6657 | SDK_POSTPROCESS_COMMAND | ||
6658 | Specifies a list of functions to call once the OpenEmbedded build | ||
6659 | system creates the SDK. You can specify functions separated by | ||
6660 | semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " | ||
6661 | |||
6662 | If you need to pass an SDK path to a command within a function, you | ||
6663 | can use ``${SDK_DIR}``, which points to the parent directory used by | ||
6664 | the OpenEmbedded build system when creating SDK output. See the | ||
6665 | :term:`SDK_DIR` variable for more information. | ||
6666 | |||
6667 | SDK_PREFIX | ||
6668 | The toolchain binary prefix used for ``nativesdk`` recipes. The | ||
6669 | OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the | ||
6670 | :term:`TARGET_PREFIX` when building | ||
6671 | ``nativesdk`` recipes. The default value is "${SDK_SYS}-". | ||
6672 | |||
6673 | SDK_RECRDEP_TASKS | ||
6674 | A list of shared state tasks added to the extensible SDK. By default, | ||
6675 | the following tasks are added: | ||
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 | ||
6683 | ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added | ||
6684 | to the SDK. To specify tasks beyond these four, you need to use the | ||
6685 | ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional | ||
6686 | tasks that are needed in order to build | ||
6687 | :term:`SDK_TARGETS`). | ||
6688 | |||
6689 | SDK_SYS | ||
6690 | Specifies the system, including the architecture and the operating | ||
6691 | system, for which the SDK will be built. | ||
6692 | |||
6693 | The OpenEmbedded build system automatically sets this variable based | ||
6694 | on :term:`SDK_ARCH`, | ||
6695 | :term:`SDK_VENDOR`, and | ||
6696 | :term:`SDK_OS`. You do not need to set the ``SDK_SYS`` | ||
6697 | variable yourself. | ||
6698 | |||
6699 | SDK_TARGET_MANIFEST | ||
6700 | The manifest file for the target part of the SDK. This file lists all | ||
6701 | the installed packages that make up the target part of the SDK. The | ||
6702 | file contains package information on a line-per-package basis as | ||
6703 | follows: | ||
6704 | :: | ||
6705 | |||
6706 | packagename packagearch version | ||
6707 | |||
6708 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | ||
6709 | defines the manifest file as follows: | ||
6710 | :: | ||
6711 | |||
6712 | SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" | ||
6713 | |||
6714 | The location is derived using the :term:`SDK_DEPLOY` and | ||
6715 | :term:`TOOLCHAIN_OUTPUTNAME` variables. | ||
6716 | |||
6717 | SDK_TARGETS | ||
6718 | A list of targets to install from shared state as part of the | ||
6719 | standard or extensible SDK installation. The default value is "${PN}" | ||
6720 | (i.e. the image from which the SDK is built). | ||
6721 | |||
6722 | The ``SDK_TARGETS`` variable is an internal variable and typically | ||
6723 | would not be changed. | ||
6724 | |||
6725 | SDK_TITLE | ||
6726 | The title to be printed when running the SDK installer. By default, | ||
6727 | this title is based on the :term:`DISTRO_NAME` or | ||
6728 | :term:`DISTRO` variable and is set in the | ||
6729 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | ||
6730 | follows: | ||
6731 | :: | ||
6732 | |||
6733 | SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" | ||
6734 | |||
6735 | For the default distribution "poky", | ||
6736 | ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". | ||
6737 | |||
6738 | For information on how to change this default title, see the | ||
6739 | ":ref:`sdk-manual/sdk-appendix-customizing:changing the extensible sdk installer title`" | ||
6740 | section in the Yocto Project Application Development and the | ||
6741 | Extensible Software Development Kit (eSDK) manual. | ||
6742 | |||
6743 | SDK_UPDATE_URL | ||
6744 | An optional URL for an update server for the extensible SDK. If set, | ||
6745 | the value is used as the default update server when running | ||
6746 | ``devtool sdk-update`` within the extensible SDK. | ||
6747 | |||
6748 | SDK_VENDOR | ||
6749 | Specifies the name of the SDK vendor. | ||
6750 | |||
6751 | SDK_VERSION | ||
6752 | Specifies the version of the SDK. The distribution configuration file | ||
6753 | (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the | ||
6754 | ``SDK_VERSION`` as follows: | ||
6755 | :: | ||
6756 | |||
6757 | SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}" | ||
6758 | |||
6759 | For additional information, see the | ||
6760 | :term:`DISTRO_VERSION` and | ||
6761 | :term:`DATE` variables. | ||
6762 | |||
6763 | SDKEXTPATH | ||
6764 | The default installation directory for the Extensible SDK. By | ||
6765 | default, this directory is based on the :term:`DISTRO` | ||
6766 | variable and is set in the | ||
6767 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | ||
6768 | follows: | ||
6769 | :: | ||
6770 | |||
6771 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" | ||
6772 | |||
6773 | For the | ||
6774 | default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". | ||
6775 | |||
6776 | For information on how to change this default directory, see the | ||
6777 | ":ref:`sdk-manual/sdk-appendix-customizing:changing the default sdk installation directory`" | ||
6778 | section in the Yocto Project Application Development and the | ||
6779 | Extensible Software Development Kit (eSDK) manual. | ||
6780 | |||
6781 | SDKIMAGE_FEATURES | ||
6782 | Equivalent to ``IMAGE_FEATURES``. However, this variable applies to | ||
6783 | the SDK generated from an image using the following command: | ||
6784 | :: | ||
6785 | |||
6786 | $ bitbake -c populate_sdk imagename | ||
6787 | |||
6788 | SDKMACHINE | ||
6789 | The machine for which the SDK is built. In other words, the SDK is | ||
6790 | built such that it runs on the target you specify with the | ||
6791 | ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` | ||
6792 | file under ``conf/machine-sdk/``. | ||
6793 | |||
6794 | You can use "i686" and "x86_64" as possible values for this variable. | ||
6795 | The variable defaults to "i686" and is set in the local.conf file in | ||
6796 | the Build Directory. | ||
6797 | :: | ||
6798 | |||
6799 | SDKMACHINE ?= "i686" | ||
6800 | |||
6801 | .. note:: | ||
6802 | |||
6803 | You cannot set the | ||
6804 | SDKMACHINE | ||
6805 | variable in your distribution configuration file. If you do, the | ||
6806 | configuration will not take affect. | ||
6807 | |||
6808 | SDKPATH | ||
6809 | Defines the path offered to the user for installation of the SDK that | ||
6810 | is generated by the OpenEmbedded build system. The path appears as | ||
6811 | the default location for installing the SDK when you run the SDK's | ||
6812 | installation script. You can override the offered path when you run | ||
6813 | the script. | ||
6814 | |||
6815 | SDKTARGETSYSROOT | ||
6816 | The full path to the sysroot used for cross-compilation within an SDK | ||
6817 | as it will be when installed into the default | ||
6818 | :term:`SDKPATH`. | ||
6819 | |||
6820 | SECTION | ||
6821 | The section in which packages should be categorized. Package | ||
6822 | management utilities can make use of this variable. | ||
6823 | |||
6824 | SELECTED_OPTIMIZATION | ||
6825 | Specifies the optimization flags passed to the C compiler when | ||
6826 | building for the target. The flags are passed through the default | ||
6827 | value of the :term:`TARGET_CFLAGS` variable. | ||
6828 | |||
6829 | The ``SELECTED_OPTIMIZATION`` variable takes the value of | ||
6830 | ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the | ||
6831 | case, the value of ``DEBUG_OPTIMIZATION`` is used. | ||
6832 | |||
6833 | SERIAL_CONSOLE | ||
6834 | Defines a serial console (TTY) to enable using | ||
6835 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | ||
6836 | value that specifies the baud rate followed by the TTY device name | ||
6837 | separated by a space. You cannot specify more than one TTY device: | ||
6838 | :: | ||
6839 | |||
6840 | SERIAL_CONSOLE = "115200 ttyS0" | ||
6841 | |||
6842 | .. note:: | ||
6843 | |||
6844 | The | ||
6845 | SERIAL_CONSOLE | ||
6846 | variable is deprecated. Please use the | ||
6847 | SERIAL_CONSOLES | ||
6848 | variable. | ||
6849 | |||
6850 | SERIAL_CONSOLES | ||
6851 | Defines a serial console (TTY) to enable using | ||
6852 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | ||
6853 | value that specifies the baud rate followed by the TTY device name | ||
6854 | separated by a semicolon. Use spaces to separate multiple devices: | ||
6855 | :: | ||
6856 | |||
6857 | SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" | ||
6858 | |||
6859 | SERIAL_CONSOLES_CHECK | ||
6860 | Specifies serial consoles, which must be listed in | ||
6861 | :term:`SERIAL_CONSOLES`, to check against | ||
6862 | ``/proc/console`` before enabling them using getty. This variable | ||
6863 | allows aliasing in the format: <device>:<alias>. If a device was | ||
6864 | listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in | ||
6865 | ``/proc/console``, you would do the following: :: | ||
6866 | |||
6867 | SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" | ||
6868 | |||
6869 | This variable is currently only supported with SysVinit (i.e. not | ||
6870 | with systemd). | ||
6871 | |||
6872 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS | ||
6873 | A list of recipe dependencies that should not be used to determine | ||
6874 | signatures of tasks from one recipe when they depend on tasks from | ||
6875 | another recipe. For example: :: | ||
6876 | |||
6877 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" | ||
6878 | |||
6879 | In the previous example, ``intone`` depends on ``mplayer2``. | ||
6880 | |||
6881 | You can use the special token ``"*"`` on the left-hand side of the | ||
6882 | dependency to match all recipes except the one on the right-hand | ||
6883 | side. Here is an example: :: | ||
6884 | |||
6885 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" | ||
6886 | |||
6887 | In the previous example, all recipes except ``quilt-native`` ignore | ||
6888 | task signatures from the ``quilt-native`` recipe when determining | ||
6889 | their task signatures. | ||
6890 | |||
6891 | Use of this variable is one mechanism to remove dependencies that | ||
6892 | affect task signatures and thus force rebuilds when a recipe changes. | ||
6893 | |||
6894 | .. note:: | ||
6895 | |||
6896 | If you add an inappropriate dependency for a recipe relationship, | ||
6897 | the software might break during runtime if the interface of the | ||
6898 | second recipe was changed after the first recipe had been built. | ||
6899 | |||
6900 | SIGGEN_EXCLUDERECIPES_ABISAFE | ||
6901 | A list of recipes that are completely stable and will never change. | ||
6902 | The ABI for the recipes in the list are presented by output from the | ||
6903 | tasks run to build the recipe. Use of this variable is one way to | ||
6904 | remove dependencies from one recipe on another that affect task | ||
6905 | signatures and thus force rebuilds when the recipe changes. | ||
6906 | |||
6907 | .. note:: | ||
6908 | |||
6909 | If you add an inappropriate variable to this list, the software | ||
6910 | might break at runtime if the interface of the recipe was changed | ||
6911 | after the other had been built. | ||
6912 | |||
6913 | SITEINFO_BITS | ||
6914 | Specifies the number of bits for the target system CPU. The value | ||
6915 | should be either "32" or "64". | ||
6916 | |||
6917 | SITEINFO_ENDIANNESS | ||
6918 | Specifies the endian byte order of the target system. The value | ||
6919 | should be either "le" for little-endian or "be" for big-endian. | ||
6920 | |||
6921 | SKIP_FILEDEPS | ||
6922 | Enables removal of all files from the "Provides" section of an RPM | ||
6923 | package. Removal of these files is required for packages containing | ||
6924 | prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. | ||
6925 | |||
6926 | To enable file removal, set the variable to "1" in your | ||
6927 | ``conf/local.conf`` configuration file in your: | ||
6928 | :term:`Build Directory`. | ||
6929 | :: | ||
6930 | |||
6931 | SKIP_FILEDEPS = "1" | ||
6932 | |||
6933 | SOC_FAMILY | ||
6934 | Groups together machines based upon the same family of SOC (System On | ||
6935 | Chip). You typically set this variable in a common ``.inc`` file that | ||
6936 | you include in the configuration files of all the machines. | ||
6937 | |||
6938 | .. note:: | ||
6939 | |||
6940 | You must include | ||
6941 | conf/machine/include/soc-family.inc | ||
6942 | for this variable to appear in | ||
6943 | MACHINEOVERRIDES | ||
6944 | . | ||
6945 | |||
6946 | SOLIBS | ||
6947 | Defines the suffix for shared libraries used on the target platform. | ||
6948 | By default, this suffix is ".so.*" for all Linux-based systems and is | ||
6949 | defined in the ``meta/conf/bitbake.conf`` configuration file. | ||
6950 | |||
6951 | You will see this variable referenced in the default values of | ||
6952 | ``FILES_${PN}``. | ||
6953 | |||
6954 | SOLIBSDEV | ||
6955 | Defines the suffix for the development symbolic link (symlink) for | ||
6956 | shared libraries on the target platform. By default, this suffix is | ||
6957 | ".so" for Linux-based systems and is defined in the | ||
6958 | ``meta/conf/bitbake.conf`` configuration file. | ||
6959 | |||
6960 | You will see this variable referenced in the default values of | ||
6961 | ``FILES_${PN}-dev``. | ||
6962 | |||
6963 | SOURCE_MIRROR_FETCH | ||
6964 | When you are fetching files to create a mirror of sources (i.e. | ||
6965 | creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in | ||
6966 | your ``local.conf`` configuration file ensures the source for all | ||
6967 | recipes are fetched regardless of whether or not a recipe is | ||
6968 | compatible with the configuration. A recipe is considered | ||
6969 | incompatible with the currently configured machine when either or | ||
6970 | both the :term:`COMPATIBLE_MACHINE` | ||
6971 | variable and :term:`COMPATIBLE_HOST` variables | ||
6972 | specify compatibility with a machine other than that of the current | ||
6973 | machine or host. | ||
6974 | |||
6975 | .. note:: | ||
6976 | |||
6977 | Do not set the | ||
6978 | SOURCE_MIRROR_FETCH | ||
6979 | variable unless you are creating a source mirror. In other words, | ||
6980 | do not set the variable during a normal build. | ||
6981 | |||
6982 | SOURCE_MIRROR_URL | ||
6983 | Defines your own :term:`PREMIRRORS` from which to | ||
6984 | first fetch source before attempting to fetch from the upstream | ||
6985 | specified in :term:`SRC_URI`. | ||
6986 | |||
6987 | To use this variable, you must globally inherit the | ||
6988 | :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide | ||
6989 | the URL to your mirrors. Here is the general syntax: | ||
6990 | :: | ||
6991 | |||
6992 | INHERIT += "own-mirrors" | ||
6993 | SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" | ||
6994 | |||
6995 | .. note:: | ||
6996 | |||
6997 | You can specify only a single URL in | ||
6998 | SOURCE_MIRROR_URL | ||
6999 | . | ||
7000 | |||
7001 | SPDXLICENSEMAP | ||
7002 | Maps commonly used license names to their SPDX counterparts found in | ||
7003 | ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` | ||
7004 | mappings, see the ``meta/conf/licenses.conf`` file. | ||
7005 | |||
7006 | For additional information, see the :term:`LICENSE` | ||
7007 | variable. | ||
7008 | |||
7009 | SPECIAL_PKGSUFFIX | ||
7010 | A list of prefixes for :term:`PN` used by the OpenEmbedded | ||
7011 | build system to create variants of recipes or packages. The list | ||
7012 | specifies the prefixes to strip off during certain circumstances such | ||
7013 | as the generation of the :term:`BPN` variable. | ||
7014 | |||
7015 | SPL_BINARY | ||
7016 | The file type for the Secondary Program Loader (SPL). Some devices | ||
7017 | use an SPL from which to boot (e.g. the BeagleBone development | ||
7018 | board). For such cases, you can declare the file type of the SPL | ||
7019 | binary in the ``u-boot.inc`` include file, which is used in the | ||
7020 | U-Boot recipe. | ||
7021 | |||
7022 | The SPL file type is set to "null" by default in the ``u-boot.inc`` | ||
7023 | file as follows: | ||
7024 | :: | ||
7025 | |||
7026 | # Some versions of u-boot build an SPL (Second Program Loader) image that | ||
7027 | # should be packaged along with the u-boot binary as well as placed in the | ||
7028 | # deploy directory. For those versions they can set the following variables | ||
7029 | # to allow packaging the SPL. | ||
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 | ||
7036 | various ``SPL_*`` variables used by the OpenEmbedded build system. | ||
7037 | |||
7038 | See the BeagleBone machine configuration example in the | ||
7039 | ":ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`" | ||
7040 | section in the Yocto Project Board Support Package Developer's Guide | ||
7041 | for additional information. | ||
7042 | |||
7043 | SRC_URI | ||
7044 | The list of source files - local or remote. This variable tells the | ||
7045 | OpenEmbedded build system which bits to pull in for the build and how | ||
7046 | to pull them in. For example, if the recipe or append file only needs | ||
7047 | to fetch a tarball from the Internet, the recipe or append file uses | ||
7048 | a single ``SRC_URI`` entry. On the other hand, if the recipe or | ||
7049 | append file needs to fetch a tarball, apply two patches, and include | ||
7050 | a custom file, the recipe or append file would include four instances | ||
7051 | of the variable. | ||
7052 | |||
7053 | The following list explains the available URI protocols. URI | ||
7054 | protocols are highly dependent on particular BitBake Fetcher | ||
7055 | submodules. Depending on the fetcher BitBake uses, various URL | ||
7056 | parameters are employed. For specifics on the supported Fetchers, see | ||
7057 | the ":ref:`Fetchers <bitbake:bb-fetchers>`" section in the | ||
7058 | BitBake User Manual. | ||
7059 | |||
7060 | - ``file://`` - Fetches files, which are usually files shipped | ||
7061 | with the :term:`Metadata`, from the local machine (e.g. | ||
7062 | :ref:`patch <patching-dev-environment>` files). | ||
7063 | The path is relative to the :term:`FILESPATH` | ||
7064 | variable. Thus, the build system searches, in order, from the | ||
7065 | following directories, which are assumed to be a subdirectories of | ||
7066 | the directory in which the recipe file (``.bb``) or append file | ||
7067 | (``.bbappend``) resides: | ||
7068 | |||
7069 | - ``${BPN}`` - The base recipe name without any special suffix | ||
7070 | or version numbers. | ||
7071 | |||
7072 | - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and | ||
7073 | version but without any special package name suffix. | ||
7074 | |||
7075 | - *files -* Files within a directory, which is named ``files`` | ||
7076 | and is also alongside the recipe or append file. | ||
7077 | |||
7078 | .. note:: | ||
7079 | |||
7080 | If you want the build system to pick up files specified through | ||
7081 | a | ||
7082 | SRC_URI | ||
7083 | statement from your append file, you need to be sure to extend | ||
7084 | the | ||
7085 | FILESPATH | ||
7086 | variable by also using the | ||
7087 | FILESEXTRAPATHS | ||
7088 | variable from within your append file. | ||
7089 | |||
7090 | - ``bzr://`` - Fetches files from a Bazaar revision control | ||
7091 | repository. | ||
7092 | |||
7093 | - ``git://`` - Fetches files from a Git revision control | ||
7094 | repository. | ||
7095 | |||
7096 | - ``osc://`` - Fetches files from an OSC (OpenSUSE Build service) | ||
7097 | revision control repository. | ||
7098 | |||
7099 | - ``repo://`` - Fetches files from a repo (Git) repository. | ||
7100 | |||
7101 | - ``ccrc://`` - Fetches files from a ClearCase repository. | ||
7102 | |||
7103 | - ``http://`` - Fetches files from the Internet using ``http``. | ||
7104 | |||
7105 | - ``https://`` - Fetches files from the Internet using ``https``. | ||
7106 | |||
7107 | - ``ftp://`` - Fetches files from the Internet using ``ftp``. | ||
7108 | |||
7109 | - ``cvs://`` - Fetches files from a CVS revision control | ||
7110 | repository. | ||
7111 | |||
7112 | - ``hg://`` - Fetches files from a Mercurial (``hg``) revision | ||
7113 | control repository. | ||
7114 | |||
7115 | - ``p4://`` - Fetches files from a Perforce (``p4``) revision | ||
7116 | control repository. | ||
7117 | |||
7118 | - ``ssh://`` - Fetches files from a secure shell. | ||
7119 | |||
7120 | - ``svn://`` - Fetches files from a Subversion (``svn``) revision | ||
7121 | control repository. | ||
7122 | |||
7123 | - ``npm://`` - Fetches JavaScript modules from a registry. | ||
7124 | |||
7125 | Standard and recipe-specific options for ``SRC_URI`` exist. Here are | ||
7126 | standard options: | ||
7127 | |||
7128 | - ``apply`` - Whether to apply the patch or not. The default | ||
7129 | action is to apply the patch. | ||
7130 | |||
7131 | - ``striplevel`` - Which striplevel to use when applying the | ||
7132 | patch. The default level is 1. | ||
7133 | |||
7134 | - ``patchdir`` - Specifies the directory in which the patch should | ||
7135 | be applied. The default is ``${``\ :term:`S`\ ``}``. | ||
7136 | |||
7137 | Here are options specific to recipes building code from a revision | ||
7138 | control system: | ||
7139 | |||
7140 | - ``mindate`` - Apply the patch only if | ||
7141 | :term:`SRCDATE` is equal to or greater than | ||
7142 | ``mindate``. | ||
7143 | |||
7144 | - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later | ||
7145 | than ``maxdate``. | ||
7146 | |||
7147 | - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or | ||
7148 | greater than ``minrev``. | ||
7149 | |||
7150 | - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later | ||
7151 | than ``maxrev``. | ||
7152 | |||
7153 | - ``rev`` - Apply the patch only if ``SRCREV`` is equal to | ||
7154 | ``rev``. | ||
7155 | |||
7156 | - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to | ||
7157 | ``rev``. | ||
7158 | |||
7159 | Here are some additional options worth mentioning: | ||
7160 | |||
7161 | - ``unpack`` - Controls whether or not to unpack the file if it is | ||
7162 | an archive. The default action is to unpack the file. | ||
7163 | |||
7164 | - ``destsuffix`` - Places the file (or extracts its contents) into | ||
7165 | the specified subdirectory of :term:`WORKDIR` when | ||
7166 | the Git fetcher is used. | ||
7167 | |||
7168 | - ``subdir`` - Places the file (or extracts its contents) into the | ||
7169 | specified subdirectory of ``WORKDIR`` when the local (``file://``) | ||
7170 | fetcher is used. | ||
7171 | |||
7172 | - ``localdir`` - Places the file (or extracts its contents) into | ||
7173 | the specified subdirectory of ``WORKDIR`` when the CVS fetcher is | ||
7174 | used. | ||
7175 | |||
7176 | - ``subpath`` - Limits the checkout to a specific subpath of the | ||
7177 | tree when using the Git fetcher is used. | ||
7178 | |||
7179 | - ``name`` - Specifies a name to be used for association with | ||
7180 | ``SRC_URI`` checksums when you have more than one file specified | ||
7181 | in ``SRC_URI``. | ||
7182 | |||
7183 | - ``downloadfilename`` - Specifies the filename used when storing | ||
7184 | the downloaded file. | ||
7185 | |||
7186 | SRC_URI_OVERRIDES_PACKAGE_ARCH | ||
7187 | By default, the OpenEmbedded build system automatically detects | ||
7188 | whether ``SRC_URI`` contains files that are machine-specific. If so, | ||
7189 | the build system automatically changes ``PACKAGE_ARCH``. Setting this | ||
7190 | variable to "0" disables this behavior. | ||
7191 | |||
7192 | SRCDATE | ||
7193 | The date of the source code used to build the package. This variable | ||
7194 | applies only if the source was fetched from a Source Code Manager | ||
7195 | (SCM). | ||
7196 | |||
7197 | SRCPV | ||
7198 | Returns the version string of the current package. This string is | ||
7199 | used to help define the value of :term:`PV`. | ||
7200 | |||
7201 | The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` | ||
7202 | configuration file in the :term:`Source Directory` as | ||
7203 | follows: | ||
7204 | :: | ||
7205 | |||
7206 | SRCPV = "${@bb.fetch2.get_srcrev(d)}" | ||
7207 | |||
7208 | Recipes that need to define ``PV`` do so with the help of the | ||
7209 | ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) | ||
7210 | located in ``meta/recipes-connectivity`` in the Source Directory | ||
7211 | defines ``PV`` as follows: | ||
7212 | :: | ||
7213 | |||
7214 | PV = "0.12-git${SRCPV}" | ||
7215 | |||
7216 | SRCREV | ||
7217 | The revision of the source code used to build the package. This | ||
7218 | variable applies to Subversion, Git, Mercurial, and Bazaar only. Note | ||
7219 | that if you want to build a fixed revision and you want to avoid | ||
7220 | performing a query on the remote repository every time BitBake parses | ||
7221 | your recipe, you should specify a ``SRCREV`` that is a full revision | ||
7222 | identifier and not just a tag. | ||
7223 | |||
7224 | .. note:: | ||
7225 | |||
7226 | For information on limitations when inheriting the latest revision | ||
7227 | of software using | ||
7228 | SRCREV | ||
7229 | , see the | ||
7230 | AUTOREV | ||
7231 | variable description and the " | ||
7232 | Automatically Incrementing a Binary Package Revision Number | ||
7233 | " section, which is in the Yocto Project Development Tasks Manual. | ||
7234 | |||
7235 | SSTATE_DIR | ||
7236 | The directory for the shared state cache. | ||
7237 | |||
7238 | SSTATE_MIRROR_ALLOW_NETWORK | ||
7239 | If set to "1", allows fetches from mirrors that are specified in | ||
7240 | :term:`SSTATE_MIRRORS` to work even when | ||
7241 | fetching from the network is disabled by setting ``BB_NO_NETWORK`` to | ||
7242 | "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if | ||
7243 | you have set ``SSTATE_MIRRORS`` to point to an internal server for | ||
7244 | your shared state cache, but you want to disable any other fetching | ||
7245 | from the network. | ||
7246 | |||
7247 | SSTATE_MIRRORS | ||
7248 | Configures the OpenEmbedded build system to search other mirror | ||
7249 | locations for prebuilt cache data objects before building out the | ||
7250 | data. This variable works like fetcher :term:`MIRRORS` | ||
7251 | and :term:`PREMIRRORS` and points to the cache | ||
7252 | locations to check for the shared state (sstate) objects. | ||
7253 | |||
7254 | You can specify a filesystem directory or a remote URL such as HTTP | ||
7255 | or FTP. The locations you specify need to contain the shared state | ||
7256 | cache (sstate-cache) results from previous builds. The sstate-cache | ||
7257 | you point to can also be from builds on other machines. | ||
7258 | |||
7259 | When pointing to sstate build artifacts on another machine that uses | ||
7260 | a different GCC version for native builds, you must configure | ||
7261 | ``SSTATE_MIRRORS`` with a regular expression that maps local search | ||
7262 | paths to server paths. The paths need to take into account | ||
7263 | :term:`NATIVELSBSTRING` set by the | ||
7264 | :ref:`uninative <ref-classes-uninative>` class. For example, the | ||
7265 | following maps the local search path ``universal-4.9`` to the | ||
7266 | server-provided path server_url_sstate_path: | ||
7267 | :: | ||
7268 | |||
7269 | SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n" | ||
7270 | |||
7271 | If a mirror uses the same structure as | ||
7272 | :term:`SSTATE_DIR`, you need to add "PATH" at the | ||
7273 | end as shown in the examples below. The build system substitutes the | ||
7274 | correct path within the directory structure. | ||
7275 | :: | ||
7276 | |||
7277 | SSTATE_MIRRORS ?= "\ | ||
7278 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | ||
7279 | file://.* file:///some-local-dir/sstate/PATH" | ||
7280 | |||
7281 | SSTATE_SCAN_FILES | ||
7282 | Controls the list of files the OpenEmbedded build system scans for | ||
7283 | hardcoded installation paths. The variable uses a space-separated | ||
7284 | list of filenames (not paths) with standard wildcard characters | ||
7285 | allowed. | ||
7286 | |||
7287 | During a build, the OpenEmbedded build system creates a shared state | ||
7288 | (sstate) object during the first stage of preparing the sysroots. | ||
7289 | That object is scanned for hardcoded paths for original installation | ||
7290 | locations. The list of files that are scanned for paths is controlled | ||
7291 | by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files | ||
7292 | they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather | ||
7293 | than the variable being comprehensively set. The | ||
7294 | :ref:`sstate <ref-classes-sstate>` class specifies the default list | ||
7295 | of files. | ||
7296 | |||
7297 | For details on the process, see the | ||
7298 | :ref:`staging <ref-classes-staging>` class. | ||
7299 | |||
7300 | STAGING_BASE_LIBDIR_NATIVE | ||
7301 | Specifies the path to the ``/lib`` subdirectory of the sysroot | ||
7302 | directory for the build host. | ||
7303 | |||
7304 | STAGING_BASELIBDIR | ||
7305 | Specifies the path to the ``/lib`` subdirectory of the sysroot | ||
7306 | directory for the target for which the current recipe is being built | ||
7307 | (:term:`STAGING_DIR_HOST`). | ||
7308 | |||
7309 | STAGING_BINDIR | ||
7310 | Specifies the path to the ``/usr/bin`` subdirectory of the sysroot | ||
7311 | directory for the target for which the current recipe is being built | ||
7312 | (:term:`STAGING_DIR_HOST`). | ||
7313 | |||
7314 | STAGING_BINDIR_CROSS | ||
7315 | Specifies the path to the directory containing binary configuration | ||
7316 | scripts. These scripts provide configuration information for other | ||
7317 | software that wants to make use of libraries or include files | ||
7318 | provided by the software associated with the script. | ||
7319 | |||
7320 | .. note:: | ||
7321 | |||
7322 | This style of build configuration has been largely replaced by | ||
7323 | pkg-config | ||
7324 | . Consequently, if | ||
7325 | pkg-config | ||
7326 | is supported by the library to which you are linking, it is | ||
7327 | recommended you use | ||
7328 | pkg-config | ||
7329 | instead of a provided configuration script. | ||
7330 | |||
7331 | STAGING_BINDIR_NATIVE | ||
7332 | Specifies the path to the ``/usr/bin`` subdirectory of the sysroot | ||
7333 | directory for the build host. | ||
7334 | |||
7335 | STAGING_DATADIR | ||
7336 | Specifies the path to the ``/usr/share`` subdirectory of the sysroot | ||
7337 | directory for the target for which the current recipe is being built | ||
7338 | (:term:`STAGING_DIR_HOST`). | ||
7339 | |||
7340 | STAGING_DATADIR_NATIVE | ||
7341 | Specifies the path to the ``/usr/share`` subdirectory of the sysroot | ||
7342 | directory for the build host. | ||
7343 | |||
7344 | STAGING_DIR | ||
7345 | Helps construct the ``recipe-sysroots`` directory, which is used | ||
7346 | during packaging. | ||
7347 | |||
7348 | For information on how staging for recipe-specific sysroots occurs, | ||
7349 | see the :ref:`ref-tasks-populate_sysroot` | ||
7350 | task, the ":ref:`sdk-manual/sdk-extensible:sharing files between recipes`" | ||
7351 | section in the Yocto Project Development Tasks Manual, the | ||
7352 | ":ref:`configuration-compilation-and-staging-dev-environment`" | ||
7353 | section in the Yocto Project Overview and Concepts Manual, and the | ||
7354 | :term:`SYSROOT_DIRS` variable. | ||
7355 | |||
7356 | .. note:: | ||
7357 | |||
7358 | Recipes should never write files directly under the | ||
7359 | STAGING_DIR | ||
7360 | directory because the OpenEmbedded build system manages the | ||
7361 | directory automatically. Instead, files should be installed to | ||
7362 | ${ | ||
7363 | D | ||
7364 | } | ||
7365 | within your recipe's | ||
7366 | do_install | ||
7367 | task and then the OpenEmbedded build system will stage a subset of | ||
7368 | those files into the sysroot. | ||
7369 | |||
7370 | STAGING_DIR_HOST | ||
7371 | Specifies the path to the sysroot directory for the system on which | ||
7372 | the component is built to run (the system that hosts the component). | ||
7373 | For most recipes, this sysroot is the one in which that recipe's | ||
7374 | :ref:`ref-tasks-populate_sysroot` task copies | ||
7375 | files. Exceptions include ``-native`` recipes, where the | ||
7376 | ``do_populate_sysroot`` task instead uses | ||
7377 | :term:`STAGING_DIR_NATIVE`. Depending on | ||
7378 | the type of recipe and the build target, ``STAGING_DIR_HOST`` can | ||
7379 | have the following values: | ||
7380 | |||
7381 | - For recipes building for the target machine, the value is | ||
7382 | "${:term:`STAGING_DIR`}/${:term:`MACHINE`}". | ||
7383 | |||
7384 | - For native recipes building for the build host, the value is empty | ||
7385 | given the assumption that when building for the build host, the | ||
7386 | build host's own directories should be used. | ||
7387 | |||
7388 | .. note:: | ||
7389 | |||
7390 | ``-native`` recipes are not installed into host paths like such | ||
7391 | as ``/usr``. Rather, these recipes are installed into | ||
7392 | ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, | ||
7393 | standard build environment variables such as | ||
7394 | :term:`CPPFLAGS` and | ||
7395 | :term:`CFLAGS` are set up so that both host paths | ||
7396 | and ``STAGING_DIR_NATIVE`` are searched for libraries and | ||
7397 | headers using, for example, GCC's ``-isystem`` option. | ||
7398 | |||
7399 | Thus, the emphasis is that the ``STAGING_DIR*`` variables | ||
7400 | should be viewed as input variables by tasks such as | ||
7401 | :ref:`ref-tasks-configure`, | ||
7402 | :ref:`ref-tasks-compile`, and | ||
7403 | :ref:`ref-tasks-install`. Having the real system | ||
7404 | root correspond to ``STAGING_DIR_HOST`` makes conceptual sense | ||
7405 | for ``-native`` recipes, as they make use of host headers and | ||
7406 | libraries. | ||
7407 | |||
7408 | STAGING_DIR_NATIVE | ||
7409 | Specifies the path to the sysroot directory used when building | ||
7410 | components that run on the build host itself. | ||
7411 | |||
7412 | STAGING_DIR_TARGET | ||
7413 | Specifies the path to the sysroot used for the system for which the | ||
7414 | component generates code. For components that do not generate code, | ||
7415 | which is the majority, ``STAGING_DIR_TARGET`` is set to match | ||
7416 | :term:`STAGING_DIR_HOST`. | ||
7417 | |||
7418 | Some recipes build binaries that can run on the target system but | ||
7419 | those binaries in turn generate code for another different system | ||
7420 | (e.g. cross-canadian recipes). Using terminology from GNU, the | ||
7421 | primary system is referred to as the "HOST" and the secondary, or | ||
7422 | different, system is referred to as the "TARGET". Thus, the binaries | ||
7423 | run on the "HOST" system and generate binaries for the "TARGET" | ||
7424 | system. The ``STAGING_DIR_HOST`` variable points to the sysroot used | ||
7425 | for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the | ||
7426 | sysroot used for the "TARGET" system. | ||
7427 | |||
7428 | STAGING_ETCDIR_NATIVE | ||
7429 | Specifies the path to the ``/etc`` subdirectory of the sysroot | ||
7430 | directory for the build host. | ||
7431 | |||
7432 | STAGING_EXECPREFIXDIR | ||
7433 | Specifies the path to the ``/usr`` subdirectory of the sysroot | ||
7434 | directory for the target for which the current recipe is being built | ||
7435 | (:term:`STAGING_DIR_HOST`). | ||
7436 | |||
7437 | STAGING_INCDIR | ||
7438 | Specifies the path to the ``/usr/include`` subdirectory of the | ||
7439 | sysroot directory for the target for which the current recipe being | ||
7440 | built (:term:`STAGING_DIR_HOST`). | ||
7441 | |||
7442 | STAGING_INCDIR_NATIVE | ||
7443 | Specifies the path to the ``/usr/include`` subdirectory of the | ||
7444 | sysroot directory for the build host. | ||
7445 | |||
7446 | STAGING_KERNEL_BUILDDIR | ||
7447 | Points to the directory containing the kernel build artifacts. | ||
7448 | Recipes building software that needs to access kernel build artifacts | ||
7449 | (e.g. ``systemtap-uprobes``) can look in the directory specified with | ||
7450 | the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts | ||
7451 | after the kernel has been built. | ||
7452 | |||
7453 | STAGING_KERNEL_DIR | ||
7454 | The directory with kernel headers that are required to build | ||
7455 | out-of-tree modules. | ||
7456 | |||
7457 | STAGING_LIBDIR | ||
7458 | Specifies the path to the ``/usr/lib`` subdirectory of the sysroot | ||
7459 | directory for the target for which the current recipe is being built | ||
7460 | (:term:`STAGING_DIR_HOST`). | ||
7461 | |||
7462 | STAGING_LIBDIR_NATIVE | ||
7463 | Specifies the path to the ``/usr/lib`` subdirectory of the sysroot | ||
7464 | directory for the build host. | ||
7465 | |||
7466 | STAMP | ||
7467 | Specifies the base path used to create recipe stamp files. The path | ||
7468 | to an actual stamp file is constructed by evaluating this string and | ||
7469 | then appending additional information. Currently, the default | ||
7470 | assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` | ||
7471 | file is: | ||
7472 | :: | ||
7473 | |||
7474 | STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" | ||
7475 | |||
7476 | For information on how BitBake uses stamp files to determine if a | ||
7477 | task should be rerun, see the | ||
7478 | ":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`" | ||
7479 | section in the Yocto Project Overview and Concepts Manual. | ||
7480 | |||
7481 | See :term:`STAMPS_DIR`, | ||
7482 | :term:`MULTIMACH_TARGET_SYS`, | ||
7483 | :term:`PN`, :term:`EXTENDPE`, | ||
7484 | :term:`PV`, and :term:`PR` for related variable | ||
7485 | information. | ||
7486 | |||
7487 | STAMPS_DIR | ||
7488 | Specifies the base directory in which the OpenEmbedded build system | ||
7489 | places stamps. The default directory is ``${TMPDIR}/stamps``. | ||
7490 | |||
7491 | STRIP | ||
7492 | The minimal command and arguments to run ``strip``, which is used to | ||
7493 | strip symbols. | ||
7494 | |||
7495 | SUMMARY | ||
7496 | The short (72 characters or less) summary of the binary package for | ||
7497 | packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, | ||
7498 | ``SUMMARY`` is used to define the | ||
7499 | :term:`DESCRIPTION` variable if ``DESCRIPTION`` is | ||
7500 | not set in the recipe. | ||
7501 | |||
7502 | SVNDIR | ||
7503 | The directory in which files checked out of a Subversion system are | ||
7504 | stored. | ||
7505 | |||
7506 | SYSLINUX_DEFAULT_CONSOLE | ||
7507 | Specifies the kernel boot default console. If you want to use a | ||
7508 | console other than the default, set this variable in your recipe as | ||
7509 | follows where "X" is the console number you want to use: | ||
7510 | :: | ||
7511 | |||
7512 | SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" | ||
7513 | |||
7514 | The :ref:`syslinux <ref-classes-syslinux>` class initially sets | ||
7515 | this variable to null but then checks for a value later. | ||
7516 | |||
7517 | SYSLINUX_OPTS | ||
7518 | Lists additional options to add to the syslinux file. You need to set | ||
7519 | this variable in your recipe. If you want to list multiple options, | ||
7520 | separate the options with a semicolon character (``;``). | ||
7521 | |||
7522 | The :ref:`syslinux <ref-classes-syslinux>` class uses this variable | ||
7523 | to create a set of options. | ||
7524 | |||
7525 | SYSLINUX_SERIAL | ||
7526 | Specifies the alternate serial port or turns it off. To turn off | ||
7527 | serial, set this variable to an empty string in your recipe. The | ||
7528 | variable's default value is set in the | ||
7529 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | ||
7530 | :: | ||
7531 | |||
7532 | SYSLINUX_SERIAL ?= "0 115200" | ||
7533 | |||
7534 | The class checks for and uses the variable as needed. | ||
7535 | |||
7536 | SYSLINUX_SPLASH | ||
7537 | An ``.LSS`` file used as the background for the VGA boot menu when | ||
7538 | you use the boot menu. You need to set this variable in your recipe. | ||
7539 | |||
7540 | The :ref:`syslinux <ref-classes-syslinux>` class checks for this | ||
7541 | variable and if found, the OpenEmbedded build system installs the | ||
7542 | splash screen. | ||
7543 | |||
7544 | SYSLINUX_SERIAL_TTY | ||
7545 | Specifies the alternate console=tty... kernel boot argument. The | ||
7546 | variable's default value is set in the | ||
7547 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | ||
7548 | :: | ||
7549 | |||
7550 | SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" | ||
7551 | |||
7552 | The class checks for and uses the variable as needed. | ||
7553 | |||
7554 | SYSROOT_DESTDIR | ||
7555 | Points to the temporary directory under the work directory (default | ||
7556 | "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``") | ||
7557 | where the files populated into the sysroot are assembled during the | ||
7558 | :ref:`ref-tasks-populate_sysroot` task. | ||
7559 | |||
7560 | SYSROOT_DIRS | ||
7561 | Directories that are staged into the sysroot by the | ||
7562 | :ref:`ref-tasks-populate_sysroot` task. By | ||
7563 | default, the following directories are staged: | ||
7564 | :: | ||
7565 | |||
7566 | SYSROOT_DIRS = " \ | ||
7567 | ${includedir} \ | ||
7568 | ${libdir} \ | ||
7569 | ${base_libdir} \ | ||
7570 | ${nonarch_base_libdir} \ | ||
7571 | ${datadir} \ | ||
7572 | " | ||
7573 | |||
7574 | SYSROOT_DIRS_BLACKLIST | ||
7575 | Directories that are not staged into the sysroot by the | ||
7576 | :ref:`ref-tasks-populate_sysroot` task. You | ||
7577 | can use this variable to exclude certain subdirectories of | ||
7578 | directories listed in :term:`SYSROOT_DIRS` from | ||
7579 | staging. By default, the following directories are not staged: | ||
7580 | :: | ||
7581 | |||
7582 | SYSROOT_DIRS_BLACKLIST = " \ | ||
7583 | ${mandir} \ | ||
7584 | ${docdir} \ | ||
7585 | ${infodir} \ | ||
7586 | ${datadir}/locale \ | ||
7587 | ${datadir}/applications \ | ||
7588 | ${datadir}/fonts \ | ||
7589 | ${datadir}/pixmaps \ | ||
7590 | " | ||
7591 | |||
7592 | SYSROOT_DIRS_NATIVE | ||
7593 | Extra directories staged into the sysroot by the | ||
7594 | :ref:`ref-tasks-populate_sysroot` task for | ||
7595 | ``-native`` recipes, in addition to those specified in | ||
7596 | :term:`SYSROOT_DIRS`. By default, the following | ||
7597 | extra directories are staged: | ||
7598 | :: | ||
7599 | |||
7600 | SYSROOT_DIRS_NATIVE = " \ | ||
7601 | ${bindir} \ | ||
7602 | ${sbindir} \ | ||
7603 | ${base_bindir} \ | ||
7604 | ${base_sbindir} \ | ||
7605 | ${libexecdir} \ | ||
7606 | ${sysconfdir} \ | ||
7607 | ${localstatedir} \ | ||
7608 | " | ||
7609 | |||
7610 | .. note:: | ||
7611 | |||
7612 | Programs built by | ||
7613 | -native | ||
7614 | recipes run directly from the sysroot ( | ||
7615 | STAGING_DIR_NATIVE | ||
7616 | ), which is why additional directories containing program | ||
7617 | executables and supporting files need to be staged. | ||
7618 | |||
7619 | SYSROOT_PREPROCESS_FUNCS | ||
7620 | A list of functions to execute after files are staged into the | ||
7621 | sysroot. These functions are usually used to apply additional | ||
7622 | processing on the staged files, or to stage additional files. | ||
7623 | |||
7624 | SYSTEMD_AUTO_ENABLE | ||
7625 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | ||
7626 | this variable specifies whether the specified service in | ||
7627 | :term:`SYSTEMD_SERVICE` should start | ||
7628 | automatically or not. By default, the service is enabled to | ||
7629 | automatically start at boot time. The default setting is in the | ||
7630 | :ref:`systemd <ref-classes-systemd>` class as follows: | ||
7631 | :: | ||
7632 | |||
7633 | SYSTEMD_AUTO_ENABLE ??= "enable" | ||
7634 | |||
7635 | You can disable the service by setting the variable to "disable". | ||
7636 | |||
7637 | SYSTEMD_BOOT_CFG | ||
7638 | When :term:`EFI_PROVIDER` is set to | ||
7639 | "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the | ||
7640 | configuration file that should be used. By default, the | ||
7641 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | ||
7642 | ``SYSTEMD_BOOT_CFG`` as follows: | ||
7643 | :: | ||
7644 | |||
7645 | SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf" | ||
7646 | |||
7647 | For information on Systemd-boot, see the `Systemd-boot | ||
7648 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | ||
7649 | |||
7650 | SYSTEMD_BOOT_ENTRIES | ||
7651 | When :term:`EFI_PROVIDER` is set to | ||
7652 | "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a | ||
7653 | list of entry files (``*.conf``) to install that contain one boot | ||
7654 | entry per file. By default, the | ||
7655 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | ||
7656 | ``SYSTEMD_BOOT_ENTRIES`` as follows: | ||
7657 | :: | ||
7658 | |||
7659 | SYSTEMD_BOOT_ENTRIES ?= "" | ||
7660 | |||
7661 | For information on Systemd-boot, see the `Systemd-boot | ||
7662 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | ||
7663 | |||
7664 | SYSTEMD_BOOT_TIMEOUT | ||
7665 | When :term:`EFI_PROVIDER` is set to | ||
7666 | "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the | ||
7667 | boot menu timeout in seconds. By default, the | ||
7668 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | ||
7669 | ``SYSTEMD_BOOT_TIMEOUT`` as follows: | ||
7670 | :: | ||
7671 | |||
7672 | SYSTEMD_BOOT_TIMEOUT ?= "10" | ||
7673 | |||
7674 | For information on Systemd-boot, see the `Systemd-boot | ||
7675 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | ||
7676 | |||
7677 | SYSTEMD_PACKAGES | ||
7678 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | ||
7679 | this variable locates the systemd unit files when they are not found | ||
7680 | in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` | ||
7681 | variable is set such that the systemd unit files are assumed to | ||
7682 | reside in the recipes main package: | ||
7683 | :: | ||
7684 | |||
7685 | SYSTEMD_PACKAGES ?= "${PN}" | ||
7686 | |||
7687 | If these unit files are not in this recipe's main package, you need | ||
7688 | to use ``SYSTEMD_PACKAGES`` to list the package or packages in which | ||
7689 | the build system can find the systemd unit files. | ||
7690 | |||
7691 | SYSTEMD_SERVICE | ||
7692 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | ||
7693 | this variable specifies the systemd service name for a package. | ||
7694 | |||
7695 | When you specify this file in your recipe, use a package name | ||
7696 | override to indicate the package to which the value applies. Here is | ||
7697 | an example from the connman recipe: | ||
7698 | :: | ||
7699 | |||
7700 | SYSTEMD_SERVICE_${PN} = "connman.service" | ||
7701 | |||
7702 | SYSVINIT_ENABLED_GETTYS | ||
7703 | When using | ||
7704 | :ref:`SysVinit <dev-manual/dev-manual-common-tasks:enabling system services>`, | ||
7705 | specifies a space-separated list of the virtual terminals that should | ||
7706 | run a `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ | ||
7707 | (allowing login), assuming :term:`USE_VT` is not set to | ||
7708 | "0". | ||
7709 | |||
7710 | The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only | ||
7711 | run a getty on the first virtual terminal). | ||
7712 | |||
7713 | T | ||
7714 | This variable points to a directory were BitBake places temporary | ||
7715 | files, which consist mostly of task logs and scripts, when building a | ||
7716 | particular recipe. The variable is typically set as follows: | ||
7717 | :: | ||
7718 | |||
7719 | T = "${WORKDIR}/temp" | ||
7720 | |||
7721 | The :term:`WORKDIR` is the directory into which | ||
7722 | BitBake unpacks and builds the recipe. The default ``bitbake.conf`` | ||
7723 | file sets this variable. | ||
7724 | |||
7725 | The ``T`` variable is not to be confused with the | ||
7726 | :term:`TMPDIR` variable, which points to the root of | ||
7727 | the directory tree where BitBake places the output of an entire | ||
7728 | build. | ||
7729 | |||
7730 | TARGET_ARCH | ||
7731 | The target machine's architecture. The OpenEmbedded build system | ||
7732 | supports many architectures. Here is an example list of architectures | ||
7733 | supported. This list is by no means complete as the architecture is | ||
7734 | configurable: | ||
7735 | |||
7736 | - arm | ||
7737 | - i586 | ||
7738 | - x86_64 | ||
7739 | - powerpc | ||
7740 | - powerpc64 | ||
7741 | - mips | ||
7742 | - mipsel | ||
7743 | |||
7744 | For additional information on machine architectures, see the | ||
7745 | :term:`TUNE_ARCH` variable. | ||
7746 | |||
7747 | TARGET_AS_ARCH | ||
7748 | Specifies architecture-specific assembler flags for the target | ||
7749 | system. ``TARGET_AS_ARCH`` is initialized from | ||
7750 | :term:`TUNE_ASARGS` by default in the BitBake | ||
7751 | configuration file (``meta/conf/bitbake.conf``): | ||
7752 | :: | ||
7753 | |||
7754 | TARGET_AS_ARCH = "${TUNE_ASARGS}" | ||
7755 | |||
7756 | TARGET_CC_ARCH | ||
7757 | Specifies architecture-specific C compiler flags for the target | ||
7758 | system. ``TARGET_CC_ARCH`` is initialized from | ||
7759 | :term:`TUNE_CCARGS` by default. | ||
7760 | |||
7761 | .. note:: | ||
7762 | |||
7763 | It is a common workaround to append | ||
7764 | LDFLAGS | ||
7765 | to | ||
7766 | TARGET_CC_ARCH | ||
7767 | in recipes that build software for the target that would not | ||
7768 | otherwise respect the exported | ||
7769 | LDFLAGS | ||
7770 | variable. | ||
7771 | |||
7772 | TARGET_CC_KERNEL_ARCH | ||
7773 | This is a specific kernel compiler flag for a CPU or Application | ||
7774 | Binary Interface (ABI) tune. The flag is used rarely and only for | ||
7775 | cases where a userspace :term:`TUNE_CCARGS` is not | ||
7776 | compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` | ||
7777 | variable allows the kernel (and associated modules) to use a | ||
7778 | different configuration. See the | ||
7779 | ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the | ||
7780 | :term:`Source Directory` for an example. | ||
7781 | |||
7782 | TARGET_CFLAGS | ||
7783 | Specifies the flags to pass to the C compiler when building for the | ||
7784 | target. When building in the target context, | ||
7785 | :term:`CFLAGS` is set to the value of this variable by | ||
7786 | default. | ||
7787 | |||
7788 | Additionally, the SDK's environment setup script sets the ``CFLAGS`` | ||
7789 | variable in the environment to the ``TARGET_CFLAGS`` value so that | ||
7790 | executables built using the SDK also have the flags applied. | ||
7791 | |||
7792 | TARGET_CPPFLAGS | ||
7793 | Specifies the flags to pass to the C pre-processor (i.e. to both the | ||
7794 | C and the C++ compilers) when building for the target. When building | ||
7795 | in the target context, :term:`CPPFLAGS` is set to the | ||
7796 | value of this variable by default. | ||
7797 | |||
7798 | Additionally, the SDK's environment setup script sets the | ||
7799 | ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` | ||
7800 | value so that executables built using the SDK also have the flags | ||
7801 | applied. | ||
7802 | |||
7803 | TARGET_CXXFLAGS | ||
7804 | Specifies the flags to pass to the C++ compiler when building for the | ||
7805 | target. When building in the target context, | ||
7806 | :term:`CXXFLAGS` is set to the value of this variable | ||
7807 | by default. | ||
7808 | |||
7809 | Additionally, the SDK's environment setup script sets the | ||
7810 | ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` | ||
7811 | value so that executables built using the SDK also have the flags | ||
7812 | applied. | ||
7813 | |||
7814 | TARGET_FPU | ||
7815 | Specifies the method for handling FPU code. For FPU-less targets, | ||
7816 | which include most ARM CPUs, the variable must be set to "soft". If | ||
7817 | not, the kernel emulation gets used, which results in a performance | ||
7818 | penalty. | ||
7819 | |||
7820 | TARGET_LD_ARCH | ||
7821 | Specifies architecture-specific linker flags for the target system. | ||
7822 | ``TARGET_LD_ARCH`` is initialized from | ||
7823 | :term:`TUNE_LDARGS` by default in the BitBake | ||
7824 | configuration file (``meta/conf/bitbake.conf``): | ||
7825 | :: | ||
7826 | |||
7827 | TARGET_LD_ARCH = "${TUNE_LDARGS}" | ||
7828 | |||
7829 | TARGET_LDFLAGS | ||
7830 | Specifies the flags to pass to the linker when building for the | ||
7831 | target. When building in the target context, | ||
7832 | :term:`LDFLAGS` is set to the value of this variable | ||
7833 | by default. | ||
7834 | |||
7835 | Additionally, the SDK's environment setup script sets the | ||
7836 | :term:`LDFLAGS` variable in the environment to the | ||
7837 | ``TARGET_LDFLAGS`` value so that executables built using the SDK also | ||
7838 | have the flags applied. | ||
7839 | |||
7840 | TARGET_OS | ||
7841 | Specifies the target's operating system. The variable can be set to | ||
7842 | "linux" for glibc-based systems (GNU C Library) and to "linux-musl" | ||
7843 | for musl libc. For ARM/EABI targets, "linux-gnueabi" and | ||
7844 | "linux-musleabi" possible values exist. | ||
7845 | |||
7846 | TARGET_PREFIX | ||
7847 | Specifies the prefix used for the toolchain binary target tools. | ||
7848 | |||
7849 | Depending on the type of recipe and the build target, | ||
7850 | ``TARGET_PREFIX`` is set as follows: | ||
7851 | |||
7852 | - For recipes building for the target machine, the value is | ||
7853 | "${:term:`TARGET_SYS`}-". | ||
7854 | |||
7855 | - For native recipes, the build system sets the variable to the | ||
7856 | value of ``BUILD_PREFIX``. | ||
7857 | |||
7858 | - For native SDK recipes (``nativesdk``), the build system sets the | ||
7859 | variable to the value of ``SDK_PREFIX``. | ||
7860 | |||
7861 | TARGET_SYS | ||
7862 | Specifies the system, including the architecture and the operating | ||
7863 | system, for which the build is occurring in the context of the | ||
7864 | current recipe. | ||
7865 | |||
7866 | The OpenEmbedded build system automatically sets this variable based | ||
7867 | on :term:`TARGET_ARCH`, | ||
7868 | :term:`TARGET_VENDOR`, and | ||
7869 | :term:`TARGET_OS` variables. | ||
7870 | |||
7871 | .. note:: | ||
7872 | |||
7873 | You do not need to set the TARGET_SYS variable yourself. | ||
7874 | |||
7875 | Consider these two examples: | ||
7876 | |||
7877 | - Given a native recipe on a 32-bit, x86 machine running Linux, the | ||
7878 | value is "i686-linux". | ||
7879 | |||
7880 | - Given a recipe being built for a little-endian, MIPS target | ||
7881 | running Linux, the value might be "mipsel-linux". | ||
7882 | |||
7883 | TARGET_VENDOR | ||
7884 | Specifies the name of the target vendor. | ||
7885 | |||
7886 | TCLIBC | ||
7887 | Specifies the GNU standard C library (``libc``) variant to use during | ||
7888 | the build process. This variable replaces ``POKYLIBC``, which is no | ||
7889 | longer supported. | ||
7890 | |||
7891 | You can select "glibc", "musl", "newlib", or "baremetal" | ||
7892 | |||
7893 | TCLIBCAPPEND | ||
7894 | Specifies a suffix to be appended onto the | ||
7895 | :term:`TMPDIR` value. The suffix identifies the | ||
7896 | ``libc`` variant for building. When you are building for multiple | ||
7897 | variants with the same :term:`Build Directory`, this | ||
7898 | mechanism ensures that output for different ``libc`` variants is kept | ||
7899 | separate to avoid potential conflicts. | ||
7900 | |||
7901 | In the ``defaultsetup.conf`` file, the default value of | ||
7902 | ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, | ||
7903 | which normally only support one ``libc`` variant, set | ||
7904 | ``TCLIBCAPPEND`` to "" in their distro configuration file resulting | ||
7905 | in no suffix being applied. | ||
7906 | |||
7907 | TCMODE | ||
7908 | Specifies the toolchain selector. ``TCMODE`` controls the | ||
7909 | characteristics of the generated packages and images by telling the | ||
7910 | OpenEmbedded build system which toolchain profile to use. By default, | ||
7911 | the OpenEmbedded build system builds its own internal toolchain. The | ||
7912 | variable's default value is "default", which uses that internal | ||
7913 | toolchain. | ||
7914 | |||
7915 | .. note:: | ||
7916 | |||
7917 | If | ||
7918 | TCMODE | ||
7919 | is set to a value other than "default", then it is your | ||
7920 | responsibility to ensure that the toolchain is compatible with the | ||
7921 | default toolchain. Using older or newer versions of these | ||
7922 | components might cause build problems. See the Release Notes for | ||
7923 | the Yocto Project release for the specific components with which | ||
7924 | the toolchain must be compatible. To access the Release Notes, go | ||
7925 | to the | ||
7926 | Downloads | ||
7927 | page on the Yocto Project website and click on the "RELEASE | ||
7928 | INFORMATION" link for the appropriate release. | ||
7929 | |||
7930 | The ``TCMODE`` variable is similar to :term:`TCLIBC`, | ||
7931 | which controls the variant of the GNU standard C library (``libc``) | ||
7932 | used during the build process: ``glibc`` or ``musl``. | ||
7933 | |||
7934 | With additional layers, it is possible to use a pre-compiled external | ||
7935 | toolchain. One example is the Sourcery G++ Toolchain. The support for | ||
7936 | this toolchain resides in the separate Mentor Graphics | ||
7937 | ``meta-sourcery`` layer at | ||
7938 | http://github.com/MentorEmbedded/meta-sourcery/. | ||
7939 | |||
7940 | The layer's ``README`` file contains information on how to use the | ||
7941 | Sourcery G++ Toolchain as an external toolchain. In summary, you must | ||
7942 | be sure to add the layer to your ``bblayers.conf`` file in front of | ||
7943 | the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable | ||
7944 | in your ``local.conf`` file to the location in which you installed | ||
7945 | the toolchain. | ||
7946 | |||
7947 | The fundamentals used for this example apply to any external | ||
7948 | toolchain. You can use ``meta-sourcery`` as a template for adding | ||
7949 | support for other external toolchains. | ||
7950 | |||
7951 | TEST_EXPORT_DIR | ||
7952 | The location the OpenEmbedded build system uses to export tests when | ||
7953 | the :term:`TEST_EXPORT_ONLY` variable is set | ||
7954 | to "1". | ||
7955 | |||
7956 | The ``TEST_EXPORT_DIR`` variable defaults to | ||
7957 | ``"${TMPDIR}/testimage/${PN}"``. | ||
7958 | |||
7959 | TEST_EXPORT_ONLY | ||
7960 | Specifies to export the tests only. Set this variable to "1" if you | ||
7961 | do not want to run the tests but you want them to be exported in a | ||
7962 | manner that you to run them outside of the build system. | ||
7963 | |||
7964 | TEST_LOG_DIR | ||
7965 | Holds the SSH log and the boot log for QEMU machines. The | ||
7966 | ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. | ||
7967 | |||
7968 | .. note:: | ||
7969 | |||
7970 | Actual test results reside in the task log ( | ||
7971 | log.do_testimage | ||
7972 | ), which is in the | ||
7973 | ${WORKDIR}/temp/ | ||
7974 | directory. | ||
7975 | |||
7976 | TEST_POWERCONTROL_CMD | ||
7977 | For automated hardware testing, specifies the command to use to | ||
7978 | control the power of the target machine under test. Typically, this | ||
7979 | command would point to a script that performs the appropriate action | ||
7980 | (e.g. interacting with a web-enabled power strip). The specified | ||
7981 | command should expect to receive as the last argument "off", "on" or | ||
7982 | "cycle" specifying to power off, on, or cycle (power off and then | ||
7983 | power on) the device, respectively. | ||
7984 | |||
7985 | TEST_POWERCONTROL_EXTRA_ARGS | ||
7986 | For automated hardware testing, specifies additional arguments to | ||
7987 | pass through to the command specified in | ||
7988 | :term:`TEST_POWERCONTROL_CMD`. Setting | ||
7989 | ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you | ||
7990 | wish, for example, to separate the machine-specific and | ||
7991 | non-machine-specific parts of the arguments. | ||
7992 | |||
7993 | TEST_QEMUBOOT_TIMEOUT | ||
7994 | The time in seconds allowed for an image to boot before automated | ||
7995 | runtime tests begin to run against an image. The default timeout | ||
7996 | period to allow the boot process to reach the login prompt is 500 | ||
7997 | seconds. You can specify a different value in the ``local.conf`` | ||
7998 | file. | ||
7999 | |||
8000 | For more information on testing images, see the | ||
8001 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
8002 | section in the Yocto Project Development Tasks Manual. | ||
8003 | |||
8004 | TEST_SERIALCONTROL_CMD | ||
8005 | For automated hardware testing, specifies the command to use to | ||
8006 | connect to the serial console of the target machine under test. This | ||
8007 | command simply needs to connect to the serial console and forward | ||
8008 | that connection to standard input and output as any normal terminal | ||
8009 | program does. | ||
8010 | |||
8011 | For example, to use the Picocom terminal program on serial device | ||
8012 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: | ||
8013 | :: | ||
8014 | |||
8015 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" | ||
8016 | |||
8017 | TEST_SERIALCONTROL_EXTRA_ARGS | ||
8018 | For automated hardware testing, specifies additional arguments to | ||
8019 | pass through to the command specified in | ||
8020 | :term:`TEST_SERIALCONTROL_CMD`. Setting | ||
8021 | ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you | ||
8022 | wish, for example, to separate the machine-specific and | ||
8023 | non-machine-specific parts of the command. | ||
8024 | |||
8025 | TEST_SERVER_IP | ||
8026 | The IP address of the build machine (host machine). This IP address | ||
8027 | is usually automatically detected. However, if detection fails, this | ||
8028 | variable needs to be set to the IP address of the build machine (i.e. | ||
8029 | where the build is taking place). | ||
8030 | |||
8031 | .. note:: | ||
8032 | |||
8033 | The | ||
8034 | TEST_SERVER_IP | ||
8035 | variable is only used for a small number of tests such as the | ||
8036 | "dnf" test suite, which needs to download packages from | ||
8037 | WORKDIR/oe-rootfs-repo | ||
8038 | . | ||
8039 | |||
8040 | TEST_TARGET | ||
8041 | Specifies the target controller to use when running tests against a | ||
8042 | test image. The default controller to use is "qemu": | ||
8043 | :: | ||
8044 | |||
8045 | TEST_TARGET = "qemu" | ||
8046 | |||
8047 | A target controller is a class that defines how an image gets | ||
8048 | deployed on a target and how a target is started. A layer can extend | ||
8049 | the controllers by adding a module in the layer's | ||
8050 | ``/lib/oeqa/controllers`` directory and by inheriting the | ||
8051 | ``BaseTarget`` class, which is an abstract class that cannot be used | ||
8052 | as a value of ``TEST_TARGET``. | ||
8053 | |||
8054 | You can provide the following arguments with ``TEST_TARGET``: | ||
8055 | |||
8056 | - *"qemu":* Boots a QEMU image and runs the tests. See the | ||
8057 | ":ref:`qemu-image-enabling-tests`" section | ||
8058 | in the Yocto Project Development Tasks Manual for more | ||
8059 | information. | ||
8060 | |||
8061 | - *"simpleremote":* Runs the tests on target hardware that is | ||
8062 | already up and running. The hardware can be on the network or it | ||
8063 | can be a device running an image on QEMU. You must also set | ||
8064 | :term:`TEST_TARGET_IP` when you use | ||
8065 | "simpleremote". | ||
8066 | |||
8067 | .. note:: | ||
8068 | |||
8069 | This argument is defined in | ||
8070 | meta/lib/oeqa/controllers/simpleremote.py | ||
8071 | . | ||
8072 | |||
8073 | For information on running tests on hardware, see the | ||
8074 | ":ref:`hardware-image-enabling-tests`" | ||
8075 | section in the Yocto Project Development Tasks Manual. | ||
8076 | |||
8077 | TEST_TARGET_IP | ||
8078 | The IP address of your hardware under test. The ``TEST_TARGET_IP`` | ||
8079 | variable has no effect when :term:`TEST_TARGET` is | ||
8080 | set to "qemu". | ||
8081 | |||
8082 | When you specify the IP address, you can also include a port. Here is | ||
8083 | an example: | ||
8084 | :: | ||
8085 | |||
8086 | TEST_TARGET_IP = "192.168.1.4:2201" | ||
8087 | |||
8088 | Specifying a port is | ||
8089 | useful when SSH is started on a non-standard port or in cases when | ||
8090 | your hardware under test is behind a firewall or network that is not | ||
8091 | directly accessible from your host and you need to do port address | ||
8092 | translation. | ||
8093 | |||
8094 | TEST_SUITES | ||
8095 | An ordered list of tests (modules) to run against an image when | ||
8096 | performing automated runtime testing. | ||
8097 | |||
8098 | The OpenEmbedded build system provides a core set of tests that can | ||
8099 | be used against images. | ||
8100 | |||
8101 | .. note:: | ||
8102 | |||
8103 | Currently, there is only support for running these tests under | ||
8104 | QEMU. | ||
8105 | |||
8106 | Tests include ``ping``, ``ssh``, ``df`` among others. You can add | ||
8107 | your own tests to the list of tests by appending ``TEST_SUITES`` as | ||
8108 | follows: | ||
8109 | :: | ||
8110 | |||
8111 | TEST_SUITES_append = " mytest" | ||
8112 | |||
8113 | Alternatively, you can | ||
8114 | provide the "auto" option to have all applicable tests run against | ||
8115 | the image. | ||
8116 | :: | ||
8117 | |||
8118 | TEST_SUITES_append = " auto" | ||
8119 | |||
8120 | Using this option causes the | ||
8121 | build system to automatically run tests that are applicable to the | ||
8122 | image. Tests that are not applicable are skipped. | ||
8123 | |||
8124 | The order in which tests are run is important. Tests that depend on | ||
8125 | another test must appear later in the list than the test on which | ||
8126 | they depend. For example, if you append the list of tests with two | ||
8127 | tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on | ||
8128 | ``test_A``, then you must order the tests as follows: | ||
8129 | :: | ||
8130 | |||
8131 | TEST_SUITES = "test_A test_B" | ||
8132 | |||
8133 | For more information on testing images, see the | ||
8134 | ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`" | ||
8135 | section in the Yocto Project Development Tasks Manual. | ||
8136 | |||
8137 | TESTIMAGE_AUTO | ||
8138 | Automatically runs the series of automated tests for images when an | ||
8139 | image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes | ||
8140 | any image that successfully builds to automatically boot under QEMU. | ||
8141 | Using the variable also adds in dependencies so that any SDK for | ||
8142 | which testing is requested is automatically built first. | ||
8143 | |||
8144 | These tests are written in Python making use of the ``unittest`` | ||
8145 | module, and the majority of them run commands on the target system | ||
8146 | over ``ssh``. You can set this variable to "1" in your ``local.conf`` | ||
8147 | file in the :term:`Build Directory` to have the | ||
8148 | OpenEmbedded build system automatically run these tests after an | ||
8149 | image successfully builds: | ||
8150 | |||
8151 | TESTIMAGE_AUTO = "1" | ||
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`" | ||
8156 | section in the Yocto Project Development Tasks Manual and the | ||
8157 | ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section. | ||
8158 | |||
8159 | THISDIR | ||
8160 | The directory in which the file BitBake is currently parsing is | ||
8161 | located. Do not manually set this variable. | ||
8162 | |||
8163 | TIME | ||
8164 | The time the build was started. Times appear using the hour, minute, | ||
8165 | and second (HMS) format (e.g. "140159" for one minute and fifty-nine | ||
8166 | seconds past 1400 hours). | ||
8167 | |||
8168 | TMPDIR | ||
8169 | This variable is the base directory the OpenEmbedded build system | ||
8170 | uses for all build output and intermediate files (other than the | ||
8171 | shared state cache). By default, the ``TMPDIR`` variable points to | ||
8172 | ``tmp`` within the :term:`Build Directory`. | ||
8173 | |||
8174 | If you want to establish this directory in a location other than the | ||
8175 | default, you can uncomment and edit the following statement in the | ||
8176 | ``conf/local.conf`` file in the :term:`Source Directory`: | ||
8177 | :: | ||
8178 | |||
8179 | #TMPDIR = "${TOPDIR}/tmp" | ||
8180 | |||
8181 | An example use for this scenario is to set ``TMPDIR`` to a local disk, | ||
8182 | which does not use NFS, while having the Build Directory use NFS. | ||
8183 | |||
8184 | The filesystem used by ``TMPDIR`` must have standard filesystem | ||
8185 | semantics (i.e. mixed-case files are unique, POSIX file locking, and | ||
8186 | persistent inodes). Due to various issues with NFS and bugs in some | ||
8187 | implementations, NFS does not meet this minimum requirement. | ||
8188 | Consequently, ``TMPDIR`` cannot be on NFS. | ||
8189 | |||
8190 | TOOLCHAIN_HOST_TASK | ||
8191 | This variable lists packages the OpenEmbedded build system uses when | ||
8192 | building an SDK, which contains a cross-development environment. The | ||
8193 | packages specified by this variable are part of the toolchain set | ||
8194 | that runs on the :term:`SDKMACHINE`, and each | ||
8195 | package should usually have the prefix ``nativesdk-``. For example, | ||
8196 | consider the following command when building an SDK: | ||
8197 | :: | ||
8198 | |||
8199 | $ bitbake -c populate_sdk imagename | ||
8200 | |||
8201 | In this case, a default list of packages is | ||
8202 | set in this variable, but you can add additional packages to the | ||
8203 | list. See the | ||
8204 | ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding individual packages to the standard sdk`" section | ||
8205 | in the Yocto Project Application Development and the Extensible | ||
8206 | Software Development Kit (eSDK) manual for more information. | ||
8207 | |||
8208 | For background information on cross-development toolchains in the | ||
8209 | Yocto Project development environment, see the | ||
8210 | ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`" | ||
8211 | section in the Yocto Project Overview and Concepts Manual. For | ||
8212 | information on setting up a cross-development environment, see the | ||
8213 | :doc:`../sdk-manual/sdk-manual` manual. | ||
8214 | |||
8215 | TOOLCHAIN_OUTPUTNAME | ||
8216 | This variable defines the name used for the toolchain output. The | ||
8217 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets | ||
8218 | the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: | ||
8219 | :: | ||
8220 | |||
8221 | TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" | ||
8222 | |||
8223 | See | ||
8224 | the :term:`SDK_NAME` and | ||
8225 | :term:`SDK_VERSION` variables for additional | ||
8226 | information. | ||
8227 | |||
8228 | TOOLCHAIN_TARGET_TASK | ||
8229 | This variable lists packages the OpenEmbedded build system uses when | ||
8230 | it creates the target part of an SDK (i.e. the part built for the | ||
8231 | target hardware), which includes libraries and headers. Use this | ||
8232 | variable to add individual packages to the part of the SDK that runs | ||
8233 | on the target. See the | ||
8234 | ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding individual packages to the standard sdk`" section | ||
8235 | in the Yocto Project Application Development and the Extensible | ||
8236 | Software Development Kit (eSDK) manual for more information. | ||
8237 | |||
8238 | For background information on cross-development toolchains in the | ||
8239 | Yocto Project development environment, see the | ||
8240 | ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`" | ||
8241 | section in the Yocto Project Overview and Concepts Manual. For | ||
8242 | information on setting up a cross-development environment, see the | ||
8243 | :doc:`../sdk-manual/sdk-manual` manual. | ||
8244 | |||
8245 | TOPDIR | ||
8246 | The top-level :term:`Build Directory`. BitBake | ||
8247 | automatically sets this variable when you initialize your build | ||
8248 | environment using ````` <#structure-core-script>`__. | ||
8249 | |||
8250 | TRANSLATED_TARGET_ARCH | ||
8251 | A sanitized version of :term:`TARGET_ARCH`. This | ||
8252 | variable is used where the architecture is needed in a value where | ||
8253 | underscores are not allowed, for example within package filenames. In | ||
8254 | this case, dash characters replace any underscore characters used in | ||
8255 | ``TARGET_ARCH``. | ||
8256 | |||
8257 | Do not edit this variable. | ||
8258 | |||
8259 | TUNE_ARCH | ||
8260 | The GNU canonical architecture for a specific architecture (i.e. | ||
8261 | ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses | ||
8262 | this value to setup configuration. | ||
8263 | |||
8264 | ``TUNE_ARCH`` definitions are specific to a given architecture. The | ||
8265 | definitions can be a single static definition, or can be dynamically | ||
8266 | adjusted. You can see details for a given CPU family by looking at | ||
8267 | the architecture's ``README`` file. For example, the | ||
8268 | ``meta/conf/machine/include/mips/README`` file in the | ||
8269 | :term:`Source Directory` provides information for | ||
8270 | ``TUNE_ARCH`` specific to the ``mips`` architecture. | ||
8271 | |||
8272 | ``TUNE_ARCH`` is tied closely to | ||
8273 | :term:`TARGET_ARCH`, which defines the target | ||
8274 | machine's architecture. The BitBake configuration file | ||
8275 | (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: | ||
8276 | :: | ||
8277 | |||
8278 | TARGET_ARCH = "${TUNE_ARCH}" | ||
8279 | |||
8280 | The following list, which is by no means complete since architectures | ||
8281 | are configurable, shows supported machine architectures: | ||
8282 | |||
8283 | - arm | ||
8284 | - i586 | ||
8285 | - x86_64 | ||
8286 | - powerpc | ||
8287 | - powerpc64 | ||
8288 | - mips | ||
8289 | - mipsel | ||
8290 | |||
8291 | TUNE_ASARGS | ||
8292 | Specifies architecture-specific assembler flags for the target | ||
8293 | system. The set of flags is based on the selected tune features. | ||
8294 | ``TUNE_ASARGS`` is set using the tune include files, which are | ||
8295 | typically under ``meta/conf/machine/include/`` and are influenced | ||
8296 | through :term:`TUNE_FEATURES`. For example, the | ||
8297 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags | ||
8298 | for the x86 architecture as follows: | ||
8299 | :: | ||
8300 | |||
8301 | TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" | ||
8302 | |||
8303 | .. note:: | ||
8304 | |||
8305 | Board Support Packages (BSPs) select the tune. The selected tune, | ||
8306 | in turn, affects the tune variables themselves (i.e. the tune can | ||
8307 | supply its own set of flags). | ||
8308 | |||
8309 | TUNE_CCARGS | ||
8310 | Specifies architecture-specific C compiler flags for the target | ||
8311 | system. The set of flags is based on the selected tune features. | ||
8312 | ``TUNE_CCARGS`` is set using the tune include files, which are | ||
8313 | typically under ``meta/conf/machine/include/`` and are influenced | ||
8314 | through :term:`TUNE_FEATURES`. | ||
8315 | |||
8316 | .. note:: | ||
8317 | |||
8318 | Board Support Packages (BSPs) select the tune. The selected tune, | ||
8319 | in turn, affects the tune variables themselves (i.e. the tune can | ||
8320 | supply its own set of flags). | ||
8321 | |||
8322 | TUNE_LDARGS | ||
8323 | Specifies architecture-specific linker flags for the target system. | ||
8324 | The set of flags is based on the selected tune features. | ||
8325 | ``TUNE_LDARGS`` is set using the tune include files, which are | ||
8326 | typically under ``meta/conf/machine/include/`` and are influenced | ||
8327 | through :term:`TUNE_FEATURES`. For example, the | ||
8328 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags | ||
8329 | for the x86 architecture as follows: | ||
8330 | :: | ||
8331 | |||
8332 | TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" | ||
8333 | |||
8334 | .. note:: | ||
8335 | |||
8336 | Board Support Packages (BSPs) select the tune. The selected tune, | ||
8337 | in turn, affects the tune variables themselves (i.e. the tune can | ||
8338 | supply its own set of flags). | ||
8339 | |||
8340 | TUNE_FEATURES | ||
8341 | Features used to "tune" a compiler for optimal use given a specific | ||
8342 | processor. The features are defined within the tune files and allow | ||
8343 | arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on | ||
8344 | the features. | ||
8345 | |||
8346 | The OpenEmbedded build system verifies the features to be sure they | ||
8347 | are not conflicting and that they are supported. | ||
8348 | |||
8349 | The BitBake configuration file (``meta/conf/bitbake.conf``) defines | ||
8350 | ``TUNE_FEATURES`` as follows: | ||
8351 | :: | ||
8352 | |||
8353 | TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" | ||
8354 | |||
8355 | See the :term:`DEFAULTTUNE` variable for more information. | ||
8356 | |||
8357 | TUNE_PKGARCH | ||
8358 | The package architecture understood by the packaging system to define | ||
8359 | the architecture, ABI, and tuning of output packages. The specific | ||
8360 | tune is defined using the "_tune" override as follows: | ||
8361 | :: | ||
8362 | |||
8363 | TUNE_PKGARCH_tune-tune = "tune" | ||
8364 | |||
8365 | These tune-specific package architectures are defined in the machine | ||
8366 | include files. Here is an example of the "core2-32" tuning as used in | ||
8367 | the ``meta/conf/machine/include/tune-core2.inc`` file: | ||
8368 | :: | ||
8369 | |||
8370 | TUNE_PKGARCH_tune-core2-32 = "core2-32" | ||
8371 | |||
8372 | TUNEABI | ||
8373 | An underlying Application Binary Interface (ABI) used by a particular | ||
8374 | tuning in a given toolchain layer. Providers that use prebuilt | ||
8375 | libraries can use the ``TUNEABI``, | ||
8376 | :term:`TUNEABI_OVERRIDE`, and | ||
8377 | :term:`TUNEABI_WHITELIST` variables to check | ||
8378 | compatibility of tunings against their selection of libraries. | ||
8379 | |||
8380 | If ``TUNEABI`` is undefined, then every tuning is allowed. See the | ||
8381 | :ref:`sanity <ref-classes-sanity>` class to see how the variable is | ||
8382 | used. | ||
8383 | |||
8384 | TUNEABI_OVERRIDE | ||
8385 | If set, the OpenEmbedded system ignores the | ||
8386 | :term:`TUNEABI_WHITELIST` variable. | ||
8387 | Providers that use prebuilt libraries can use the | ||
8388 | ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and | ||
8389 | :term:`TUNEABI` variables to check compatibility of a | ||
8390 | tuning against their selection of libraries. | ||
8391 | |||
8392 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8393 | variable is used. | ||
8394 | |||
8395 | TUNEABI_WHITELIST | ||
8396 | A whitelist of permissible :term:`TUNEABI` values. If | ||
8397 | ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers | ||
8398 | that use prebuilt libraries can use the ``TUNEABI_WHITELIST``, | ||
8399 | :term:`TUNEABI_OVERRIDE`, and ``TUNEABI`` | ||
8400 | variables to check compatibility of a tuning against their selection | ||
8401 | of libraries. | ||
8402 | |||
8403 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8404 | variable is used. | ||
8405 | |||
8406 | TUNECONFLICTS[feature] | ||
8407 | Specifies CPU or Application Binary Interface (ABI) tuning features | ||
8408 | that conflict with feature. | ||
8409 | |||
8410 | Known tuning conflicts are specified in the machine include files in | ||
8411 | the :term:`Source Directory`. Here is an example from | ||
8412 | the ``meta/conf/machine/include/mips/arch-mips.inc`` include file | ||
8413 | that lists the "o32" and "n64" features as conflicting with the "n32" | ||
8414 | feature: | ||
8415 | :: | ||
8416 | |||
8417 | TUNECONFLICTS[n32] = "o32 n64" | ||
8418 | |||
8419 | TUNEVALID[feature] | ||
8420 | Specifies a valid CPU or Application Binary Interface (ABI) tuning | ||
8421 | feature. The specified feature is stored as a flag. Valid features | ||
8422 | are specified in the machine include files (e.g. | ||
8423 | ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example | ||
8424 | from that file: | ||
8425 | :: | ||
8426 | |||
8427 | TUNEVALID[bigendian] = "Enable big-endian mode." | ||
8428 | |||
8429 | See the machine include files in the :term:`Source Directory` | ||
8430 | for these features. | ||
8431 | |||
8432 | UBOOT_CONFIG | ||
8433 | Configures the :term:`UBOOT_MACHINE` and can | ||
8434 | also define :term:`IMAGE_FSTYPES` for individual | ||
8435 | cases. | ||
8436 | |||
8437 | Following is an example from the ``meta-fsl-arm`` layer. :: | ||
8438 | |||
8439 | UBOOT_CONFIG ??= "sd" | ||
8440 | UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" | ||
8441 | UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" | ||
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 | ||
8446 | ``UBOOT_MACHINE``. The "sd" configuration defines | ||
8447 | "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the | ||
8448 | "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image. | ||
8449 | |||
8450 | For more information on how the ``UBOOT_CONFIG`` is handled, see the | ||
8451 | :ref:`uboot-config <ref-classes-uboot-config>` | ||
8452 | class. | ||
8453 | |||
8454 | UBOOT_DTB_LOADADDRESS | ||
8455 | Specifies the load address for the dtb image used by U-boot. During FIT | ||
8456 | image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in | ||
8457 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify | ||
8458 | the load address to be used in | ||
8459 | creating the dtb sections of Image Tree Source for the FIT image. | ||
8460 | |||
8461 | UBOOT_DTBO_LOADADDRESS | ||
8462 | Specifies the load address for the dtbo image used by U-boot. During FIT | ||
8463 | image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in | ||
8464 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in | ||
8465 | creating the dtbo sections of Image Tree Source for the FIT image. | ||
8466 | |||
8467 | UBOOT_ENTRYPOINT | ||
8468 | Specifies the entry point for the U-Boot image. During U-Boot image | ||
8469 | creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a | ||
8470 | command-line parameter to the ``uboot-mkimage`` utility. | ||
8471 | |||
8472 | UBOOT_LOADADDRESS | ||
8473 | Specifies the load address for the U-Boot image. During U-Boot image | ||
8474 | creation, the ``UBOOT_LOADADDRESS`` variable is passed as a | ||
8475 | command-line parameter to the ``uboot-mkimage`` utility. | ||
8476 | |||
8477 | UBOOT_LOCALVERSION | ||
8478 | Appends a string to the name of the local version of the U-Boot | ||
8479 | image. For example, assuming the version of the U-Boot image built | ||
8480 | was "2013.10", the full version string reported by U-Boot would be | ||
8481 | "2013.10-yocto" given the following statement: | ||
8482 | :: | ||
8483 | |||
8484 | UBOOT_LOCALVERSION = "-yocto" | ||
8485 | |||
8486 | UBOOT_MACHINE | ||
8487 | Specifies the value passed on the ``make`` command line when building | ||
8488 | a U-Boot image. The value indicates the target platform | ||
8489 | configuration. You typically set this variable from the machine | ||
8490 | configuration file (i.e. ``conf/machine/machine_name.conf``). | ||
8491 | |||
8492 | Please see the "Selection of Processor Architecture and Board Type" | ||
8493 | section in the U-Boot README for valid values for this variable. | ||
8494 | |||
8495 | UBOOT_MAKE_TARGET | ||
8496 | Specifies the target called in the ``Makefile``. The default target | ||
8497 | is "all". | ||
8498 | |||
8499 | UBOOT_MKIMAGE_DTCOPTS | ||
8500 | Options for the device tree compiler passed to mkimage '-D' | ||
8501 | feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class. | ||
8502 | |||
8503 | UBOOT_RD_LOADADDRESS | ||
8504 | Specifies the load address for the RAM disk image. | ||
8505 | During FIT image creation, the | ||
8506 | ``UBOOT_RD_LOADADDRESS`` variable is used | ||
8507 | in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the | ||
8508 | load address to be used in creating the Image Tree Source for | ||
8509 | the FIT image. | ||
8510 | |||
8511 | UBOOT_RD_ENTRYPOINT | ||
8512 | Specifies the entrypoint for the RAM disk image. | ||
8513 | During FIT image creation, the | ||
8514 | ``UBOOT_RD_ENTRYPOINT`` variable is used | ||
8515 | in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the | ||
8516 | entrypoint to be used in creating the Image Tree Source for | ||
8517 | the FIT image. | ||
8518 | |||
8519 | UBOOT_SIGN_ENABLE | ||
8520 | Enable signing of FIT image. The default value is "0". | ||
8521 | |||
8522 | UBOOT_SIGN_KEYDIR | ||
8523 | Location of the directory containing the RSA key and | ||
8524 | certificate used for signing FIT image. | ||
8525 | |||
8526 | UBOOT_SIGN_KEYNAME | ||
8527 | The name of keys used for signing U-boot FIT image stored in | ||
8528 | :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt | ||
8529 | certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have | ||
8530 | :term:`UBOOT_SIGN_KEYNAME` set to "dev". | ||
8531 | |||
8532 | UBOOT_SUFFIX | ||
8533 | Points to the generated U-Boot extension. For example, ``u-boot.sb`` | ||
8534 | has a ``.sb`` extension. | ||
8535 | |||
8536 | The default U-Boot extension is ``.bin`` | ||
8537 | |||
8538 | UBOOT_TARGET | ||
8539 | Specifies the target used for building U-Boot. The target is passed | ||
8540 | directly as part of the "make" command (e.g. SPL and AIS). If you do | ||
8541 | not specifically set this variable, the OpenEmbedded build process | ||
8542 | passes and uses "all" for the target during the U-Boot building | ||
8543 | process. | ||
8544 | |||
8545 | UNKNOWN_CONFIGURE_WHITELIST | ||
8546 | Specifies a list of options that, if reported by the configure script | ||
8547 | as being invalid, should not generate a warning during the | ||
8548 | :ref:`ref-tasks-configure` task. Normally, invalid | ||
8549 | configure options are simply not passed to the configure script (e.g. | ||
8550 | should be removed from :term:`EXTRA_OECONF` or | ||
8551 | :term:`PACKAGECONFIG_CONFARGS`). | ||
8552 | However, common options, for example, exist that are passed to all | ||
8553 | configure scripts at a class level that might not be valid for some | ||
8554 | configure scripts. It follows that no benefit exists in seeing a | ||
8555 | warning about these options. For these cases, the options are added | ||
8556 | to ``UNKNOWN_CONFIGURE_WHITELIST``. | ||
8557 | |||
8558 | The configure arguments check that uses | ||
8559 | ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the | ||
8560 | :ref:`insane <ref-classes-insane>` class and is only enabled if the | ||
8561 | recipe inherits the :ref:`autotools <ref-classes-autotools>` class. | ||
8562 | |||
8563 | UPDATERCPN | ||
8564 | For recipes inheriting the | ||
8565 | :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` | ||
8566 | specifies the package that contains the initscript that is enabled. | ||
8567 | |||
8568 | The default value is "${PN}". Given that almost all recipes that | ||
8569 | install initscripts package them in the main package for the recipe, | ||
8570 | you rarely need to set this variable in individual recipes. | ||
8571 | |||
8572 | UPSTREAM_CHECK_GITTAGREGEX | ||
8573 | You can perform a per-recipe check for what the latest upstream | ||
8574 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | ||
8575 | the recipe source code is provided from Git repositories, the | ||
8576 | OpenEmbedded build system determines the latest upstream version by | ||
8577 | picking the latest tag from the list of all repository tags. | ||
8578 | |||
8579 | You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a | ||
8580 | regular expression to filter only the relevant tags should the | ||
8581 | default filter not work correctly. | ||
8582 | :: | ||
8583 | |||
8584 | UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" | ||
8585 | |||
8586 | UPSTREAM_CHECK_REGEX | ||
8587 | Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different | ||
8588 | regular expression instead of the default one when the package | ||
8589 | checking system is parsing the page found using | ||
8590 | :term:`UPSTREAM_CHECK_URI`. | ||
8591 | :: | ||
8592 | |||
8593 | UPSTREAM_CHECK_REGEX = "package_regex" | ||
8594 | |||
8595 | UPSTREAM_CHECK_URI | ||
8596 | You can perform a per-recipe check for what the latest upstream | ||
8597 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | ||
8598 | the source code is provided from tarballs, the latest version is | ||
8599 | determined by fetching the directory listing where the tarball is and | ||
8600 | attempting to find a later tarball. When this approach does not work, | ||
8601 | you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that | ||
8602 | contains the link to the latest tarball. | ||
8603 | :: | ||
8604 | |||
8605 | UPSTREAM_CHECK_URI = "recipe_url" | ||
8606 | |||
8607 | USE_DEVFS | ||
8608 | Determines if ``devtmpfs`` is used for ``/dev`` population. The | ||
8609 | default value used for ``USE_DEVFS`` is "1" when no value is | ||
8610 | specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a | ||
8611 | statically populated ``/dev`` directory. | ||
8612 | |||
8613 | See the ":ref:`selecting-dev-manager`" section in | ||
8614 | the Yocto Project Development Tasks Manual for information on how to | ||
8615 | use this variable. | ||
8616 | |||
8617 | USE_VT | ||
8618 | When using | ||
8619 | :ref:`SysVinit <new-recipe-enabling-system-services>`, | ||
8620 | determines whether or not to run a | ||
8621 | `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any | ||
8622 | virtual terminals in order to enable logging in through those | ||
8623 | terminals. | ||
8624 | |||
8625 | The default value used for ``USE_VT`` is "1" when no default value is | ||
8626 | specifically set. Typically, you would set ``USE_VT`` to "0" in the | ||
8627 | machine configuration file for machines that do not have a graphical | ||
8628 | display attached and therefore do not need virtual terminal | ||
8629 | functionality. | ||
8630 | |||
8631 | USER_CLASSES | ||
8632 | A list of classes to globally inherit. These classes are used by the | ||
8633 | OpenEmbedded build system to enable extra features (e.g. | ||
8634 | ``buildstats``, ``image-mklibs``, and so forth). | ||
8635 | |||
8636 | The default list is set in your ``local.conf`` file: | ||
8637 | :: | ||
8638 | |||
8639 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | ||
8640 | |||
8641 | For more information, see | ||
8642 | ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`. | ||
8643 | |||
8644 | USERADD_ERROR_DYNAMIC | ||
8645 | If set to ``error``, forces the OpenEmbedded build system to produce | ||
8646 | an error if the user identification (``uid``) and group | ||
8647 | identification (``gid``) values are not defined in any of the files | ||
8648 | listed in :term:`USERADD_UID_TABLES` and | ||
8649 | :term:`USERADD_GID_TABLES`. If set to | ||
8650 | ``warn``, a warning will be issued instead. | ||
8651 | |||
8652 | The default behavior for the build system is to dynamically apply | ||
8653 | ``uid`` and ``gid`` values. Consequently, the | ||
8654 | ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan | ||
8655 | on using statically assigned ``gid`` and ``uid`` values, you should | ||
8656 | set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` | ||
8657 | file as follows: | ||
8658 | :: | ||
8659 | |||
8660 | USERADD_ERROR_DYNAMIC = "error" | ||
8661 | |||
8662 | Overriding the | ||
8663 | default behavior implies you are going to also take steps to set | ||
8664 | static ``uid`` and ``gid`` values through use of the | ||
8665 | :term:`USERADDEXTENSION`, | ||
8666 | :term:`USERADD_UID_TABLES`, and | ||
8667 | :term:`USERADD_GID_TABLES` variables. | ||
8668 | |||
8669 | .. note:: | ||
8670 | |||
8671 | There is a difference in behavior between setting | ||
8672 | USERADD_ERROR_DYNAMIC | ||
8673 | to | ||
8674 | error | ||
8675 | and setting it to | ||
8676 | warn | ||
8677 | . When it is set to | ||
8678 | warn | ||
8679 | , the build system will report a warning for every undefined | ||
8680 | uid | ||
8681 | and | ||
8682 | gid | ||
8683 | in any recipe. But when it is set to | ||
8684 | error | ||
8685 | , it will only report errors for recipes that are actually built. | ||
8686 | This saves you from having to add static IDs for recipes that you | ||
8687 | know will never be built. | ||
8688 | |||
8689 | USERADD_GID_TABLES | ||
8690 | Specifies a password file to use for obtaining static group | ||
8691 | identification (``gid``) values when the OpenEmbedded build system | ||
8692 | adds a group to the system during package installation. | ||
8693 | |||
8694 | When applying static group identification (``gid``) values, the | ||
8695 | OpenEmbedded build system looks in :term:`BBPATH` for a | ||
8696 | ``files/group`` file and then applies those ``uid`` values. Set the | ||
8697 | variable as follows in your ``local.conf`` file: | ||
8698 | :: | ||
8699 | |||
8700 | |||
8701 | USERADD_GID_TABLES = "files/group" | ||
8702 | |||
8703 | .. note:: | ||
8704 | |||
8705 | Setting the | ||
8706 | USERADDEXTENSION | ||
8707 | variable to "useradd-staticids" causes the build system to use | ||
8708 | static | ||
8709 | gid | ||
8710 | values. | ||
8711 | |||
8712 | USERADD_PACKAGES | ||
8713 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
8714 | this variable specifies the individual packages within the recipe | ||
8715 | that require users and/or groups to be added. | ||
8716 | |||
8717 | You must set this variable if the recipe inherits the class. For | ||
8718 | example, the following enables adding a user for the main package in | ||
8719 | a recipe: | ||
8720 | :: | ||
8721 | |||
8722 | USERADD_PACKAGES = "${PN}" | ||
8723 | |||
8724 | .. note:: | ||
8725 | |||
8726 | It follows that if you are going to use the | ||
8727 | USERADD_PACKAGES | ||
8728 | variable, you need to set one or more of the | ||
8729 | USERADD_PARAM | ||
8730 | , | ||
8731 | GROUPADD_PARAM | ||
8732 | , or | ||
8733 | GROUPMEMS_PARAM | ||
8734 | variables. | ||
8735 | |||
8736 | USERADD_PARAM | ||
8737 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
8738 | this variable specifies for a package what parameters should pass to | ||
8739 | the ``useradd`` command if you add a user to the system when the | ||
8740 | package is installed. | ||
8741 | |||
8742 | Here is an example from the ``dbus`` recipe: | ||
8743 | :: | ||
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 | ||
8750 | standard Linux shell command ``useradd``, see | ||
8751 | http://linux.die.net/man/8/useradd. | ||
8752 | |||
8753 | USERADD_UID_TABLES | ||
8754 | Specifies a password file to use for obtaining static user | ||
8755 | identification (``uid``) values when the OpenEmbedded build system | ||
8756 | adds a user to the system during package installation. | ||
8757 | |||
8758 | When applying static user identification (``uid``) values, the | ||
8759 | OpenEmbedded build system looks in :term:`BBPATH` for a | ||
8760 | ``files/passwd`` file and then applies those ``uid`` values. Set the | ||
8761 | variable as follows in your ``local.conf`` file: | ||
8762 | :: | ||
8763 | |||
8764 | USERADD_UID_TABLES = "files/passwd" | ||
8765 | |||
8766 | .. note:: | ||
8767 | |||
8768 | Setting the | ||
8769 | USERADDEXTENSION | ||
8770 | variable to "useradd-staticids" causes the build system to use | ||
8771 | static | ||
8772 | uid | ||
8773 | values. | ||
8774 | |||
8775 | USERADDEXTENSION | ||
8776 | When set to "useradd-staticids", causes the OpenEmbedded build system | ||
8777 | to base all user and group additions on a static ``passwd`` and | ||
8778 | ``group`` files found in :term:`BBPATH`. | ||
8779 | |||
8780 | To use static user identification (``uid``) and group identification | ||
8781 | (``gid``) values, set the variable as follows in your ``local.conf`` | ||
8782 | file: USERADDEXTENSION = "useradd-staticids" | ||
8783 | |||
8784 | .. note:: | ||
8785 | |||
8786 | Setting this variable to use static | ||
8787 | uid | ||
8788 | and | ||
8789 | gid | ||
8790 | values causes the OpenEmbedded build system to employ the | ||
8791 | useradd-staticids | ||
8792 | class. | ||
8793 | |||
8794 | If you use static ``uid`` and ``gid`` information, you must also | ||
8795 | specify the ``files/passwd`` and ``files/group`` files by setting the | ||
8796 | :term:`USERADD_UID_TABLES` and | ||
8797 | :term:`USERADD_GID_TABLES` variables. | ||
8798 | Additionally, you should also set the | ||
8799 | :term:`USERADD_ERROR_DYNAMIC` variable. | ||
8800 | |||
8801 | VOLATILE_LOG_DIR | ||
8802 | Specifies the persistence of the target's ``/var/log`` directory, | ||
8803 | which is used to house postinstall target log files. | ||
8804 | |||
8805 | By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the | ||
8806 | file is not persistent. You can override this setting by setting the | ||
8807 | variable to "no" to make the log directory persistent. | ||
8808 | |||
8809 | WARN_QA | ||
8810 | Specifies the quality assurance checks whose failures are reported as | ||
8811 | warnings by the OpenEmbedded build system. You set this variable in | ||
8812 | your distribution configuration file. For a list of the checks you | ||
8813 | can control with this variable, see the | ||
8814 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | ||
8815 | |||
8816 | WKS_FILE_DEPENDS | ||
8817 | When placed in the recipe that builds your image, this variable lists | ||
8818 | build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only | ||
8819 | applicable when Wic images are active (i.e. when | ||
8820 | :term:`IMAGE_FSTYPES` contains entries related | ||
8821 | to Wic). If your recipe does not create Wic images, the variable has | ||
8822 | no effect. | ||
8823 | |||
8824 | The ``WKS_FILE_DEPENDS`` variable is similar to the | ||
8825 | :term:`DEPENDS` variable. When you use the variable in | ||
8826 | your recipe that builds the Wic image, dependencies you list in the | ||
8827 | ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. | ||
8828 | |||
8829 | With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to | ||
8830 | specify a list of additional dependencies (e.g. native tools, | ||
8831 | bootloaders, and so forth), that are required to build Wic images. | ||
8832 | Following is an example: | ||
8833 | :: | ||
8834 | |||
8835 | WKS_FILE_DEPENDS = "some-native-tool" | ||
8836 | |||
8837 | In the | ||
8838 | previous example, some-native-tool would be replaced with an actual | ||
8839 | native tool on which the build would depend. | ||
8840 | |||
8841 | WKS_FILE | ||
8842 | Specifies the location of the Wic kickstart file that is used by the | ||
8843 | OpenEmbedded build system to create a partitioned image | ||
8844 | (image\ ``.wic``). For information on how to create a partitioned | ||
8845 | image, see the | ||
8846 | ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`" | ||
8847 | section in the Yocto Project Development Tasks Manual. For details on | ||
8848 | the kickstart file format, see the ":doc:`../ref-manual/ref-kickstart`" Chapter. | ||
8849 | |||
8850 | WORKDIR | ||
8851 | The pathname of the work directory in which the OpenEmbedded build | ||
8852 | system builds a recipe. This directory is located within the | ||
8853 | :term:`TMPDIR` directory structure and is specific to | ||
8854 | the recipe being built and the system for which it is being built. | ||
8855 | |||
8856 | The ``WORKDIR`` directory is defined as follows: | ||
8857 | :: | ||
8858 | |||
8859 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} | ||
8860 | |||
8861 | The actual directory depends on several things: | ||
8862 | |||
8863 | - TMPDIR | ||
8864 | : The top-level build output directory | ||
8865 | - MULTIMACH_TARGET_SYS | ||
8866 | : The target system identifier | ||
8867 | - PN | ||
8868 | : The recipe name | ||
8869 | - EXTENDPE | ||
8870 | : The epoch - (if | ||
8871 | PE | ||
8872 | is not specified, which is usually the case for most recipes, then | ||
8873 | EXTENDPE | ||
8874 | is blank) | ||
8875 | - PV | ||
8876 | : The recipe version | ||
8877 | - PR | ||
8878 | : The recipe revision | ||
8879 | |||
8880 | As an example, assume a Source Directory top-level folder name | ||
8881 | ``poky``, a default Build Directory at ``poky/build``, and a | ||
8882 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose | ||
8883 | your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work | ||
8884 | directory the build system uses to build the package would be as | ||
8885 | follows: | ||
8886 | :: | ||
8887 | |||
8888 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 | ||
8889 | |||
8890 | XSERVER | ||
8891 | Specifies the packages that should be installed to provide an X | ||
8892 | server and drivers for the current machine, assuming your image | ||
8893 | directly includes ``packagegroup-core-x11-xserver`` or, perhaps | ||
8894 | indirectly, includes "x11-base" in | ||
8895 | :term:`IMAGE_FEATURES`. | ||
8896 | |||
8897 | The default value of ``XSERVER``, if not specified in the machine | ||
8898 | configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". | ||
8899 | |||
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index 364cd09eb8..a5064807e5 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <!-- Dummy chapter --> | 6 | <!-- Dummy chapter --> |
6 | <chapter id='ref-variables-glos'> | 7 | <chapter id='ref-variables-glos'> |
@@ -4990,6 +4991,30 @@ | |||
4990 | </glossdef> | 4991 | </glossdef> |
4991 | </glossentry> | 4992 | </glossentry> |
4992 | 4993 | ||
4994 | <glossentry id='var-FIT_HASH_ALG'><glossterm>FIT_HASH_ALG</glossterm> | ||
4995 | <info> | ||
4996 | FIT_HASH_ALG[doc] = "Specifies the hash algorithm used in creating the FIT Image." | ||
4997 | </info> | ||
4998 | <glossdef> | ||
4999 | <para role="glossdeffirst"> | ||
5000 | Specifies the hash algorithm used in creating the FIT Image. | ||
5001 | For e.g. sha256. | ||
5002 | </para> | ||
5003 | </glossdef> | ||
5004 | </glossentry> | ||
5005 | |||
5006 | <glossentry id='var-FIT_SIGN_ALG'><glossterm>FIT_SIGN_ALG</glossterm> | ||
5007 | <info> | ||
5008 | FIT_SIGN_ALG[doc] = "Specifies the signature algorithm used in creating the FIT Image." | ||
5009 | </info> | ||
5010 | <glossdef> | ||
5011 | <para role="glossdeffirst"> | ||
5012 | Specifies the signature algorithm used in creating the FIT Image. | ||
5013 | For e.g. rsa2048. | ||
5014 | </para> | ||
5015 | </glossdef> | ||
5016 | </glossentry> | ||
5017 | |||
4993 | <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm> | 5018 | <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm> |
4994 | <info> | 5019 | <info> |
4995 | FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'." | 5020 | FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'." |
@@ -5702,7 +5727,7 @@ | |||
5702 | <para role="glossdeffirst"> | 5727 | <para role="glossdeffirst"> |
5703 | A space-separated list of files installed into the | 5728 | A space-separated list of files installed into the |
5704 | boot partition when preparing an image using the Wic tool | 5729 | boot partition when preparing an image using the Wic tool |
5705 | with the <filename>bootimg-partition</filename> source | 5730 | with the <filename>bootimg-partition</filename> or <filename>bootimg-efi</filename> source |
5706 | plugin. | 5731 | plugin. |
5707 | By default, the files are installed under the same name as | 5732 | By default, the files are installed under the same name as |
5708 | the source files. | 5733 | the source files. |
@@ -9539,6 +9564,40 @@ | |||
9539 | </glossdef> | 9564 | </glossdef> |
9540 | </glossentry> | 9565 | </glossentry> |
9541 | 9566 | ||
9567 | <glossentry id='var-PACKAGE_ADD_METADATA'><glossterm>PACKAGE_ADD_METADATA</glossterm> | ||
9568 | <info> | ||
9569 | PACKAGE_ADD_METADATA[doc] = "This variable defines additional metadata to add to packages." | ||
9570 | </info> | ||
9571 | <glossdef> | ||
9572 | <para role="glossdeffirst"> | ||
9573 | <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> | ||
9574 | This variable defines additional metdata to add to packages. | ||
9575 | </para> | ||
9576 | |||
9577 | <para> | ||
9578 | You may find you need to inject additional metadata into | ||
9579 | packages. This variable allows you to do that by setting | ||
9580 | the injected data as the value. Multiple fields can be | ||
9581 | added by splitting the content with the literal separator | ||
9582 | "\n". | ||
9583 | </para> | ||
9584 | |||
9585 | <para> | ||
9586 | The suffixes '_IPK', '_DEB', or '_RPM' can be applied to | ||
9587 | the variable to do package type specific settings. It can | ||
9588 | also be made package specific by using the package name as | ||
9589 | a suffix. | ||
9590 | </para> | ||
9591 | |||
9592 | <para> | ||
9593 | You can find out more about applying this variable in | ||
9594 | the | ||
9595 | "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-custom-metadata-to-packages'>Adding custom metadata to packages</ulink>" | ||
9596 | section in the Yocto Project Development Tasks Manual. | ||
9597 | </para> | ||
9598 | </glossdef> | ||
9599 | </glossentry> | ||
9600 | |||
9542 | <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm> | 9601 | <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm> |
9543 | <info> | 9602 | <info> |
9544 | PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages." | 9603 | PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages." |
@@ -15925,6 +15984,38 @@ | |||
15925 | </glossdef> | 15984 | </glossdef> |
15926 | </glossentry> | 15985 | </glossentry> |
15927 | 15986 | ||
15987 | <glossentry id='var-UBOOT_DTB_LOADADDRESS'><glossterm>UBOOT_DTB_LOADADDRESS</glossterm> | ||
15988 | <info> | ||
15989 | UBOOT_DTB_LOADADDRESS[doc] = "Specifies the load address for the dtb." | ||
15990 | </info> | ||
15991 | <glossdef> | ||
15992 | <para role="glossdeffirst"> | ||
15993 | Specifies the load address for the dtb image used by U-boot. | ||
15994 | During FIT image creation, the | ||
15995 | <filename>UBOOT_DTB_LOADADDRESS</filename> variable is used | ||
15996 | in <filename>kernel-fitimage</filename> class to specify the | ||
15997 | load address to be used in creating the dtb sections of | ||
15998 | Image Tree Source for the FIT image. | ||
15999 | </para> | ||
16000 | </glossdef> | ||
16001 | </glossentry> | ||
16002 | |||
16003 | <glossentry id='var-UBOOT_DTBO_LOADADDRESS'><glossterm>UBOOT_DTBO_LOADADDRESS</glossterm> | ||
16004 | <info> | ||
16005 | UBOOT_DTBO_LOADADDRESS[doc] = "Specifies the load address for the dtbo." | ||
16006 | </info> | ||
16007 | <glossdef> | ||
16008 | <para role="glossdeffirst"> | ||
16009 | Specifies the load address for the dtbo image used by U-boot. | ||
16010 | During FIT image creation, the | ||
16011 | <filename>UBOOT_DTBO_LOADADDRESS</filename> variable is used | ||
16012 | in <filename>kernel-fitimage</filename> class to specify the | ||
16013 | load address to be used in creating the dtbo sections of | ||
16014 | Image Tree Source for the FIT image. | ||
16015 | </para> | ||
16016 | </glossdef> | ||
16017 | </glossentry> | ||
16018 | |||
15928 | <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> | 16019 | <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> |
15929 | <info> | 16020 | <info> |
15930 | UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image." | 16021 | UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image." |
@@ -16010,6 +16101,51 @@ | |||
16010 | </glossdef> | 16101 | </glossdef> |
16011 | </glossentry> | 16102 | </glossentry> |
16012 | 16103 | ||
16104 | <glossentry id='var-UBOOT_MKIMAGE_DTCOPTS'><glossterm>UBOOT_MKIMAGE_DTCOPTS</glossterm> | ||
16105 | <info> | ||
16106 | UBOOT_MKIMAGE_DTCOPTS[doc] = "Options for the device tree compiler passed to mkimage '-D' feature." | ||
16107 | </info> | ||
16108 | <glossdef> | ||
16109 | <para role="glossdeffirst"> | ||
16110 | Options for the device tree compiler passed to mkimage '-D' | ||
16111 | feature while creating FIT image in | ||
16112 | <filename>kernel-fitimage</filename> class. | ||
16113 | </para> | ||
16114 | </glossdef> | ||
16115 | </glossentry> | ||
16116 | |||
16117 | <glossentry id='var-UBOOT_RD_LOADADDRESS'><glossterm>UBOOT_RD_LOADADDRESS</glossterm> | ||
16118 | <info> | ||
16119 | UBOOT_RD_LOADADDRESS[doc] = "Specifies the load address for the ramdisk image." | ||
16120 | </info> | ||
16121 | <glossdef> | ||
16122 | <para role="glossdeffirst"> | ||
16123 | Specifies the load address for the RAM disk image. | ||
16124 | During FIT image creation, the | ||
16125 | <filename>UBOOT_RD_LOADADDRESS</filename> variable is used | ||
16126 | in <filename>kernel-fitimage</filename> class to specify the | ||
16127 | load address to be used in creating the Image Tree Source for | ||
16128 | the FIT image. | ||
16129 | </para> | ||
16130 | </glossdef> | ||
16131 | </glossentry> | ||
16132 | |||
16133 | <glossentry id='var-UBOOT_RD_ENTRYPOINT'><glossterm>UBOOT_RD_ENTRYPOINT</glossterm> | ||
16134 | <info> | ||
16135 | UBOOT_RD_ENTRYPOINT[doc] = "Specifies the entrypoint for the ramdisk image." | ||
16136 | </info> | ||
16137 | <glossdef> | ||
16138 | <para role="glossdeffirst"> | ||
16139 | Specifies the entrypoint for the RAM disk image. | ||
16140 | During FIT image creation, the | ||
16141 | <filename>UBOOT_RD_ENTRYPOINT</filename> variable is used | ||
16142 | in <filename>kernel-fitimage</filename> class to specify the | ||
16143 | entrypoint to be used in creating the Image Tree Source for | ||
16144 | the FIT image. | ||
16145 | </para> | ||
16146 | </glossdef> | ||
16147 | </glossentry> | ||
16148 | |||
16013 | <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> | 16149 | <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> |
16014 | <info> | 16150 | <info> |
16015 | UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension." | 16151 | UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension." |
@@ -16028,6 +16164,47 @@ | |||
16028 | </glossdef> | 16164 | </glossdef> |
16029 | </glossentry> | 16165 | </glossentry> |
16030 | 16166 | ||
16167 | <glossentry id='var-UBOOT_SIGN_ENABLE'><glossterm>UBOOT_SIGN_ENABLE</glossterm> | ||
16168 | <info> | ||
16169 | UBOOT_SIGN_KEYDIR[doc] = "Enable signing of FIT image." | ||
16170 | </info> | ||
16171 | <glossdef> | ||
16172 | <para role="glossdeffirst"> | ||
16173 | Enable signing of FIT image. The default value is "0". | ||
16174 | </para> | ||
16175 | </glossdef> | ||
16176 | </glossentry> | ||
16177 | |||
16178 | <glossentry id='var-UBOOT_SIGN_KEYDIR'><glossterm>UBOOT_SIGN_KEYDIR</glossterm> | ||
16179 | <info> | ||
16180 | UBOOT_SIGN_KEYDIR[doc] = "Location of the directory containing the RSA key and certificate used for signing FIT image." | ||
16181 | </info> | ||
16182 | <glossdef> | ||
16183 | <para role="glossdeffirst"> | ||
16184 | Location of the directory containing the RSA key and | ||
16185 | certificate used for signing FIT image. | ||
16186 | </para> | ||
16187 | </glossdef> | ||
16188 | </glossentry> | ||
16189 | |||
16190 | <glossentry id='var-UBOOT_SIGN_KEYNAME'><glossterm>UBOOT_SIGN_KEYNAME</glossterm> | ||
16191 | <info> | ||
16192 | UBOOT_SIGN_KEYNAME[doc] = "The name of keys used for signing U-boot FIT image" | ||
16193 | </info> | ||
16194 | <glossdef> | ||
16195 | <para role="glossdeffirst"> | ||
16196 | The name of keys used for signing U-boot FIT image stored in | ||
16197 | <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> | ||
16198 | directory. For e.g. dev.key key and dev.crt certificate | ||
16199 | stored in | ||
16200 | <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename> | ||
16201 | directory will have | ||
16202 | <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename> | ||
16203 | set to "dev". | ||
16204 | </para> | ||
16205 | </glossdef> | ||
16206 | </glossentry> | ||
16207 | |||
16031 | <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> | 16208 | <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> |
16032 | <info> | 16209 | <info> |
16033 | UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot." | 16210 | UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot." |
diff --git a/documentation/ref-manual/ref-varlocality.rst b/documentation/ref-manual/ref-varlocality.rst new file mode 100644 index 0000000000..a95504b571 --- /dev/null +++ b/documentation/ref-manual/ref-varlocality.rst | |||
@@ -0,0 +1,166 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | **************** | ||
4 | Variable Context | ||
5 | **************** | ||
6 | |||
7 | While you can use most variables in almost any context such as | ||
8 | ``.conf``, ``.bbclass``, ``.inc``, and ``.bb`` files, some variables are | ||
9 | often associated with a particular locality or context. This chapter | ||
10 | describes some common associations. | ||
11 | |||
12 | .. _ref-varlocality-configuration: | ||
13 | |||
14 | Configuration | ||
15 | ============= | ||
16 | |||
17 | The following subsections provide lists of variables whose context is | ||
18 | configuration: distribution, machine, and local. | ||
19 | |||
20 | .. _ref-varlocality-config-distro: | ||
21 | |||
22 | Distribution (Distro) | ||
23 | --------------------- | ||
24 | |||
25 | This section lists variables whose configuration context is the | ||
26 | distribution, or distro. | ||
27 | |||
28 | - :term:`DISTRO` | ||
29 | |||
30 | - :term:`DISTRO_NAME` | ||
31 | |||
32 | - :term:`DISTRO_VERSION` | ||
33 | |||
34 | - :term:`MAINTAINER` | ||
35 | |||
36 | - :term:`PACKAGE_CLASSES` | ||
37 | |||
38 | - :term:`TARGET_OS` | ||
39 | |||
40 | - :term:`TARGET_FPU` | ||
41 | |||
42 | - :term:`TCMODE` | ||
43 | |||
44 | - :term:`TCLIBC` | ||
45 | |||
46 | .. _ref-varlocality-config-machine: | ||
47 | |||
48 | Machine | ||
49 | ------- | ||
50 | |||
51 | This section lists variables whose configuration context is the machine. | ||
52 | |||
53 | - :term:`TARGET_ARCH` | ||
54 | |||
55 | - :term:`SERIAL_CONSOLES` | ||
56 | |||
57 | - :term:`PACKAGE_EXTRA_ARCHS` | ||
58 | |||
59 | - :term:`IMAGE_FSTYPES` | ||
60 | |||
61 | - :term:`MACHINE_FEATURES` | ||
62 | |||
63 | - :term:`MACHINE_EXTRA_RDEPENDS` | ||
64 | |||
65 | - :term:`MACHINE_EXTRA_RRECOMMENDS` | ||
66 | |||
67 | - :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` | ||
68 | |||
69 | - :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | ||
70 | |||
71 | .. _ref-varlocality-config-local: | ||
72 | |||
73 | Local | ||
74 | ----- | ||
75 | |||
76 | This section lists variables whose configuration context is the local | ||
77 | configuration through the ``local.conf`` file. | ||
78 | |||
79 | - :term:`DISTRO` | ||
80 | |||
81 | - :term:`MACHINE` | ||
82 | |||
83 | - :term:`DL_DIR` | ||
84 | |||
85 | - :term:`BBFILES` | ||
86 | |||
87 | - :term:`EXTRA_IMAGE_FEATURES` | ||
88 | |||
89 | - :term:`PACKAGE_CLASSES` | ||
90 | |||
91 | - :term:`BB_NUMBER_THREADS` | ||
92 | |||
93 | - :term:`BBINCLUDELOGS` | ||
94 | |||
95 | - :term:`ENABLE_BINARY_LOCALE_GENERATION` | ||
96 | |||
97 | .. _ref-varlocality-recipes: | ||
98 | |||
99 | Recipes | ||
100 | ======= | ||
101 | |||
102 | The following subsections provide lists of variables whose context is | ||
103 | recipes: required, dependencies, path, and extra build information. | ||
104 | |||
105 | .. _ref-varlocality-recipe-required: | ||
106 | |||
107 | Required | ||
108 | -------- | ||
109 | |||
110 | This section lists variables that are required for recipes. | ||
111 | |||
112 | - :term:`LICENSE` | ||
113 | |||
114 | - :term:`LIC_FILES_CHKSUM` | ||
115 | |||
116 | - :term:`SRC_URI` - used in recipes that fetch local or remote files. | ||
117 | |||
118 | .. _ref-varlocality-recipe-dependencies: | ||
119 | |||
120 | Dependencies | ||
121 | ------------ | ||
122 | |||
123 | This section lists variables that define recipe dependencies. | ||
124 | |||
125 | - :term:`DEPENDS` | ||
126 | |||
127 | - :term:`RDEPENDS` | ||
128 | |||
129 | - :term:`RRECOMMENDS` | ||
130 | |||
131 | - :term:`RCONFLICTS` | ||
132 | |||
133 | - :term:`RREPLACES` | ||
134 | |||
135 | .. _ref-varlocality-recipe-paths: | ||
136 | |||
137 | Paths | ||
138 | ----- | ||
139 | |||
140 | This section lists variables that define recipe paths. | ||
141 | |||
142 | - :term:`WORKDIR` | ||
143 | |||
144 | - :term:`S` | ||
145 | |||
146 | - :term:`FILES` | ||
147 | |||
148 | .. _ref-varlocality-recipe-build: | ||
149 | |||
150 | Extra Build Information | ||
151 | ----------------------- | ||
152 | |||
153 | This section lists variables that define extra build information for | ||
154 | recipes. | ||
155 | |||
156 | - :term:`DEFAULT_PREFERENCE` | ||
157 | |||
158 | - :term:`EXTRA_OECMAKE` | ||
159 | |||
160 | - :term:`EXTRA_OECONF` | ||
161 | |||
162 | - :term:`EXTRA_OEMAKE` | ||
163 | |||
164 | - :term:`PACKAGECONFIG_CONFARGS` | ||
165 | |||
166 | - :term:`PACKAGES` | ||
diff --git a/documentation/ref-manual/ref-varlocality.xml b/documentation/ref-manual/ref-varlocality.xml index 54524d5b60..a2436fb310 100644 --- a/documentation/ref-manual/ref-varlocality.xml +++ b/documentation/ref-manual/ref-varlocality.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='ref-varlocality'> | 6 | <chapter id='ref-varlocality'> |
6 | <title>Variable Context</title> | 7 | <title>Variable Context</title> |
diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst new file mode 100644 index 0000000000..2b82b79102 --- /dev/null +++ b/documentation/ref-manual/resources.rst | |||
@@ -0,0 +1,197 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-2.0-UK | ||
2 | |||
3 | **************************************** | ||
4 | Contributions and Additional Information | ||
5 | **************************************** | ||
6 | |||
7 | .. _resources-intro: | ||
8 | |||
9 | Introduction | ||
10 | ============ | ||
11 | |||
12 | The Yocto Project team is happy for people to experiment with the Yocto | ||
13 | Project. A number of places exist to find help if you run into | ||
14 | difficulties or find bugs. This presents information about contributing | ||
15 | and participating in the Yocto Project. | ||
16 | |||
17 | .. _resources-contributions: | ||
18 | |||
19 | Contributions | ||
20 | ============= | ||
21 | |||
22 | The Yocto Project gladly accepts contributions. You can submit changes | ||
23 | to the project either by creating and sending pull requests, or by | ||
24 | submitting patches through email. For information on how to do both as | ||
25 | well as information on how to identify the maintainer for each area of | ||
26 | code, see the ":ref:`how-to-submit-a-change`" section in the | ||
27 | Yocto Project Development Tasks Manual. | ||
28 | |||
29 | .. _resources-bugtracker: | ||
30 | |||
31 | Yocto Project Bugzilla | ||
32 | ====================== | ||
33 | |||
34 | The Yocto Project uses its own implementation of | ||
35 | :yocto_bugs:`Bugzilla <>` to track defects (bugs). | ||
36 | Implementations of Bugzilla work well for group development because they | ||
37 | track bugs and code changes, can be used to communicate changes and | ||
38 | problems with developers, can be used to submit and review patches, and | ||
39 | can be used to manage quality assurance. | ||
40 | |||
41 | Sometimes it is helpful to submit, investigate, or track a bug against | ||
42 | the Yocto Project itself (e.g. when discovering an issue with some | ||
43 | component of the build system that acts contrary to the documentation or | ||
44 | your expectations). | ||
45 | |||
46 | A general procedure and guidelines exist for when you use Bugzilla to | ||
47 | submit a bug. For information on how to use Bugzilla to submit a bug | ||
48 | against the Yocto Project, see the following: | ||
49 | |||
50 | - The ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`" | ||
51 | section in the Yocto Project Development Tasks Manual. | ||
52 | |||
53 | - The Yocto Project :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>` | ||
54 | |||
55 | For information on Bugzilla in general, see http://www.bugzilla.org/about/. | ||
56 | |||
57 | .. _resources-mailinglist: | ||
58 | |||
59 | Mailing lists | ||
60 | ============= | ||
61 | |||
62 | A number of mailing lists maintained by the Yocto Project exist as well | ||
63 | as related OpenEmbedded mailing lists for discussion, patch submission | ||
64 | and announcements. To subscribe to one of the following mailing lists, | ||
65 | click on the appropriate URL in the following list and follow the | ||
66 | instructions: | ||
67 | |||
68 | - https://lists.yoctoproject.org/g/yocto - General Yocto Project | ||
69 | discussion mailing list. | ||
70 | |||
71 | - https://lists.openembedded.org/g/openembedded-core - Discussion mailing | ||
72 | list about OpenEmbedded-Core (the core metadata). | ||
73 | |||
74 | - https://lists.openembedded.org/g/openembedded-devel - Discussion | ||
75 | mailing list about OpenEmbedded. | ||
76 | |||
77 | - https://lists.openembedded.org/g/bitbake-devel - Discussion mailing | ||
78 | list about the :term:`BitBake` build tool. | ||
79 | |||
80 | - https://lists.yoctoproject.org/g/poky - Discussion mailing list | ||
81 | about `Poky <#poky>`__. | ||
82 | |||
83 | - https://lists.yoctoproject.org/g/yocto-announce - Mailing list to | ||
84 | receive official Yocto Project release and milestone announcements. | ||
85 | |||
86 | For more Yocto Project-related mailing lists, see the | ||
87 | Yocto Project Website | ||
88 | . | ||
89 | .. _resources-irc: | ||
90 | |||
91 | Internet Relay Chat (IRC) | ||
92 | ========================= | ||
93 | |||
94 | Two IRC channels on freenode are available for the Yocto Project and | ||
95 | Poky discussions: | ||
96 | |||
97 | - ``#yocto`` | ||
98 | |||
99 | - ``#poky`` | ||
100 | |||
101 | .. _resources-links-and-related-documentation: | ||
102 | |||
103 | Links and Related Documentation | ||
104 | =============================== | ||
105 | |||
106 | Here is a list of resources you might find helpful: | ||
107 | |||
108 | - :yocto_home:`The Yocto Project Website <>`\ *:* The home site | ||
109 | for the Yocto Project. | ||
110 | |||
111 | - :yocto_wiki:`The Yocto Project Main Wiki Page </wiki/Main_Page>`\ *:* The main wiki page for | ||
112 | the Yocto Project. This page contains information about project | ||
113 | planning, release engineering, QA & automation, a reference site map, | ||
114 | and other resources related to the Yocto Project. | ||
115 | |||
116 | - `OpenEmbedded <http://www.openembedded.org/>`__\ *:* The build system used by the | ||
117 | Yocto Project. This project is the upstream, generic, embedded | ||
118 | distribution from which the Yocto Project derives its build system | ||
119 | (Poky) and to which it contributes. | ||
120 | |||
121 | - `BitBake <http://www.openembedded.org/wiki/BitBake>`__\ *:* The tool | ||
122 | used to process metadata. | ||
123 | |||
124 | - :doc:`BitBake User Manual <bitbake:index>`\ *:* A comprehensive | ||
125 | guide to the BitBake tool. If you want information on BitBake, see | ||
126 | this manual. | ||
127 | |||
128 | - :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` *:* This | ||
129 | short document lets you experience building an image using the Yocto | ||
130 | Project without having to understand any concepts or details. | ||
131 | |||
132 | - :doc:`../overview-manual/overview-manual` *:* This manual provides overview | ||
133 | and conceptual information about the Yocto Project. | ||
134 | |||
135 | - :doc:`../dev-manual/dev-manual` *:* This manual is a "how-to" guide | ||
136 | that presents procedures useful to both application and system | ||
137 | developers who use the Yocto Project. | ||
138 | |||
139 | - :doc:`../sdk-manual/sdk-manual` *manual :* This | ||
140 | guide provides information that lets you get going with the standard | ||
141 | or extensible SDK. An SDK, with its cross-development toolchains, | ||
142 | allows you to develop projects inside or outside of the Yocto Project | ||
143 | environment. | ||
144 | |||
145 | - :doc:`../bsp-guide/bsp` *:* This guide defines the structure | ||
146 | for BSP components. Having a commonly understood structure encourages | ||
147 | standardization. | ||
148 | |||
149 | - :doc:`../kernel-dev/kernel-dev` *:* This manual describes | ||
150 | how to work with Linux Yocto kernels as well as provides a bit of | ||
151 | conceptual information on the construction of the Yocto Linux kernel | ||
152 | tree. | ||
153 | |||
154 | - :doc:`../ref-manual/ref-manual` *:* This | ||
155 | manual provides reference material such as variable, task, and class | ||
156 | descriptions. | ||
157 | |||
158 | - `Yocto Project Mega-Manual <https://docs.yoctoproject.org/singleindex.html>`__\ *:* This manual | ||
159 | is simply a single HTML file comprised of the bulk of the Yocto | ||
160 | Project manuals. The Mega-Manual primarily exists as a vehicle by | ||
161 | which you can easily search for phrases and terms used in the Yocto | ||
162 | Project documentation set. | ||
163 | |||
164 | - :doc:`../profile-manual/profile-manual` *:* This manual presents a set of | ||
165 | common and generally useful tracing and profiling schemes along with | ||
166 | their applications (as appropriate) to each tool. | ||
167 | |||
168 | - :doc:`../toaster-manual/toaster-manual` *:* This manual | ||
169 | introduces and describes how to set up and use Toaster. Toaster is an | ||
170 | Application Programming Interface (API) and web-based interface to | ||
171 | the :term:`OpenEmbedded Build System`, which uses | ||
172 | BitBake, that reports build information. | ||
173 | |||
174 | - :yocto_wiki:`FAQ </wiki/FAQ>`\ *:* A list of commonly asked | ||
175 | questions and their answers. | ||
176 | |||
177 | - *Release Notes:* Features, updates and known issues for the current | ||
178 | release of the Yocto Project. To access the Release Notes, go to the | ||
179 | :yocto_home:`Downloads </software-overview/downloads>` page on | ||
180 | the Yocto Project website and click on the "RELEASE INFORMATION" link | ||
181 | for the appropriate release. | ||
182 | |||
183 | - `Bugzilla <https://bugzilla.yoctoproject.org>`__\ *:* The bug tracking application | ||
184 | the Yocto Project uses. If you find problems with the Yocto Project, | ||
185 | you should report them using this application. | ||
186 | |||
187 | - :yocto_wiki:`Bugzilla Configuration and Bug Tracking Wiki Page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`\ *:* | ||
188 | Information on how to get set up and use the Yocto Project | ||
189 | implementation of Bugzilla for logging and tracking Yocto Project | ||
190 | defects. | ||
191 | |||
192 | - *Internet Relay Chat (IRC):* Two IRC channels on freenode are | ||
193 | available for Yocto Project and Poky discussions: ``#yocto`` and | ||
194 | ``#poky``, respectively. | ||
195 | |||
196 | - `Quick EMUlator (QEMU) <http://wiki.qemu.org/Index.html>`__\ *:* An | ||
197 | open-source machine emulator and virtualizer. | ||
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml index afe8e288de..4899b2e599 100644 --- a/documentation/ref-manual/resources.xml +++ b/documentation/ref-manual/resources.xml | |||
@@ -1,6 +1,7 @@ | |||
1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
4 | <!--SPDX-License-Identifier: CC-BY-2.0-UK--> | ||
4 | 5 | ||
5 | <chapter id='resources'> | 6 | <chapter id='resources'> |
6 | <title>Contributions and Additional Information</title> | 7 | <title>Contributions and Additional Information</title> |