summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/faq.xml836
-rw-r--r--documentation/ref-manual/migration.xml7301
-rw-r--r--documentation/ref-manual/ref-classes.xml3974
-rw-r--r--documentation/ref-manual/ref-devtool-reference.xml842
-rw-r--r--documentation/ref-manual/ref-features.xml461
-rw-r--r--documentation/ref-manual/ref-images.xml170
-rw-r--r--documentation/ref-manual/ref-kickstart.xml335
-rw-r--r--documentation/ref-manual/ref-manual-customization.xsl31
-rwxr-xr-xdocumentation/ref-manual/ref-manual.xml232
-rw-r--r--documentation/ref-manual/ref-qa-checks.xml1225
-rw-r--r--documentation/ref-manual/ref-release-process.xml256
-rw-r--r--documentation/ref-manual/ref-structure.xml1123
-rw-r--r--documentation/ref-manual/ref-style.css1035
-rw-r--r--documentation/ref-manual/ref-system-requirements.xml577
-rw-r--r--documentation/ref-manual/ref-tasks.xml1131
-rw-r--r--documentation/ref-manual/ref-terms.xml525
-rw-r--r--documentation/ref-manual/ref-variables.xml16877
-rw-r--r--documentation/ref-manual/ref-varlocality.xml199
-rw-r--r--documentation/ref-manual/resources.xml298
19 files changed, 0 insertions, 37428 deletions
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
deleted file mode 100644
index 2f8fcf3242..0000000000
--- a/documentation/ref-manual/faq.xml
+++ /dev/null
@@ -1,836 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='faq'>
7<title>FAQ</title>
8<qandaset>
9 <qandaentry>
10 <question>
11 <para>
12 How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
13 </para>
14 </question>
15 <answer>
16 <para>
17 The term "<link link='poky'>Poky</link>"
18 refers to the specific reference build system that
19 the Yocto Project provides.
20 Poky is based on <link linkend='oe-core'>OE-Core</link>
21 and <link linkend='bitbake-term'>BitBake</link>.
22 Thus, the generic term used here for the build system is
23 the "OpenEmbedded build system."
24 Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
25 changes always being merged to OE-Core or BitBake first before being pulled back
26 into Poky.
27 This practice benefits both projects immediately.
28 </para>
29 </answer>
30 </qandaentry>
31
32 <qandaentry>
33 <question>
34 <para id='faq-not-meeting-requirements'>
35 My development system does not meet the
36 required Git, tar, and Python versions.
37 In particular, I do not have Python 3.5.0 or greater.
38 Can I still use the Yocto Project?
39 </para>
40 </question>
41 <answer>
42 <para>
43 You can get the required tools on your host development
44 system a couple different ways (i.e. building a tarball or
45 downloading a tarball).
46 See the
47 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
48 section for steps on how to update your build tools.
49 </para>
50 </answer>
51 </qandaentry>
52
53 <qandaentry>
54 <question>
55 <para>
56 How can you claim Poky / OpenEmbedded-Core is stable?
57 </para>
58 </question>
59 <answer>
60 <para>
61 There are three areas that help with stability;
62 <itemizedlist>
63 <listitem><para>The Yocto Project team keeps
64 <link linkend='oe-core'>OE-Core</link> small
65 and focused, containing around 830 recipes as opposed to the thousands
66 available in other OpenEmbedded community layers.
67 Keeping it small makes it easy to test and maintain.</para></listitem>
68 <listitem><para>The Yocto Project team runs manual and automated tests
69 using a small, fixed set of reference hardware as well as emulated
70 targets.</para></listitem>
71 <listitem><para>The Yocto Project uses an autobuilder,
72 which provides continuous build and integration tests.</para></listitem>
73 </itemizedlist>
74 </para>
75 </answer>
76 </qandaentry>
77
78 <qandaentry>
79 <question>
80 <para>
81 How do I get support for my board added to the Yocto Project?
82 </para>
83 </question>
84 <answer>
85 <para>
86 Support for an additional board is added by creating a
87 Board Support Package (BSP) layer for it.
88 For more information on how to create a BSP layer, see the
89 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
90 section in the Yocto Project Development Tasks Manual and the
91 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
92 </para>
93 <para>
94 Usually, if the board is not completely exotic, adding support in
95 the Yocto Project is fairly straightforward.
96 </para>
97 </answer>
98 </qandaentry>
99
100 <qandaentry>
101 <question>
102 <para>
103 Are there any products built using the OpenEmbedded build system?
104 </para>
105 </question>
106 <answer>
107 <para>
108 The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
109 is built using the OpenEmbedded build system.
110 See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
111 website for more information.
112 There are a number of pre-production devices using the OpenEmbedded build system
113 and the Yocto Project team
114 announces them as soon as they are released.
115 </para>
116 </answer>
117 </qandaentry>
118
119 <qandaentry>
120 <question>
121 <para>
122 What does the OpenEmbedded build system produce as output?
123 </para>
124 </question>
125 <answer>
126 <para>
127 Because you can use the same set of recipes to create output of
128 various formats, the output of an OpenEmbedded build depends on
129 how you start it.
130 Usually, the output is a flashable image ready for the target
131 device.
132 </para>
133 </answer>
134 </qandaentry>
135
136 <qandaentry>
137 <question>
138 <para>
139 How do I add my package to the Yocto Project?
140 </para>
141 </question>
142 <answer>
143 <para>
144 To add a package, you need to create a BitBake recipe.
145 For information on how to create a BitBake recipe, see the
146 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe'>Writing a New Recipe</ulink>"
147 section in the Yocto Project Development Tasks Manual.
148 </para>
149 </answer>
150 </qandaentry>
151
152 <qandaentry>
153 <question>
154 <para>
155 Do I have to reflash my entire board with a new Yocto Project image when recompiling
156 a package?
157 </para>
158 </question>
159 <answer>
160 <para>
161 The OpenEmbedded build system can build packages in various
162 formats such as IPK for OPKG, Debian package
163 (<filename>.deb</filename>), or RPM.
164 You can then upgrade the packages using the package tools on
165 the device, much like on a desktop distribution such as
166 Ubuntu or Fedora.
167 However, package management on the target is entirely optional.
168 </para>
169 </answer>
170 </qandaentry>
171
172 <qandaentry>
173 <question>
174 <para>
175 I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
176 What is wrong?
177 </para>
178 </question>
179 <answer>
180 <para>
181 You are probably running the build on an NTFS filesystem.
182 Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
183 </para>
184 </answer>
185 </qandaentry>
186
187<!-- <qandaentry>
188 <question>
189 <para>
190 How do I make the Yocto Project work in RHEL/CentOS?
191 </para>
192 </question>
193 <answer>
194 <para>
195 To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
196 install some required packages.
197 The standard CentOS packages needed are:
198 <itemizedlist>
199 <listitem><para>"Development tools" (selected during installation)</para></listitem>
200 <listitem><para><filename>texi2html</filename></para></listitem>
201 <listitem><para><filename>compat-gcc-34</filename></para></listitem>
202 </itemizedlist>
203 On top of these, you need the following external packages:
204 <itemizedlist>
205 <listitem><para><filename>python-sqlite2</filename> from
206 <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
207 </para></listitem>
208 <listitem><para><filename>help2man</filename> from
209 <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem>
210 </itemizedlist>
211 </para>
212
213 <para>
214 Once these packages are installed, the OpenEmbedded build system will be able
215 to build standard images.
216 However, there might be a problem with the QEMU emulator segfaulting.
217 You can either disable the generation of binary locales by setting
218 <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
219 </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
220 from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
221 </para>
222
223 <note>
224 <para>For information on distributions that the Yocto Project
225 uses during validation, see the
226 <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>
227 Wiki page.</para>
228 <para>For notes about using the Yocto Project on a RHEL 4-based
229 host, see the
230 <ulink url='&YOCTO_WIKI_URL;/wiki/BuildingOnRHEL4'>Building on RHEL4</ulink>
231 Wiki page.</para>
232 </note>
233 </answer>
234 </qandaentry> -->
235
236 <qandaentry>
237 <question>
238 <para>
239 I see lots of 404 responses for files when the OpenEmbedded
240 build system is trying to download sources.
241 Is something wrong?
242 </para>
243 </question>
244 <answer>
245 <para>
246 Nothing is wrong.
247 The OpenEmbedded build system checks any configured source mirrors before downloading
248 from the upstream sources.
249 The build system does this searching for both source archives and
250 pre-checked out versions of SCM-managed software.
251 These checks help in large installations because it can reduce load on the SCM servers
252 themselves.
253 The address above is one of the default mirrors configured into the
254 build system.
255 Consequently, if an upstream source disappears, the team
256 can place sources there so builds continue to work.
257 </para>
258 </answer>
259 </qandaentry>
260
261 <qandaentry>
262 <question>
263 <para>
264 I have machine-specific data in a package for one machine only but the package is
265 being marked as machine-specific in all cases, how do I prevent this?
266 </para>
267 </question>
268 <answer>
269 <para>
270 Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
271 </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
272 manually marked as
273 machine-specific for the case that needs it.
274 The code that handles
275 <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in
276 the <filename>meta/classes/base.bbclass</filename> file.
277 </para>
278 </answer>
279 </qandaentry>
280
281 <qandaentry>
282 <question>
283 <para id='i-am-behind-a-firewall-and-need-to-use-a-proxy-server'>
284 I'm behind a firewall and need to use a proxy server. How do I do that?
285 </para>
286 </question>
287 <answer>
288 <para>
289 Most source fetching by the OpenEmbedded build system is done
290 by <filename>wget</filename> and you therefore need to specify
291 the proxy settings in a <filename>.wgetrc</filename> file,
292 which can be in your home directory if you are a single user
293 or can be in <filename>/usr/local/etc/wgetrc</filename> as
294 a global user file.
295 </para>
296
297 <para>
298 Following is the applicable code for setting various proxy
299 types in the <filename>.wgetrc</filename> file.
300 By default, these settings are disabled with comments.
301 To use them, remove the comments:
302 <literallayout class='monospaced'>
303 # You can set the default proxies for Wget to use for http, https, and ftp.
304 # They will override the value in the environment.
305 #https_proxy = http://proxy.yoyodyne.com:18023/
306 #http_proxy = http://proxy.yoyodyne.com:18023/
307 #ftp_proxy = http://proxy.yoyodyne.com:18023/
308
309 # If you do not want to use proxy at all, set this to off.
310 #use_proxy = on
311 </literallayout>
312 The Yocto Project also includes a
313 <filename>meta-poky/conf/site.conf.sample</filename> file that
314 shows how to configure CVS and Git proxy servers if needed.
315 For more information on setting up various proxy types and
316 configuring proxy servers, see the
317 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
318 Wiki page.
319 </para>
320 </answer>
321 </qandaentry>
322
323 <qandaentry>
324 <question>
325 <para>
326 What's the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>?
327 </para>
328 </question>
329 <answer>
330 <para>
331 The <filename>*-native</filename> targets are designed to run on the system
332 being used for the build.
333 These are usually tools that are needed to assist the build in some way such as
334 <filename>quilt-native</filename>, which is used to apply patches.
335 The non-native version is the one that runs on the target device.
336 </para>
337 </answer>
338 </qandaentry>
339
340 <qandaentry>
341 <question>
342 <para>
343 I'm seeing random build failures. Help?!
344 </para>
345 </question>
346 <answer>
347 <para>
348 If the same build is failing in totally different and random
349 ways, the most likely explanation is:
350 <itemizedlist>
351 <listitem><para>The hardware you are running the build on
352 has some problem.</para></listitem>
353 <listitem><para>You are running the build under
354 virtualization, in which case the virtualization
355 probably has bugs.</para></listitem>
356 </itemizedlist>
357 The OpenEmbedded build system processes a massive amount of
358 data that causes lots of network, disk and CPU activity and
359 is sensitive to even single-bit failures in any of these areas.
360 True random failures have always been traced back to hardware
361 or virtualization issues.
362 </para>
363 </answer>
364 </qandaentry>
365
366 <qandaentry>
367 <question>
368 <para>
369 When I try to build a native recipe, the build fails with <filename>iconv.h</filename> problems.
370 </para>
371 </question>
372 <answer>
373 <para>
374 If you get an error message that indicates GNU
375 <filename>libiconv</filename> is not in use but
376 <filename>iconv.h</filename> has been included from
377 <filename>libiconv</filename>, you need to check to see if
378 you have a previously installed version of the header file
379 in <filename>/usr/local/include</filename>.
380 <literallayout class='monospaced'>
381 #error GNU libiconv not in use but included iconv.h is from libiconv
382 </literallayout>
383 If you find a previously installed file, you should either
384 uninstall it or temporarily rename it and try the build again.
385 </para>
386
387 <para>
388 This issue is just a single manifestation of "system
389 leakage" issues caused when the OpenEmbedded build system
390 finds and uses previously installed files during a native
391 build.
392 This type of issue might not be limited to
393 <filename>iconv.h</filename>.
394 Be sure that leakage cannot occur from
395 <filename>/usr/local/include</filename> and
396 <filename>/opt</filename> locations.
397 </para>
398 </answer>
399 </qandaentry>
400
401 <qandaentry>
402 <question>
403 <para>
404 What do we need to ship for license compliance?
405 </para>
406 </question>
407 <answer>
408 <para>
409 This is a difficult question and you need to consult your lawyer
410 for the answer for your specific case.
411 It is worth bearing in mind that for GPL compliance, there needs
412 to be enough information shipped to allow someone else to
413 rebuild and produce the same end result you are shipping.
414 This means sharing the source code, any patches applied to it,
415 and also any configuration information about how that package
416 was configured and built.
417 </para>
418
419 <para>
420 You can find more information on licensing in the
421 "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"
422 section in the Yocto Project Overview and Concepts Manual
423 and also in the
424 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
425 section in the Yocto Project Development Tasks Manual.
426 </para>
427 </answer>
428 </qandaentry>
429
430 <qandaentry>
431 <question>
432 <para>
433 How do I disable the cursor on my touchscreen device?
434 </para>
435 </question>
436 <answer>
437 <para>
438 You need to create a form factor file as described in the
439 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
440 section in the Yocto Project Board Support Packages (BSP)
441 Developer's Guide.
442 Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to
443 one as follows:
444 <literallayout class='monospaced'>
445 HAVE_TOUCHSCREEN=1
446 </literallayout>
447 </para>
448 </answer>
449 </qandaentry>
450
451 <qandaentry>
452 <question>
453 <para>
454 How do I make sure connected network interfaces are brought up by default?
455 </para>
456 </question>
457 <answer>
458 <para>
459 The default interfaces file provided by the netbase recipe does not
460 automatically bring up network interfaces.
461 Therefore, you will need to add a BSP-specific netbase that includes an interfaces
462 file.
463 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
464 section in the Yocto Project Board Support Packages (BSP)
465 Developer's Guide for information on creating these types of
466 miscellaneous recipe files.
467 </para>
468 <para>
469 For example, add the following files to your layer:
470 <literallayout class='monospaced'>
471 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
472 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
473 </literallayout>
474 </para>
475 </answer>
476 </qandaentry>
477
478 <qandaentry>
479 <question>
480 <para>
481 How do I create images with more free space?
482 </para>
483 </question>
484 <answer>
485 <para>
486 By default, the OpenEmbedded build system creates images
487 that are 1.3 times the size of the populated root filesystem.
488 To affect the image size, you need to set various
489 configurations:
490 <itemizedlist>
491 <listitem><para><emphasis>Image Size:</emphasis>
492 The OpenEmbedded build system uses the
493 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
494 variable to define the size of the image in Kbytes.
495 The build system determines the size by taking into
496 account the initial root filesystem size before any
497 modifications such as requested size for the image and
498 any requested additional free disk space to be
499 added to the image.</para></listitem>
500 <listitem><para><emphasis>Overhead:</emphasis>
501 Use the
502 <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
503 variable to define the multiplier that the build system
504 applies to the initial image size, which is 1.3 by
505 default.</para></listitem>
506 <listitem><para><emphasis>Additional Free Space:</emphasis>
507 Use the
508 <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
509 variable to add additional free space to the image.
510 The build system adds this space to the image after
511 it determines its
512 <filename>IMAGE_ROOTFS_SIZE</filename>.
513 </para></listitem>
514 </itemizedlist>
515 </para>
516 </answer>
517 </qandaentry>
518
519 <qandaentry>
520 <question>
521 <para>
522 Why don't you support directories with spaces in the pathnames?
523 </para>
524 </question>
525 <answer>
526 <para>
527 The Yocto Project team has tried to do this before but too
528 many of the tools the OpenEmbedded build system depends on,
529 such as <filename>autoconf</filename>, break when they find
530 spaces in pathnames.
531 Until that situation changes, the team will not support spaces
532 in pathnames.
533 </para>
534 </answer>
535 </qandaentry>
536
537 <qandaentry>
538 <question>
539 <para>
540 How do I use an external toolchain?
541 </para>
542 </question>
543 <answer>
544 <para>
545 The toolchain configuration is very flexible and customizable.
546 It is primarily controlled with the
547 <filename><link linkend='var-TCMODE'>TCMODE</link></filename>
548 variable.
549 This variable controls which <filename>tcmode-*.inc</filename>
550 file to include from the
551 <filename>meta/conf/distro/include</filename> directory within
552 the
553 <link linkend='source-directory'>Source Directory</link>.
554 </para>
555
556 <para>
557 The default value of <filename>TCMODE</filename> is "default",
558 which tells the OpenEmbedded build system to use its internally
559 built toolchain (i.e. <filename>tcmode-default.inc</filename>).
560 However, other patterns are accepted.
561 In particular, "external-*" refers to external toolchains.
562 One example is the Sourcery G++ Toolchain.
563 The support for this toolchain resides in the separate
564 <filename>meta-sourcery</filename> layer at
565 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
566 </para>
567
568 <para>
569 In addition to the toolchain configuration, you also need a
570 corresponding toolchain recipe file.
571 This recipe file needs to package up any pre-built objects in
572 the toolchain such as <filename>libgcc</filename>,
573 <filename>libstdcc++</filename>, any locales, and
574 <filename>libc</filename>.
575 </para>
576 </answer>
577 </qandaentry>
578
579 <qandaentry>
580 <question>
581 <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
582 How does the OpenEmbedded build system obtain source code and
583 will it work behind my firewall or proxy server?
584 </para>
585 </question>
586 <answer>
587 <para>
588 The way the build system obtains source code is highly
589 configurable.
590 You can setup the build system to get source code in most
591 environments if HTTP transport is available.
592 </para>
593 <para>
594 When the build system searches for source code, it first
595 tries the local download directory.
596 If that location fails, Poky tries
597 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
598 the upstream source, and then
599 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
600 in that order.
601 </para>
602 <para>
603 Assuming your distribution is "poky", the OpenEmbedded build
604 system uses the Yocto Project source
605 <filename>PREMIRRORS</filename> by default for SCM-based
606 sources, upstreams for normal tarballs, and then falls back
607 to a number of other mirrors including the Yocto Project
608 source mirror if those fail.
609 </para>
610 <para>
611 As an example, you could add a specific server for the
612 build system to attempt before any others by adding something
613 like the following to the <filename>local.conf</filename>
614 configuration file:
615 <literallayout class='monospaced'>
616 PREMIRRORS_prepend = "\
617 git://.*/.* http://www.yoctoproject.org/sources/ \n \
618 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
619 http://.*/.* http://www.yoctoproject.org/sources/ \n \
620 https://.*/.* http://www.yoctoproject.org/sources/ \n"
621 </literallayout>
622 </para>
623 <para>
624 These changes cause the build system to intercept Git, FTP,
625 HTTP, and HTTPS requests and direct them to the
626 <filename>http://</filename> sources mirror.
627 You can use <filename>file://</filename> URLs to point to
628 local directories or network shares as well.
629 </para>
630 <para>
631 Aside from the previous technique, these options also exist:
632 <literallayout class='monospaced'>
633 BB_NO_NETWORK = "1"
634 </literallayout>
635 This statement tells BitBake to issue an error instead of
636 trying to access the Internet.
637 This technique is useful if you want to ensure code builds
638 only from local sources.
639 </para>
640 <para>
641 Here is another technique:
642 <literallayout class='monospaced'>
643 BB_FETCH_PREMIRRORONLY = "1"
644 </literallayout>
645 This statement limits the build system to pulling source
646 from the <filename>PREMIRRORS</filename> only.
647 Again, this technique is useful for reproducing builds.
648 </para>
649 <para>
650 Here is another technique:
651 <literallayout class='monospaced'>
652 BB_GENERATE_MIRROR_TARBALLS = "1"
653 </literallayout>
654 This statement tells the build system to generate mirror
655 tarballs.
656 This technique is useful if you want to create a mirror server.
657 If not, however, the technique can simply waste time during
658 the build.
659 </para>
660 <para>
661 Finally, consider an example where you are behind an
662 HTTP-only firewall.
663 You could make the following changes to the
664 <filename>local.conf</filename> configuration file as long as
665 the <filename>PREMIRRORS</filename> server is current:
666 <literallayout class='monospaced'>
667 PREMIRRORS_prepend = "\
668 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
669 http://.*/.* http://www.yoctoproject.org/sources/ \n \
670 https://.*/.* http://www.yoctoproject.org/sources/ \n"
671 BB_FETCH_PREMIRRORONLY = "1"
672 </literallayout>
673 These changes would cause the build system to successfully
674 fetch source over HTTP and any network accesses to anything
675 other than the <filename>PREMIRRORS</filename> would fail.
676 </para>
677 <para>
678 The build system also honors the standard shell environment
679 variables <filename>http_proxy</filename>,
680 <filename>ftp_proxy</filename>,
681 <filename>https_proxy</filename>, and
682 <filename>all_proxy</filename> to redirect requests through
683 proxy servers.
684 </para>
685 <note>
686 You can find more information on the
687 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
688 Wiki page.
689 </note>
690 </answer>
691 </qandaentry>
692
693 <qandaentry>
694 <question>
695 <para>
696 Can I get rid of build output so I can start over?
697 </para>
698 </question>
699 <answer>
700 <para>
701 Yes - you can easily do this.
702 When you use BitBake to build an image, all the build output
703 goes into the directory created when you run the
704 build environment setup script (i.e.
705 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
706 By default, this
707 <link linkend='build-directory'>Build Directory</link>
708 is named <filename>build</filename> but can be named
709 anything you want.
710 </para>
711
712 <para>
713 Within the Build Directory, is the <filename>tmp</filename>
714 directory.
715 To remove all the build output yet preserve any source code or
716 downloaded files from previous builds, simply remove the
717 <filename>tmp</filename> directory.
718 </para>
719 </answer>
720 </qandaentry>
721
722 <qandaentry>
723 <question>
724 <para>
725 Why do <filename>${bindir}</filename> and <filename>${libdir}</filename> have strange values for <filename>-native</filename> recipes?
726 </para>
727 </question>
728 <answer>
729 <para>
730 Executables and libraries might need to be used from a
731 directory other than the directory into which they were
732 initially installed.
733 Complicating this situation is the fact that sometimes these
734 executables and libraries are compiled with the expectation
735 of being run from that initial installation target directory.
736 If this is the case, moving them causes problems.
737 </para>
738
739 <para>
740 This scenario is a fundamental problem for package maintainers
741 of mainstream Linux distributions as well as for the
742 OpenEmbedded build system.
743 As such, a well-established solution exists.
744 Makefiles, Autotools configuration scripts, and other build
745 systems are expected to respect environment variables such as
746 <filename>bindir</filename>, <filename>libdir</filename>,
747 and <filename>sysconfdir</filename> that indicate where
748 executables, libraries, and data reside when a program is
749 actually run.
750 They are also expected to respect a
751 <filename>DESTDIR</filename> environment variable, which is
752 prepended to all the other variables when the build system
753 actually installs the files.
754 It is understood that the program does not actually run from
755 within <filename>DESTDIR</filename>.
756 </para>
757
758 <para>
759 When the OpenEmbedded build system uses a recipe to build a
760 target-architecture program (i.e. one that is intended for
761 inclusion on the image being built), that program eventually
762 runs from the root file system of that image.
763 Thus, the build system provides a value of "/usr/bin" for
764 <filename>bindir</filename>, a value of "/usr/lib" for
765 <filename>libdir</filename>, and so forth.
766 </para>
767
768 <para>
769 Meanwhile, <filename>DESTDIR</filename> is a path within the
770 <link linkend='build-directory'>Build Directory</link>.
771 However, when the recipe builds a native program (i.e. one
772 that is intended to run on the build machine), that program
773 is never installed directly to the build machine's root
774 file system.
775 Consequently, the build system uses paths within the Build
776 Directory for <filename>DESTDIR</filename>,
777 <filename>bindir</filename> and related variables.
778 To better understand this, consider the following two paths
779 where the first is relatively normal and the second is not:
780 <note>
781 Due to these lengthy examples, the paths are artificially
782 broken across lines for readability.
783 </note>
784 <literallayout class='monospaced'>
785 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
786 1.2.8-r0/sysroot-destdir/usr/bin
787
788 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
789 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
790 build/tmp/sysroots/x86_64-linux/usr/bin
791 </literallayout>
792 Even if the paths look unusual, they both are correct -
793 the first for a target and the second for a native recipe.
794 These paths are a consequence of the
795 <filename>DESTDIR</filename> mechanism and while they
796 appear strange, they are correct and in practice very effective.
797 </para>
798 </answer>
799 </qandaentry>
800
801 <qandaentry>
802 <question>
803 <para>
804 The files provided by my <filename>*-native</filename> recipe do
805 not appear to be available to other recipes.
806 Files are missing from the native sysroot, my recipe is
807 installing to the wrong place, or I am getting permissions
808 errors during the do_install task in my recipe! What is wrong?
809 </para>
810 </question>
811 <answer>
812 <para>
813 This situation results when a build system does
814 not recognize the environment variables supplied to it by
815 <link linkend='bitbake-term'>BitBake</link>.
816 The incident that prompted this FAQ entry involved a Makefile
817 that used an environment variable named
818 <filename>BINDIR</filename> instead of the more standard
819 variable <filename>bindir</filename>.
820 The makefile's hardcoded default value of "/usr/bin" worked
821 most of the time, but not for the recipe's
822 <filename>-native</filename> variant.
823 For another example, permissions errors might be caused
824 by a Makefile that ignores <filename>DESTDIR</filename> or uses
825 a different name for that environment variable.
826 Check the the build system to see if these kinds of
827 issues exist.
828 </para>
829 </answer>
830 </qandaentry>
831
832</qandaset>
833</chapter>
834<!--
835vim: expandtab tw=80 ts=4
836-->
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
deleted file mode 100644
index d3d5b16bdd..0000000000
--- a/documentation/ref-manual/migration.xml
+++ /dev/null
@@ -1,7301 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='migration'>
7<title>Migrating to a Newer Yocto Project Release</title>
8
9 <para>
10 This chapter provides information you can use to migrate work to a
11 newer Yocto Project release. You can find the same information in the
12 release notes for a given release.
13 </para>
14
15<section id='general-migration-considerations'>
16 <title>General Migration Considerations</title>
17
18 <para>
19 Some considerations are not tied to a specific Yocto Project
20 release.
21 This section presents information you should consider when
22 migrating to any new Yocto Project release.
23 <itemizedlist>
24 <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
25 Issues could arise if you take older recipes that contain
26 customizations and simply copy them forward expecting them
27 to work after you migrate to new Yocto Project metadata.
28 For example, suppose you have a recipe in your layer that is
29 a customized version of a core recipe copied from the earlier
30 release, rather than through the use of an append file.
31 When you migrate to a newer version of Yocto Project, the
32 metadata (e.g. perhaps an include file used by the recipe)
33 could have changed in a way that would break the build.
34 Say, for example, a function is removed from an include file
35 and the customized recipe tries to call that function.
36 </para>
37
38 <para>You could "forward-port" all your customizations in your
39 recipe so that everything works for the new release.
40 However, this is not the optimal solution as you would have
41 to repeat this process with each new release if changes
42 occur that give rise to problems.</para>
43
44 <para>The better solution (where practical) is to use append
45 files (<filename>*.bbappend</filename>) to capture any
46 customizations you want to make to a recipe.
47 Doing so, isolates your changes from the main recipe making
48 them much more manageable.
49 However, sometimes it is not practical to use an append
50 file.
51 A good example of this is when introducing a newer or older
52 version of a recipe in another layer.</para>
53 </listitem>
54 <listitem><para><emphasis>Updating Append Files</emphasis>:
55 Since append files generally only contain your customizations,
56 they often do not need to be adjusted for new releases.
57 However, if the <filename>.bbappend</filename> file is
58 specific to a particular version of the recipe (i.e. its
59 name does not use the % wildcard) and the version of the
60 recipe to which it is appending has changed, then you will
61 at a minimum need to rename the append file to match the
62 name of the recipe file.
63 A mismatch between an append file and its corresponding
64 recipe file (<filename>.bb</filename>) will
65 trigger an error during parsing.</para>
66 <para>Depending on the type of customization the append file
67 applies, other incompatibilities might occur when you
68 upgrade.
69 For example, if your append file applies a patch and the
70 recipe to which it is appending is updated to a newer
71 version, the patch might no longer apply.
72 If this is the case and assuming the patch is still needed,
73 you must modify the patch file so that it does apply.
74 </para></listitem>
75 </itemizedlist>
76 </para>
77</section>
78
79<section id='moving-to-the-yocto-project-1.3-release'>
80 <title>Moving to the Yocto Project 1.3 Release</title>
81
82 <para>
83 This section provides migration information for moving to the
84 Yocto Project 1.3 Release from the prior release.
85 </para>
86
87 <section id='1.3-local-configuration'>
88 <title>Local Configuration</title>
89
90 <para>
91 Differences include changes for
92 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
93 and <filename>bblayers.conf</filename>.
94 </para>
95
96 <section id='migration-1.3-sstate-mirrors'>
97 <title>SSTATE_MIRRORS</title>
98
99 <para>
100 The shared state cache (sstate-cache), as pointed to by
101 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
102 by default now has two-character subdirectories to prevent
103 issues arising from too many files in the same directory.
104 Also, native sstate-cache packages, which are built to run
105 on the host system, will go into a subdirectory named using
106 the distro ID string.
107 If you copy the newly structured sstate-cache to a mirror
108 location (either local or remote) and then point to it in
109 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
110 you need to append "PATH" to the end of the mirror URL so that
111 the path used by BitBake before the mirror substitution is
112 appended to the path used to access the mirror.
113 Here is an example:
114 <literallayout class='monospaced'>
115 SSTATE_MIRRORS = "file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH"
116 </literallayout>
117 </para>
118 </section>
119
120 <section id='migration-1.3-bblayers-conf'>
121 <title>bblayers.conf</title>
122
123 <para>
124 The <filename>meta-yocto</filename> layer consists of two parts
125 that correspond to the Poky reference distribution and the
126 reference hardware Board Support Packages (BSPs), respectively:
127 <filename>meta-yocto</filename> and
128 <filename>meta-yocto-bsp</filename>.
129 When running BitBake for the first time after upgrading,
130 your <filename>conf/bblayers.conf</filename> file will be
131 updated to handle this change and you will be asked to
132 re-run or restart for the changes to take effect.
133 </para>
134 </section>
135 </section>
136
137 <section id='1.3-recipes'>
138 <title>Recipes</title>
139
140 <para>
141 Differences include changes for the following:
142 <itemizedlist>
143 <listitem><para>Python function whitespace</para></listitem>
144 <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
145 <listitem><para><filename>nativesdk</filename></para></listitem>
146 <listitem><para>Task recipes</para></listitem>
147 <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
148 <listitem><para>Removed recipes</para></listitem>
149 </itemizedlist>
150 </para>
151
152 <section id='migration-1.3-python-function-whitespace'>
153 <title>Python Function Whitespace</title>
154
155 <para>
156 All Python functions must now use four spaces for indentation.
157 Previously, an inconsistent mix of spaces and tabs existed,
158 which made extending these functions using
159 <filename>_append</filename> or <filename>_prepend</filename>
160 complicated given that Python treats whitespace as
161 syntactically significant.
162 If you are defining or extending any Python functions (e.g.
163 <filename>populate_packages</filename>, <filename>do_unpack</filename>,
164 <filename>do_patch</filename> and so forth) in custom recipes
165 or classes, you need to ensure you are using consistent
166 four-space indentation.
167 </para>
168 </section>
169
170 <section id='migration-1.3-proto=-in-src-uri'>
171 <title>proto= in SRC_URI</title>
172
173 <para>
174 Any use of <filename>proto=</filename> in
175 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
176 needs to be changed to <filename>protocol=</filename>.
177 In particular, this applies to the following URIs:
178 <itemizedlist>
179 <listitem><para><filename>svn://</filename></para></listitem>
180 <listitem><para><filename>bzr://</filename></para></listitem>
181 <listitem><para><filename>hg://</filename></para></listitem>
182 <listitem><para><filename>osc://</filename></para></listitem>
183 </itemizedlist>
184 Other URIs were already using <filename>protocol=</filename>.
185 This change improves consistency.
186 </para>
187 </section>
188
189 <section id='migration-1.3-nativesdk'>
190 <title>nativesdk</title>
191
192 <para>
193 The suffix <filename>nativesdk</filename> is now implemented
194 as a prefix, which simplifies a lot of the packaging code for
195 <filename>nativesdk</filename> recipes.
196 All custom <filename>nativesdk</filename> recipes, which are
197 relocatable packages that are native to
198 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
199 and any references need to be updated to use
200 <filename>nativesdk-*</filename> instead of
201 <filename>*-nativesdk</filename>.
202 </para>
203 </section>
204
205 <section id='migration-1.3-task-recipes'>
206 <title>Task Recipes</title>
207
208 <para>
209 "Task" recipes are now known as "Package groups" and have
210 been renamed from <filename>task-*.bb</filename> to
211 <filename>packagegroup-*.bb</filename>.
212 Existing references to the previous <filename>task-*</filename>
213 names should work in most cases as there is an automatic
214 upgrade path for most packages.
215 However, you should update references in your own recipes and
216 configurations as they could be removed in future releases.
217 You should also rename any custom <filename>task-*</filename>
218 recipes to <filename>packagegroup-*</filename>, and change
219 them to inherit <filename>packagegroup</filename> instead of
220 <filename>task</filename>, as well as taking the opportunity
221 to remove anything now handled by
222 <filename>packagegroup.bbclass</filename>, such as providing
223 <filename>-dev</filename> and <filename>-dbg</filename>
224 packages, setting
225 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
226 and so forth.
227 See the
228 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
229 section for further details.
230 </para>
231 </section>
232
233 <section id='migration-1.3-image-features'>
234 <title>IMAGE_FEATURES</title>
235
236 <para>
237 Image recipes that previously included "apps-console-core"
238 in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
239 should now include "splash" instead to enable the boot-up
240 splash screen.
241 Retaining "apps-console-core" will still include the splash
242 screen but generates a warning.
243 The "apps-x11-core" and "apps-x11-games"
244 <filename>IMAGE_FEATURES</filename> features have been removed.
245 </para>
246 </section>
247
248 <section id='migration-1.3-removed-recipes'>
249 <title>Removed Recipes</title>
250
251 <para>
252 The following recipes have been removed.
253 For most of them, it is unlikely that you would have any
254 references to them in your own
255 <link linkend='metadata'>Metadata</link>.
256 However, you should check your metadata against this list to be sure:
257 <itemizedlist>
258 <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
259 Replaced by <filename>libx11</filename>, which has a negligible
260 size difference with modern Xorg.</para></listitem>
261 <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
262 Use <filename>xserver-xorg</filename>, which has a negligible
263 size difference when DRI and GLX modules are not installed.</para></listitem>
264 <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
265 Effectively unmaintained for many years.</para></listitem>
266 <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
267 No longer serves any purpose.</para></listitem>
268 <listitem><para><emphasis><filename>galago</filename></emphasis>:
269 Replaced by telepathy.</para></listitem>
270 <listitem><para><emphasis><filename>gail</filename></emphasis>:
271 Functionality was integrated into GTK+ 2.13.</para></listitem>
272 <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
273 No longer needed.</para></listitem>
274 <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
275 The build has been restructured to avoid the need for
276 this step.</para></listitem>
277 <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
278 Unmaintained for many years.
279 Functionality now provided by
280 <filename>ofono</filename> instead.</para></listitem>
281 <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
282 Largely unmaintained PIM application suite.
283 It has been moved to <filename>meta-gnome</filename>
284 in <filename>meta-openembedded</filename>.</para></listitem>
285 </itemizedlist>
286 In addition to the previously listed changes, the
287 <filename>meta-demoapps</filename> directory has also been removed
288 because the recipes in it were not being maintained and many
289 had become obsolete or broken.
290 Additionally, these recipes were not parsed in the default configuration.
291 Many of these recipes are already provided in an updated and
292 maintained form within the OpenEmbedded community layers such as
293 <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
294 For the remainder, you can now find them in the
295 <filename>meta-extras</filename> repository, which is in the
296 Yocto Project
297 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
298 </para>
299 </section>
300 </section>
301
302 <section id='1.3-linux-kernel-naming'>
303 <title>Linux Kernel Naming</title>
304
305 <para>
306 The naming scheme for kernel output binaries has been changed to
307 now include
308 <link linkend='var-PE'><filename>PE</filename></link> as part of the
309 filename:
310 <literallayout class='monospaced'>
311 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
312 </literallayout>
313 </para>
314
315 <para>
316 Because the <filename>PE</filename> variable is not set by default,
317 these binary files could result with names that include two dash
318 characters.
319 Here is an example:
320 <literallayout class='monospaced'>
321 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
322 </literallayout>
323 </para>
324 </section>
325</section>
326
327<section id='moving-to-the-yocto-project-1.4-release'>
328 <title>Moving to the Yocto Project 1.4 Release</title>
329
330 <para>
331 This section provides migration information for moving to the
332 Yocto Project 1.4 Release from the prior release.
333 </para>
334
335 <section id='migration-1.4-bitbake'>
336 <title>BitBake</title>
337
338 <para>
339 Differences include the following:
340 <itemizedlist>
341 <listitem><para><emphasis>Comment Continuation:</emphasis>
342 If a comment ends with a line continuation (\) character,
343 then the next line must also be a comment.
344 Any instance where this is not the case, now triggers
345 a warning.
346 You must either remove the continuation character, or be
347 sure the next line is a comment.
348 </para></listitem>
349 <listitem><para><emphasis>Package Name Overrides:</emphasis>
350 The runtime package specific variables
351 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
352 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
353 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
354 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
355 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
356 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
357 <link linkend='var-FILES'><filename>FILES</filename></link>,
358 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
359 and the pre, post, install, and uninstall script functions
360 <filename>pkg_preinst</filename>,
361 <filename>pkg_postinst</filename>,
362 <filename>pkg_prerm</filename>, and
363 <filename>pkg_postrm</filename> should always have a
364 package name override.
365 For example, use <filename>RDEPENDS_${PN}</filename> for
366 the main package instead of <filename>RDEPENDS</filename>.
367 BitBake uses more strict checks when it parses recipes.
368 </para></listitem>
369 </itemizedlist>
370 </para>
371 </section>
372
373 <section id='migration-1.4-build-behavior'>
374 <title>Build Behavior</title>
375
376 <para>
377 Differences include the following:
378 <itemizedlist>
379 <listitem><para><emphasis>Shared State Code:</emphasis>
380 The shared state code has been optimized to avoid running
381 unnecessary tasks.
382 For example, the following no longer populates the target
383 sysroot since that is not necessary:
384 <literallayout class='monospaced'>
385 $ bitbake -c rootfs <replaceable>some-image</replaceable>
386 </literallayout>
387 Instead, the system just needs to extract the output
388 package contents, re-create the packages, and construct
389 the root filesystem.
390 This change is unlikely to cause any problems unless
391 you have missing declared dependencies.
392 </para></listitem>
393 <listitem><para><emphasis>Scanning Directory Names:</emphasis>
394 When scanning for files in
395 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
396 the build system now uses
397 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
398 instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
399 for the directory names.
400 In general, the values previously in
401 <filename>OVERRIDES</filename> are now in
402 <filename>FILESOVERRIDES</filename> as well.
403 However, if you relied upon an additional value
404 you previously added to <filename>OVERRIDES</filename>,
405 you might now need to add it to
406 <filename>FILESOVERRIDES</filename> unless you are already
407 adding it through the
408 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
409 or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
410 variables, as appropriate.
411 For more related changes, see the
412 "<link linkend='migration-1.4-variables'>Variables</link>"
413 section.
414 </para></listitem>
415 </itemizedlist>
416 </para>
417 </section>
418
419
420 <section id='migration-1.4-proxies-and-fetching-source'>
421 <title>Proxies and Fetching Source</title>
422
423 <para>
424 A new <filename>oe-git-proxy</filename> script has been added to
425 replace previous methods of handling proxies and fetching source
426 from Git.
427 See the <filename>meta-yocto/conf/site.conf.sample</filename> file
428 for information on how to use this script.
429 </para>
430 </section>
431
432 <section id='migration-1.4-custom-interfaces-file-netbase-change'>
433 <title>Custom Interfaces File (netbase change)</title>
434
435 <para>
436 If you have created your own custom
437 <filename>etc/network/interfaces</filename> file by creating
438 an append file for the <filename>netbase</filename> recipe,
439 you now need to create an append file for the
440 <filename>init-ifupdown</filename> recipe instead, which you can
441 find in the
442 <link linkend='source-directory'>Source Directory</link>
443 at <filename>meta/recipes-core/init-ifupdown</filename>.
444 For information on how to use append files, see the
445 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
446 section in the Yocto Project Development Tasks Manual.
447 </para>
448 </section>
449
450 <section id='migration-1.4-remote-debugging'>
451 <title>Remote Debugging</title>
452
453 <para>
454 Support for remote debugging with the Eclipse IDE is now
455 separated into an image feature
456 (<filename>eclipse-debug</filename>) that corresponds to the
457 <filename>packagegroup-core-eclipse-debug</filename> package group.
458 Previously, the debugging feature was included through the
459 <filename>tools-debug</filename> image feature, which corresponds
460 to the <filename>packagegroup-core-tools-debug</filename>
461 package group.
462 </para>
463 </section>
464
465 <section id='migration-1.4-variables'>
466 <title>Variables</title>
467
468 <para>
469 The following variables have changed:
470 <itemizedlist>
471 <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
472 This variable now uses a distribution ID, which is composed
473 of the host distributor ID followed by the release.
474 Previously,
475 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
476 was composed of the description field.
477 For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
478 You do not need to worry about this change if you are not
479 specifically setting this variable, or if you are
480 specifically setting it to "".
481 </para></listitem>
482 <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
483 The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
484 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
485 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
486 and <filename>FILE_DIRNAME</filename> directories have been
487 dropped from the default value of the
488 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
489 variable, which is used as the search path for finding files
490 referred to in
491 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
492 If you have a recipe that relied upon these directories,
493 which would be unusual, then you will need to add the
494 appropriate paths within the recipe or, alternatively,
495 rearrange the files.
496 The most common locations are still covered by
497 <filename>${BP}</filename>, <filename>${BPN}</filename>,
498 and "files", which all remain in the default value of
499 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
500 </para></listitem>
501 </itemizedlist>
502 </para>
503 </section>
504
505 <section id='migration-target-package-management-with-rpm'>
506 <title>Target Package Management with RPM</title>
507
508 <para>
509 If runtime package management is enabled and the RPM backend
510 is selected, Smart is now installed for package download, dependency
511 resolution, and upgrades instead of Zypper.
512 For more information on how to use Smart, run the following command
513 on the target:
514 <literallayout class='monospaced'>
515 smart --help
516 </literallayout>
517 </para>
518 </section>
519
520 <section id='migration-1.4-recipes-moved'>
521 <title>Recipes Moved</title>
522
523 <para>
524 The following recipes were moved from their previous locations
525 because they are no longer used by anything in
526 the OpenEmbedded-Core:
527 <itemizedlist>
528 <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
529 Now resides in the <filename>meta-oe</filename> layer.
530 </para></listitem>
531 <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
532 Now resides in the <filename>meta-gnome</filename> layer.
533 </para></listitem>
534 <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
535 Now resides in the <filename>meta-gnome</filename> layer.
536 </para></listitem>
537 <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
538 Now resides in the <filename>meta-oe</filename> layer.
539 </para></listitem>
540 <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
541 Now resides in the <filename>meta-multimedia</filename> layer.
542 </para></listitem>
543 <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
544 Now resides in the <filename>meta-oe</filename> layer.
545 </para></listitem>
546 <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
547 Now resides in the <filename>meta-gnome</filename> layer.
548 </para></listitem>
549 <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
550 Now resides in the <filename>meta-gnome</filename> layer.
551 </para></listitem>
552 <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
553 Now resides in the <filename>meta-multimedia</filename> layer.
554 </para></listitem>
555 <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
556 Now resides in the <filename>meta-gnome</filename> layer.
557 </para></listitem>
558 <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
559 Now resides in the <filename>meta-oe</filename> layer.
560 </para></listitem>
561 <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
562 Now resides in the <filename>meta-networking</filename> layer.
563 </para></listitem>
564 </itemizedlist>
565 </para>
566 </section>
567
568 <section id='migration-1.4-removals-and-renames'>
569 <title>Removals and Renames</title>
570
571 <para>
572 The following list shows what has been removed or renamed:
573 <itemizedlist>
574 <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
575 Removed because it has been removed from
576 <filename>xserver</filename> since 2008.
577 </para></listitem>
578 <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
579 Removed support because upstream Gtk+ no longer supports it
580 as of version 2.18.
581 </para></listitem>
582 <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
583 Removed because they were removed from the Xorg server in 2008.
584 </para></listitem>
585 <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
586 Removed because the XPrint server was removed from
587 Xorg in 2008.
588 </para></listitem>
589 <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
590 Removed because their functionality was broken upstream.
591 </para></listitem>
592 <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
593 Removed with linux-yocto 3.8 kernel being added.
594 The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
595 as part of the release.
596 </para></listitem>
597 <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
598 Removed with functionality now provided by
599 <filename>lsbtest</filename>.
600 </para></listitem>
601 <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
602 Removed because it was never more than a proof-of-concept.
603 </para></listitem>
604 <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
605 Removed because they are not maintained.
606 However, <filename>matchbox-wm</filename> and
607 <filename>matchbox-theme-sato</filename> are still
608 provided.
609 </para></listitem>
610 <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
611 Renamed to <filename>mesa</filename>.
612 </para></listitem>
613 <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
614 Removed because it was no longer useful.
615 </para></listitem>
616 <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
617 Removed because nothing ever uses it and the recipe is
618 very old.
619 </para></listitem>
620 <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
621 Removed because it has become obsolete.
622 </para></listitem>
623 <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
624 Removed because it is no longer used.
625 The kernel module <filename>postinstall</filename> and
626 <filename>postrm</filename> scripts can now do the same
627 task without the use of this script.
628 </para></listitem>
629 <listitem><para><emphasis><filename>web</filename>:</emphasis>
630 Removed because it is not maintained. Superseded by
631 <filename>web-webkit</filename>.
632 </para></listitem>
633 <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
634 Removed because upstream it has been disabled by default
635 since 2007.
636 Nothing uses <filename>xf86bigfontproto</filename>.
637 </para></listitem>
638 <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
639 Removed because its dependency in
640 <filename>xserver</filename> was spurious and it was
641 removed in 2005.
642 </para></listitem>
643 <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
644 Removed and been functionally replaced with Smart
645 (<filename>python-smartpm</filename>) when RPM packaging
646 is used and package management is enabled on the target.
647 </para></listitem>
648 </itemizedlist>
649 </para>
650 </section>
651</section>
652
653<section id='moving-to-the-yocto-project-1.5-release'>
654 <title>Moving to the Yocto Project 1.5 Release</title>
655
656 <para>
657 This section provides migration information for moving to the
658 Yocto Project 1.5 Release from the prior release.
659 </para>
660
661 <section id='migration-1.5-host-dependency-changes'>
662 <title>Host Dependency Changes</title>
663
664 <para>
665 The OpenEmbedded build system now has some additional requirements
666 on the host system:
667 <itemizedlist>
668 <listitem><para>Python 2.7.3+</para></listitem>
669 <listitem><para>Tar 1.24+</para></listitem>
670 <listitem><para>Git 1.7.8+</para></listitem>
671 <listitem><para>Patched version of Make if you are using
672 3.82.
673 Most distributions that provide Make 3.82 use the patched
674 version.</para></listitem>
675 </itemizedlist>
676 If the Linux distribution you are using on your build host
677 does not provide packages for these, you can install and use
678 the Buildtools tarball, which provides an SDK-like environment
679 containing them.
680 </para>
681
682 <para>
683 For more information on this requirement, see the
684 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
685 section.
686 </para>
687 </section>
688
689 <section id='migration-1.5-atom-pc-bsp'>
690 <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
691
692 <para>
693 The <filename>atom-pc</filename> hardware reference BSP has been
694 replaced by a <filename>genericx86</filename> BSP.
695 This BSP is not necessarily guaranteed to work on all x86
696 hardware, but it will run on a wider range of systems than the
697 <filename>atom-pc</filename> did.
698 <note>
699 Additionally, a <filename>genericx86-64</filename> BSP has
700 been added for 64-bit Atom systems.
701 </note>
702 </para>
703 </section>
704
705 <section id='migration-1.5-bitbake'>
706 <title>BitBake</title>
707
708 <para>
709 The following changes have been made that relate to BitBake:
710 <itemizedlist>
711 <listitem><para>
712 BitBake now supports a <filename>_remove</filename>
713 operator.
714 The addition of this operator means you will have to
715 rename any items in recipe space (functions, variables)
716 whose names currently contain
717 <filename>_remove_</filename> or end with
718 <filename>_remove</filename> to avoid unexpected behavior.
719 </para></listitem>
720 <listitem><para>
721 BitBake's global method pool has been removed.
722 This method is not particularly useful and led to clashes
723 between recipes containing functions that had the
724 same name.</para></listitem>
725 <listitem><para>
726 The "none" server backend has been removed.
727 The "process" server backend has been serving well as the
728 default for a long time now.</para></listitem>
729 <listitem><para>
730 The <filename>bitbake-runtask</filename> script has been
731 removed.</para></listitem>
732 <listitem><para>
733 <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
734 and
735 <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
736 are no longer added to
737 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
738 by default in <filename>bitbake.conf</filename>.
739 These version-specific <filename>PROVIDES</filename>
740 items were seldom used.
741 Attempting to use them could result in two versions being
742 built simultaneously rather than just one version due to
743 the way BitBake resolves dependencies.</para></listitem>
744 </itemizedlist>
745 </para>
746 </section>
747
748 <section id='migration-1.5-qa-warnings'>
749 <title>QA Warnings</title>
750
751 <para>
752 The following changes have been made to the package QA checks:
753 <itemizedlist>
754 <listitem><para>
755 If you have customized
756 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
757 or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
758 values in your configuration, check that they contain all of
759 the issues that you wish to be reported.
760 Previous Yocto Project versions contained a bug that meant
761 that any item not mentioned in <filename>ERROR_QA</filename>
762 or <filename>WARN_QA</filename> would be treated as a
763 warning.
764 Consequently, several important items were not already in
765 the default value of <filename>WARN_QA</filename>.
766 All of the possible QA checks are now documented in the
767 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
768 section.</para></listitem>
769 <listitem><para>
770 An additional QA check has been added to check if
771 <filename>/usr/share/info/dir</filename> is being installed.
772 Your recipe should delete this file within
773 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
774 if "make install" is installing it.
775 </para></listitem>
776 <listitem><para>
777 If you are using the buildhistory class, the check for the
778 package version going backwards is now controlled using a
779 standard QA check.
780 Thus, if you have customized your
781 <filename>ERROR_QA</filename> or
782 <filename>WARN_QA</filename> values and still wish to have
783 this check performed, you should add
784 "version-going-backwards" to your value for one or the
785 other variables depending on how you wish it to be handled.
786 See the documented QA checks in the
787 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
788 section.
789 </para></listitem>
790 </itemizedlist>
791 </para>
792 </section>
793
794 <section id='migration-1.5-directory-layout-changes'>
795 <title>Directory Layout Changes</title>
796
797 <para>
798 The following directory changes exist:
799 <itemizedlist>
800 <listitem><para>
801 Output SDK installer files are now named to include the
802 image name and tuning architecture through the
803 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
804 variable.</para></listitem>
805 <listitem><para>
806 Images and related files are now installed into a directory
807 that is specific to the machine, instead of a parent
808 directory containing output files for multiple machines.
809 The
810 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
811 variable continues to point to the directory containing
812 images for the current
813 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
814 and should be used anywhere there is a need to refer to
815 this directory.
816 The <filename>runqemu</filename> script now uses this
817 variable to find images and kernel binaries and will use
818 BitBake to determine the directory.
819 Alternatively, you can set the
820 <filename>DEPLOY_DIR_IMAGE</filename> variable in the
821 external environment.</para></listitem>
822 <listitem><para>
823 When buildhistory is enabled, its output is now written
824 under the
825 <link linkend='build-directory'>Build Directory</link>
826 rather than
827 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
828 Doing so makes it easier to delete
829 <filename>TMPDIR</filename> and preserve the build history.
830 Additionally, data for produced SDKs is now split by
831 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
832 </para></listitem>
833 <listitem><para>
834 The <filename>pkgdata</filename> directory produced as
835 part of the packaging process has been collapsed into a
836 single machine-specific directory.
837 This directory is located under
838 <filename>sysroots</filename> and uses a machine-specific
839 name (i.e.
840 <filename>tmp/sysroots/<replaceable>machine</replaceable>/pkgdata</filename>).
841 </para></listitem>
842 </itemizedlist>
843 </para>
844 </section>
845
846 <section id='migration-1.5-shortened-git-srcrev-values'>
847 <title>Shortened Git <filename>SRCREV</filename> Values</title>
848
849 <para>
850 BitBake will now shorten revisions from Git repositories from the
851 normal 40 characters down to 10 characters within
852 <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
853 for improved usability in path and file names.
854 This change should be safe within contexts where these revisions
855 are used because the chances of spatially close collisions
856 is very low.
857 Distant collisions are not a major issue in the way
858 the values are used.
859 </para>
860 </section>
861
862 <section id='migration-1.5-image-features'>
863 <title><filename>IMAGE_FEATURES</filename></title>
864
865 <para>
866 The following changes have been made that relate to
867 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
868 <itemizedlist>
869 <listitem><para>
870 The value of <filename>IMAGE_FEATURES</filename> is now
871 validated to ensure invalid feature items are not added.
872 Some users mistakenly add package names to this variable
873 instead of using
874 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
875 in order to have the package added to the image, which does
876 not work.
877 This change is intended to catch those kinds of situations.
878 Valid <filename>IMAGE_FEATURES</filename> are drawn from
879 <filename>PACKAGE_GROUP</filename> definitions,
880 <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
881 and a new "validitems" varflag on
882 <filename>IMAGE_FEATURES</filename>.
883 The "validitems" varflag change allows additional features
884 to be added if they are not provided using the previous
885 two mechanisms.
886 </para></listitem>
887 <listitem><para>
888 The previously deprecated "apps-console-core"
889 <filename>IMAGE_FEATURES</filename> item is no longer
890 supported.
891 Add "splash" to <filename>IMAGE_FEATURES</filename> if you
892 wish to have the splash screen enabled, since this is
893 all that apps-console-core was doing.</para></listitem>
894 </itemizedlist>
895 </para>
896 </section>
897
898 <section id='migration-1.5-run'>
899 <title><filename>/run</filename></title>
900
901 <para>
902 The <filename>/run</filename> directory from the Filesystem
903 Hierarchy Standard 3.0 has been introduced.
904 You can find some of the implications for this change
905 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
906 The change also means that recipes that install files to
907 <filename>/var/run</filename> must be changed.
908 You can find a guide on how to make these changes
909 <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
910 </para>
911 </section>
912
913 <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
914 <title>Removal of Package Manager Database Within Image Recipes</title>
915
916 <para>
917 The image <filename>core-image-minimal</filename> no longer adds
918 <filename>remove_packaging_data_files</filename> to
919 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
920 This addition is now handled automatically when "package-management"
921 is not in
922 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
923 If you have custom image recipes that make this addition,
924 you should remove the lines, as they are not needed and might
925 interfere with correct operation of postinstall scripts.
926 </para>
927 </section>
928
929 <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
930 <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
931
932 <para>
933 The
934 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
935 and other related image
936 construction tasks are no longer marked as "nostamp".
937 Consequently, they will only be re-executed when their inputs have
938 changed.
939 Previous versions of the OpenEmbedded build system always rebuilt
940 the image when requested rather when necessary.
941 </para>
942 </section>
943
944 <section id='migration-1.5-task-recipes'>
945 <title>Task Recipes</title>
946
947 <para>
948 The previously deprecated <filename>task.bbclass</filename> has
949 now been dropped.
950 For recipes that previously inherited from this class, you should
951 rename them from <filename>task-*</filename> to
952 <filename>packagegroup-*</filename> and inherit packagegroup
953 instead.
954 </para>
955
956 <para>
957 For more information, see the
958 "<link linkend='ref-classes-packagegroup'><filename>packagegroup.bbclass</filename></link>"
959 section.
960 </para>
961 </section>
962
963 <section id='migration-1.5-busybox'>
964 <title>BusyBox</title>
965
966 <para>
967 By default, we now split BusyBox into two binaries:
968 one that is suid root for those components that need it, and
969 another for the rest of the components.
970 Splitting BusyBox allows for optimization that eliminates the
971 <filename>tinylogin</filename> recipe as recommended by upstream.
972 You can disable this split by setting
973 <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
974 to "0".
975 </para>
976 </section>
977
978 <section id='migration-1.5-automated-image-testing'>
979 <title>Automated Image Testing</title>
980
981 <para>
982 A new automated image testing framework has been added
983 through the
984 <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>
985 class.
986 This framework replaces the older
987 <filename>imagetest-qemu</filename> framework.
988 </para>
989
990 <para>
991 You can learn more about performing automated image tests in the
992 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
993 section in the Yocto Project Development Tasks Manual.
994 </para>
995 </section>
996
997 <section id='migration-1.5-build-history'>
998 <title>Build History</title>
999
1000 <para>
1001 Following are changes to Build History:
1002 <itemizedlist>
1003 <listitem><para>
1004 Installed package sizes:
1005 <filename>installed-package-sizes.txt</filename> for an
1006 image now records the size of the files installed by each
1007 package instead of the size of each compressed package
1008 archive file.</para></listitem>
1009 <listitem><para>
1010 The dependency graphs (<filename>depends*.dot</filename>)
1011 now use the actual package names instead of replacing
1012 dashes, dots and plus signs with underscores.
1013 </para></listitem>
1014 <listitem><para>
1015 The <filename>buildhistory-diff</filename> and
1016 <filename>buildhistory-collect-srcrevs</filename>
1017 utilities have improved command-line handling.
1018 Use the <filename>--help</filename> option for
1019 each utility for more information on the new syntax.
1020 </para></listitem>
1021 </itemizedlist>
1022 For more information on Build History, see the
1023 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1024 section in the Yocto Project Development Tasks Manual.
1025 </para>
1026 </section>
1027
1028 <section id='migration-1.5-udev'>
1029 <title><filename>udev</filename></title>
1030
1031 <para>
1032 Following are changes to <filename>udev</filename>:
1033 <itemizedlist>
1034 <listitem><para>
1035 <filename>udev</filename> no longer brings in
1036 <filename>udev-extraconf</filename> automatically
1037 through
1038 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1039 since this was originally intended to be optional.
1040 If you need the extra rules, then add
1041 <filename>udev-extraconf</filename> to your image.
1042 </para></listitem>
1043 <listitem><para>
1044 <filename>udev</filename> no longer brings in
1045 <filename>pciutils-ids</filename> or
1046 <filename>usbutils-ids</filename> through
1047 <filename>RRECOMMENDS</filename>.
1048 These are not needed by <filename>udev</filename> itself
1049 and removing them saves around 350KB.
1050 </para></listitem>
1051 </itemizedlist>
1052 </para>
1053 </section>
1054
1055 <section id='migration-1.5-removed-renamed-recipes'>
1056 <title>Removed and Renamed Recipes</title>
1057
1058 <itemizedlist>
1059 <listitem><para>
1060 The <filename>linux-yocto</filename> 3.2 kernel has been
1061 removed.</para></listitem>
1062 <listitem><para>
1063 <filename>libtool-nativesdk</filename> has been renamed to
1064 <filename>nativesdk-libtool</filename>.</para></listitem>
1065 <listitem><para>
1066 <filename>tinylogin</filename> has been removed.
1067 It has been replaced by a suid portion of Busybox.
1068 See the
1069 "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
1070 for more information.</para></listitem>
1071 <listitem><para>
1072 <filename>external-python-tarball</filename> has been renamed
1073 to <filename>buildtools-tarball</filename>.
1074 </para></listitem>
1075 <listitem><para>
1076 <filename>web-webkit</filename> has been removed.
1077 It has been functionally replaced by
1078 <filename>midori</filename>.</para></listitem>
1079 <listitem><para>
1080 <filename>imake</filename> has been removed.
1081 It is no longer needed by any other recipe.
1082 </para></listitem>
1083 <listitem><para>
1084 <filename>transfig-native</filename> has been removed.
1085 It is no longer needed by any other recipe.
1086 </para></listitem>
1087 <listitem><para>
1088 <filename>anjuta-remote-run</filename> has been removed.
1089 Anjuta IDE integration has not been officially supported for
1090 several releases.</para></listitem>
1091 </itemizedlist>
1092 </section>
1093
1094 <section id='migration-1.5-other-changes'>
1095 <title>Other Changes</title>
1096
1097 <para>
1098 Following is a list of short entries describing other changes:
1099 <itemizedlist>
1100 <listitem><para>
1101 <filename>run-postinsts</filename>: Make this generic.
1102 </para></listitem>
1103 <listitem><para>
1104 <filename>base-files</filename>: Remove the unnecessary
1105 <filename>media/</filename><replaceable>xxx</replaceable> directories.
1106 </para></listitem>
1107 <listitem><para>
1108 <filename>alsa-state</filename>: Provide an empty
1109 <filename>asound.conf</filename> by default.
1110 </para></listitem>
1111 <listitem><para>
1112 <filename>classes/image</filename>: Ensure
1113 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
1114 supports pre-renamed package names.</para></listitem>
1115 <listitem><para>
1116 <filename>classes/rootfs_rpm</filename>: Implement
1117 <filename>BAD_RECOMMENDATIONS</filename> for RPM.
1118 </para></listitem>
1119 <listitem><para>
1120 <filename>systemd</filename>: Remove
1121 <filename>systemd_unitdir</filename> if
1122 <filename>systemd</filename> is not in
1123 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
1124 </para></listitem>
1125 <listitem><para>
1126 <filename>systemd</filename>: Remove
1127 <filename>init.d</filename> dir if
1128 <filename>systemd</filename> unit file is present and
1129 <filename>sysvinit</filename> is not a distro feature.
1130 </para></listitem>
1131 <listitem><para>
1132 <filename>libpam</filename>: Deny all services for the
1133 <filename>OTHER</filename> entries.
1134 </para></listitem>
1135 <listitem><para>
1136 <filename>image.bbclass</filename>: Move
1137 <filename>runtime_mapping_rename</filename> to avoid
1138 conflict with <filename>multilib</filename>.
1139 See
1140 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
1141 in Bugzilla for more information.
1142 </para></listitem>
1143 <listitem><para>
1144 <filename>linux-dtb</filename>: Use kernel build system
1145 to generate the <filename>dtb</filename> files.
1146 </para></listitem>
1147 <listitem><para>
1148 <filename>kern-tools</filename>: Switch from guilt to
1149 new <filename>kgit-s2q</filename> tool.
1150 </para></listitem>
1151 </itemizedlist>
1152 </para>
1153 </section>
1154</section>
1155
1156<section id='moving-to-the-yocto-project-1.6-release'>
1157 <title>Moving to the Yocto Project 1.6 Release</title>
1158
1159 <para>
1160 This section provides migration information for moving to the
1161 Yocto Project 1.6 Release from the prior release.
1162 </para>
1163
1164
1165 <section id='migration-1.6-archiver-class'>
1166 <title><filename>archiver</filename> Class</title>
1167
1168 <para>
1169 The
1170 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
1171 class has been rewritten and its configuration has been simplified.
1172 For more details on the source archiver, see the
1173 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
1174 section in the Yocto Project Development Tasks Manual.
1175 </para>
1176 </section>
1177
1178 <section id='migration-1.6-packaging-changes'>
1179 <title>Packaging Changes</title>
1180
1181 <para>
1182 The following packaging changes have been made:
1183 <itemizedlist>
1184 <listitem><para>
1185 The <filename>binutils</filename> recipe no longer produces
1186 a <filename>binutils-symlinks</filename> package.
1187 <filename>update-alternatives</filename> is now used to
1188 handle the preferred <filename>binutils</filename>
1189 variant on the target instead.
1190 </para></listitem>
1191 <listitem><para>
1192 The tc (traffic control) utilities have been split out of
1193 the main <filename>iproute2</filename> package and put
1194 into the <filename>iproute2-tc</filename> package.
1195 </para></listitem>
1196 <listitem><para>
1197 The <filename>gtk-engines</filename> schemas have been
1198 moved to a dedicated
1199 <filename>gtk-engines-schemas</filename> package.
1200 </para></listitem>
1201 <listitem><para>
1202 The <filename>armv7a</filename> with thumb package
1203 architecture suffix has changed.
1204 The suffix for these packages with the thumb
1205 optimization enabled is "t2" as it should be.
1206 Use of this suffix was not the case in the 1.5 release.
1207 Architecture names will change within package feeds as a
1208 result.
1209 </para></listitem>
1210 </itemizedlist>
1211 </para>
1212 </section>
1213
1214 <section id='migration-1.6-bitbake'>
1215 <title>BitBake</title>
1216
1217 <para>
1218 The following changes have been made to
1219 <link linkend='bitbake-term'>BitBake</link>.
1220 </para>
1221
1222 <section id='migration-1.6-matching-branch-requirement-for-git-fetching'>
1223 <title>Matching Branch Requirement for Git Fetching</title>
1224
1225 <para>
1226 When fetching source from a Git repository using
1227 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
1228 BitBake will now validate the
1229 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1230 value against the branch.
1231 You can specify the branch using the following form:
1232 <literallayout class='monospaced'>
1233 SRC_URI = "git://server.name/repository;branch=<replaceable>branchname</replaceable>"
1234 </literallayout>
1235 If you do not specify a branch, BitBake looks
1236 in the default "master" branch.
1237 </para>
1238
1239 <para>
1240 Alternatively, if you need to bypass this check (e.g.
1241 if you are fetching a revision corresponding to a tag that
1242 is not on any branch), you can add ";nobranch=1" to
1243 the end of the URL within <filename>SRC_URI</filename>.
1244 </para>
1245 </section>
1246
1247 <section id='migration-1.6-bitbake-deps'>
1248 <title>Python Definition substitutions</title>
1249
1250 <para>
1251 BitBake had some previously deprecated Python definitions
1252 within its <filename>bb</filename> module removed.
1253 You should use their sub-module counterparts instead:
1254 <itemizedlist>
1255 <listitem><para><filename>bb.MalformedUrl</filename>:
1256 Use <filename>bb.fetch.MalformedUrl</filename>.
1257 </para></listitem>
1258 <listitem><para><filename>bb.encodeurl</filename>:
1259 Use <filename>bb.fetch.encodeurl</filename>.
1260 </para></listitem>
1261 <listitem><para><filename>bb.decodeurl</filename>:
1262 Use <filename>bb.fetch.decodeurl</filename>
1263 </para></listitem>
1264 <listitem><para><filename>bb.mkdirhier</filename>:
1265 Use <filename>bb.utils.mkdirhier</filename>.
1266 </para></listitem>
1267 <listitem><para><filename>bb.movefile</filename>:
1268 Use <filename>bb.utils.movefile</filename>.
1269 </para></listitem>
1270 <listitem><para><filename>bb.copyfile</filename>:
1271 Use <filename>bb.utils.copyfile</filename>.
1272 </para></listitem>
1273 <listitem><para><filename>bb.which</filename>:
1274 Use <filename>bb.utils.which</filename>.
1275 </para></listitem>
1276 <listitem><para><filename>bb.vercmp_string</filename>:
1277 Use <filename>bb.utils.vercmp_string</filename>.
1278 </para></listitem>
1279 <listitem><para><filename>bb.vercmp</filename>:
1280 Use <filename>bb.utils.vercmp</filename>.
1281 </para></listitem>
1282 </itemizedlist>
1283 </para>
1284 </section>
1285
1286 <section id='migration-1.6-bitbake-fetcher'>
1287 <title>SVK Fetcher</title>
1288
1289 <para>
1290 The SVK fetcher has been removed from BitBake.
1291 </para>
1292 </section>
1293
1294 <section id='migration-1.6-bitbake-console-output'>
1295 <title>Console Output Error Redirection</title>
1296
1297 <para>
1298 The BitBake console UI will now output errors to
1299 <filename>stderr</filename> instead of
1300 <filename>stdout</filename>.
1301 Consequently, if you are piping or redirecting the output of
1302 <filename>bitbake</filename> to somewhere else, and you wish
1303 to retain the errors, you will need to add
1304 <filename>2>&amp;1</filename> (or something similar) to the
1305 end of your <filename>bitbake</filename> command line.
1306 </para>
1307 </section>
1308
1309 <section id='migration-1.6-task-taskname-overrides'>
1310 <title><filename>task-</filename><replaceable>taskname</replaceable> Overrides</title>
1311
1312 <para>
1313 <filename>task-</filename><replaceable>taskname</replaceable> overrides have been
1314 adjusted so that tasks whose names contain underscores have the
1315 underscores replaced by hyphens for the override so that they
1316 now function properly.
1317 For example, the task override for
1318 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
1319 is <filename>task-populate-sdk</filename>.
1320 </para>
1321 </section>
1322 </section>
1323
1324 <section id='migration-1.6-variable-changes'>
1325 <title>Changes to Variables</title>
1326
1327 <para>
1328 The following variables have changed.
1329 For information on the OpenEmbedded build system variables, see the
1330 "<link linkend='ref-variables-glos'>Variables Glossary</link>" Chapter.
1331 </para>
1332
1333 <section id='migration-1.6-variable-changes-TMPDIR'>
1334 <title><filename>TMPDIR</filename></title>
1335
1336 <para>
1337 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1338 can no longer be on an NFS mount.
1339 NFS does not offer full POSIX locking and inode consistency
1340 and can cause unexpected issues if used to store
1341 <filename>TMPDIR</filename>.
1342 </para>
1343
1344 <para>
1345 The check for this occurs on startup.
1346 If <filename>TMPDIR</filename> is detected on an NFS mount,
1347 an error occurs.
1348 </para>
1349 </section>
1350
1351 <section id='migration-1.6-variable-changes-PRINC'>
1352 <title><filename>PRINC</filename></title>
1353
1354 <para>
1355 The <filename>PRINC</filename>
1356 variable has been deprecated and triggers a warning if
1357 detected during a build.
1358 For
1359 <link linkend='var-PR'><filename>PR</filename></link>
1360 increments on changes, use the PR service instead.
1361 You can find out more about this service in the
1362 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
1363 section in the Yocto Project Development Tasks Manual.
1364 </para>
1365 </section>
1366
1367 <section id='migration-1.6-variable-changes-IMAGE_TYPES'>
1368 <title><filename>IMAGE_TYPES</filename></title>
1369
1370 <para>
1371 The "sum.jffs2" option for
1372 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>
1373 has been replaced by the "jffs2.sum" option, which fits the
1374 processing order.
1375 </para>
1376 </section>
1377
1378 <section id='migration-1.6-variable-changes-COPY_LIC_MANIFEST'>
1379 <title><filename>COPY_LIC_MANIFEST</filename></title>
1380
1381 <para>
1382 The
1383 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
1384 variable must
1385 now be set to "1" rather than any value in order to enable
1386 it.
1387 </para>
1388 </section>
1389
1390 <section id='migration-1.6-variable-changes-COPY_LIC_DIRS'>
1391 <title><filename>COPY_LIC_DIRS</filename></title>
1392
1393 <para>
1394 The
1395 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
1396 variable must
1397 now be set to "1" rather than any value in order to enable
1398 it.
1399 </para>
1400 </section>
1401
1402 <section id='migration-1.6-variable-changes-PACKAGE_GROUP'>
1403 <title><filename>PACKAGE_GROUP</filename></title>
1404
1405 <para>
1406 The
1407 <filename>PACKAGE_GROUP</filename> variable has been renamed to
1408 <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>
1409 to more accurately reflect its purpose.
1410 You can still use <filename>PACKAGE_GROUP</filename> but
1411 the OpenEmbedded build system produces a warning message when
1412 it encounters the variable.
1413 </para>
1414 </section>
1415
1416 <section id='migration-1.6-variable-changes-variable-entry-behavior'>
1417 <title>Preprocess and Post Process Command Variable Behavior</title>
1418
1419 <para>
1420 The following variables now expect a semicolon separated
1421 list of functions to call and not arbitrary shell commands:
1422 <literallayout class='monospaced'>
1423 <link linkend='var-ROOTFS_PREPROCESS_COMMAND'>ROOTFS_PREPROCESS_COMMAND</link>
1424 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'>ROOTFS_POSTPROCESS_COMMAND</link>
1425 <link linkend='var-SDK_POSTPROCESS_COMMAND'>SDK_POSTPROCESS_COMMAND</link>
1426 <link linkend='var-POPULATE_SDK_POST_TARGET_COMMAND'>POPULATE_SDK_POST_TARGET_COMMAND</link>
1427 <link linkend='var-POPULATE_SDK_POST_HOST_COMMAND'>POPULATE_SDK_POST_HOST_COMMAND</link>
1428 <link linkend='var-IMAGE_POSTPROCESS_COMMAND'>IMAGE_POSTPROCESS_COMMAND</link>
1429 <link linkend='var-IMAGE_PREPROCESS_COMMAND'>IMAGE_PREPROCESS_COMMAND</link>
1430 <link linkend='var-ROOTFS_POSTUNINSTALL_COMMAND'>ROOTFS_POSTUNINSTALL_COMMAND</link>
1431 <link linkend='var-ROOTFS_POSTINSTALL_COMMAND'>ROOTFS_POSTINSTALL_COMMAND</link>
1432 </literallayout>
1433 For migration purposes, you can simply wrap shell commands in
1434 a shell function and then call the function.
1435 Here is an example:
1436 <literallayout class='monospaced'>
1437 my_postprocess_function() {
1438 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
1439 }
1440 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
1441 </literallayout>
1442 </para>
1443 </section>
1444 </section>
1445
1446 <section id='migration-1.6-package-test-ptest'>
1447 <title>Package Test (ptest)</title>
1448
1449 <para>
1450 Package Tests (ptest) are built but not installed by default.
1451 For information on using Package Tests, see the
1452 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages with ptest</ulink>"
1453 section in the Yocto Project Development Tasks Manual.
1454 For information on the <filename>ptest</filename> class, see the
1455 "<link linkend='ref-classes-ptest'><filename>ptest.bbclass</filename></link>"
1456 section.
1457 </para>
1458 </section>
1459
1460 <section id='migration-1.6-build-changes'>
1461 <title>Build Changes</title>
1462
1463 <para>
1464 Separate build and source directories have been enabled
1465 by default for selected recipes where it is known to work
1466 (a whitelist) and for all recipes that inherit the
1467 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
1468 class.
1469 In future releases the
1470 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1471 class will enable a separate build directory by default as
1472 well.
1473 Recipes building Autotools-based
1474 software that fails to build with a separate build directory
1475 should be changed to inherit from the
1476 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1477 class instead of the <filename>autotools</filename> or
1478 <filename>autotools_stage</filename>classes.
1479 </para>
1480 </section>
1481
1482 <section id='migration-1.6-building-qemu-native'>
1483 <title><filename>qemu-native</filename></title>
1484
1485 <para>
1486 <filename>qemu-native</filename> now builds without
1487 SDL-based graphical output support by default.
1488 The following additional lines are needed in your
1489 <filename>local.conf</filename> to enable it:
1490 <literallayout class='monospaced'>
1491 PACKAGECONFIG_pn-qemu-native = "sdl"
1492 ASSUME_PROVIDED += "libsdl-native"
1493 </literallayout>
1494 <note>
1495 The default <filename>local.conf</filename>
1496 contains these statements.
1497 Consequently, if you are building a headless system and using
1498 a default <filename>local.conf</filename> file, you will need
1499 comment these two lines out.
1500 </note>
1501 </para>
1502 </section>
1503
1504 <section id='migration-1.6-core-image-basic'>
1505 <title><filename>core-image-basic</filename></title>
1506
1507 <para>
1508 <filename>core-image-basic</filename> has been renamed to
1509 <filename>core-image-full-cmdline</filename>.
1510 </para>
1511
1512 <para>
1513 In addition to <filename>core-image-basic</filename> being renamed,
1514 <filename>packagegroup-core-basic</filename> has been renamed to
1515 <filename>packagegroup-core-full-cmdline</filename> to match.
1516 </para>
1517 </section>
1518
1519 <section id='migration-1.6-licensing'>
1520 <title>Licensing</title>
1521
1522 <para>
1523 The top-level <filename>LICENSE</filename> file has been changed
1524 to better describe the license of the various components of
1525 <link linkend='oe-core'>OE-Core</link>.
1526 However, the licensing itself remains unchanged.
1527 </para>
1528
1529 <para>
1530 Normally, this change would not cause any side-effects.
1531 However, some recipes point to this file within
1532 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
1533 (as <filename>${COREBASE}/LICENSE</filename>) and thus the
1534 accompanying checksum must be changed from
1535 3f40d7994397109285ec7b81fdeb3b58 to
1536 4d92cd373abda3937c2bc47fbc49d690.
1537 A better alternative is to have
1538 <filename>LIC_FILES_CHKSUM</filename> point to a file
1539 describing the license that is distributed with the source
1540 that the recipe is building, if possible, rather than pointing
1541 to <filename>${COREBASE}/LICENSE</filename>.
1542 </para>
1543 </section>
1544
1545 <section id='migration-1.6-cflags-options'>
1546 <title><filename>CFLAGS</filename> Options</title>
1547
1548 <para>
1549 The "-fpermissive" option has been removed from the default
1550 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1551 value.
1552 You need to take action on individual recipes that fail when
1553 building with this option.
1554 You need to either patch the recipes to fix the issues reported by
1555 the compiler, or you need to add "-fpermissive" to
1556 <filename>CFLAGS</filename> in the recipes.
1557 </para>
1558 </section>
1559
1560 <section id='migration-1.6-custom-images'>
1561 <title>Custom Image Output Types</title>
1562
1563 <para>
1564 Custom image output types, as selected using
1565 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
1566 must declare their dependencies on other image types (if any) using
1567 a new
1568 <link linkend='var-IMAGE_TYPEDEP'><filename>IMAGE_TYPEDEP</filename></link>
1569 variable.
1570 </para>
1571 </section>
1572
1573 <section id='migration-1.6-do-package-write-task'>
1574 <title>Tasks</title>
1575
1576 <para>
1577 The <filename>do_package_write</filename> task has been removed.
1578 The task is no longer needed.
1579 </para>
1580 </section>
1581
1582 <section id='migration-1.6-update-alternatives-provider'>
1583 <title><filename>update-alternative</filename> Provider</title>
1584
1585 <para>
1586 The default <filename>update-alternatives</filename> provider has
1587 been changed from <filename>opkg</filename> to
1588 <filename>opkg-utils</filename>.
1589 This change resolves some troublesome circular dependencies.
1590 The runtime package has also been renamed from
1591 <filename>update-alternatives-cworth</filename>
1592 to <filename>update-alternatives-opkg</filename>.
1593 </para>
1594 </section>
1595
1596 <section id='migration-1.6-virtclass-overrides'>
1597 <title><filename>virtclass</filename> Overrides</title>
1598
1599 <para>
1600 The <filename>virtclass</filename> overrides are now deprecated.
1601 Use the equivalent class overrides instead (e.g.
1602 <filename>virtclass-native</filename> becomes
1603 <filename>class-native</filename>.)
1604 </para>
1605 </section>
1606
1607 <section id='migration-1.6-removed-renamed-recipes'>
1608 <title>Removed and Renamed Recipes</title>
1609
1610 <para>
1611 The following recipes have been removed:
1612 <itemizedlist>
1613 <listitem><para><filename>packagegroup-toolset-native</filename> -
1614 This recipe is largely unused.
1615 </para></listitem>
1616 <listitem><para><filename>linux-yocto-3.8</filename> -
1617 Support for the Linux yocto 3.8 kernel has been dropped.
1618 Support for the 3.10 and 3.14 kernels have been added
1619 with the <filename>linux-yocto-3.10</filename> and
1620 <filename>linux-yocto-3.14</filename> recipes.
1621 </para></listitem>
1622 <listitem><para><filename>ocf-linux</filename> -
1623 This recipe has been functionally replaced using
1624 <filename>cryptodev-linux</filename>.
1625 </para></listitem>
1626 <listitem><para><filename>genext2fs</filename> -
1627 <filename>genext2fs</filename> is no longer used by the
1628 build system and is unmaintained upstream.
1629 </para></listitem>
1630 <listitem><para><filename>js</filename> -
1631 This provided an ancient version of Mozilla's javascript
1632 engine that is no longer needed.
1633 </para></listitem>
1634 <listitem><para><filename>zaurusd</filename> -
1635 The recipe has been moved to the
1636 <filename>meta-handheld</filename> layer.
1637 </para></listitem>
1638 <listitem><para><filename>eglibc 2.17</filename> -
1639 Replaced by the <filename>eglibc 2.19</filename>
1640 recipe.
1641 </para></listitem>
1642 <listitem><para><filename>gcc 4.7.2</filename> -
1643 Replaced by the now stable
1644 <filename>gcc 4.8.2</filename>.
1645 </para></listitem>
1646 <listitem><para><filename>external-sourcery-toolchain</filename> -
1647 this recipe is now maintained in the
1648 <filename>meta-sourcery</filename> layer.
1649 </para></listitem>
1650 <listitem><para><filename>linux-libc-headers-yocto 3.4+git</filename> -
1651 Now using version 3.10 of the
1652 <filename>linux-libc-headers</filename> by default.
1653 </para></listitem>
1654 <listitem><para><filename>meta-toolchain-gmae</filename> -
1655 This recipe is obsolete.
1656 </para></listitem>
1657 <listitem><para><filename>packagegroup-core-sdk-gmae</filename> -
1658 This recipe is obsolete.
1659 </para></listitem>
1660 <listitem><para><filename>packagegroup-core-standalone-gmae-sdk-target</filename> -
1661 This recipe is obsolete.
1662 </para></listitem>
1663 </itemizedlist>
1664 </para>
1665 </section>
1666
1667 <section id='migration-1.6-removed-classes'>
1668 <title>Removed Classes</title>
1669
1670 <para>
1671 The following classes have become obsolete and have been removed:
1672 <itemizedlist>
1673 <listitem><para><filename>module_strip</filename>
1674 </para></listitem>
1675 <listitem><para><filename>pkg_metainfo</filename>
1676 </para></listitem>
1677 <listitem><para><filename>pkg_distribute</filename>
1678 </para></listitem>
1679 <listitem><para><filename>image-empty</filename>
1680 </para></listitem>
1681 </itemizedlist>
1682 </para>
1683 </section>
1684
1685 <section id='migration-1.6-reference-bsps'>
1686 <title>Reference Board Support Packages (BSPs)</title>
1687
1688 <para>
1689 The following reference BSPs changes occurred:
1690 <itemizedlist>
1691 <listitem><para>The BeagleBoard
1692 (<filename>beagleboard</filename>) ARM reference hardware
1693 has been replaced by the BeagleBone
1694 (<filename>beaglebone</filename>) hardware.
1695 </para></listitem>
1696 <listitem><para>The RouterStation Pro
1697 (<filename>routerstationpro</filename>) MIPS reference
1698 hardware has been replaced by the EdgeRouter Lite
1699 (<filename>edgerouter</filename>) hardware.
1700 </para></listitem>
1701 </itemizedlist>
1702 The previous reference BSPs for the
1703 <filename>beagleboard</filename> and
1704 <filename>routerstationpro</filename> machines are still available
1705 in a new <filename>meta-yocto-bsp-old</filename> layer in the
1706 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
1707 at
1708 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/'>http://git.yoctoproject.org/cgit/cgit.cgi/meta-yocto-bsp-old/</ulink>.
1709 </para>
1710 </section>
1711</section>
1712
1713<section id='moving-to-the-yocto-project-1.7-release'>
1714 <title>Moving to the Yocto Project 1.7 Release</title>
1715
1716 <para>
1717 This section provides migration information for moving to the
1718 Yocto Project 1.7 Release from the prior release.
1719 </para>
1720
1721 <section id='migration-1.7-changes-to-setting-qemu-packageconfig-options'>
1722 <title>Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename></title>
1723
1724 <para>
1725 The QEMU recipe now uses a number of
1726 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
1727 options to enable various optional features.
1728 The method used to set defaults for these options means that
1729 existing
1730 <filename>local.conf</filename> files will need to be be
1731 modified to append to <filename>PACKAGECONFIG</filename> for
1732 <filename>qemu-native</filename> and
1733 <filename>nativesdk-qemu</filename> instead of setting it.
1734 In other words, to enable graphical output for QEMU, you should
1735 now have these lines in <filename>local.conf</filename>:
1736 <literallayout class='monospaced'>
1737 PACKAGECONFIG_append_pn-qemu-native = " sdl"
1738 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
1739 </literallayout>
1740 </para>
1741 </section>
1742
1743 <section id='migration-1.7-minimum-git-version'>
1744 <title>Minimum Git version</title>
1745
1746 <para>
1747 The minimum
1748 <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> version
1749 required on the build host is now 1.7.8 because the
1750 <filename>--list</filename> option is now required by
1751 BitBake's Git fetcher.
1752 As always, if your host distribution does not provide a version of
1753 Git that meets this requirement, you can use the
1754 <filename>buildtools-tarball</filename> that does.
1755 See the
1756 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
1757 section for more information.
1758 </para>
1759 </section>
1760
1761 <section id='migration-1.7-autotools-class-changes'>
1762 <title>Autotools Class Changes</title>
1763
1764 <para>
1765 The following
1766 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
1767 class changes occurred:
1768 <itemizedlist>
1769 <listitem><para><emphasis>
1770 A separate build directory is now used by default:</emphasis>
1771 The <filename>autotools</filename> class has been changed
1772 to use a directory for building
1773 (<link linkend='var-B'><filename>B</filename></link>),
1774 which is separate from the source directory
1775 (<link linkend='var-S'><filename>S</filename></link>).
1776 This is commonly referred to as
1777 <filename>B != S</filename>, or an out-of-tree build.</para>
1778 <para>If the software being built is already capable of
1779 building in a directory separate from the source, you
1780 do not need to do anything.
1781 However, if the software is not capable of being built
1782 in this manner, you will
1783 need to either patch the software so that it can build
1784 separately, or you will need to change the recipe to
1785 inherit the
1786 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1787 class instead of the <filename>autotools</filename> or
1788 <filename>autotools_stage</filename> classes.
1789 </para></listitem>
1790 <listitem><para><emphasis>
1791 The <filename>--foreign</filename> option is
1792 no longer passed to <filename>automake</filename> when
1793 running <filename>autoconf</filename>:</emphasis>
1794 This option tells <filename>automake</filename> that a
1795 particular software package does not follow the GNU
1796 standards and therefore should not be expected
1797 to distribute certain files such as
1798 <filename>ChangeLog</filename>,
1799 <filename>AUTHORS</filename>, and so forth.
1800 Because the majority of upstream software packages already
1801 tell <filename>automake</filename> to enable foreign mode
1802 themselves, the option is mostly superfluous.
1803 However, some recipes will need patches for this change.
1804 You can easily make the change by patching
1805 <filename>configure.ac</filename> so that it passes
1806 "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>.
1807 See
1808 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink>
1809 for an example showing how to make the patch.
1810 </para></listitem>
1811 </itemizedlist>
1812 </para>
1813 </section>
1814
1815 <section id='migration-1.7-binary-configuration-scripts-disabled'>
1816 <title>Binary Configuration Scripts Disabled</title>
1817
1818 <para>
1819 Some of the core recipes that package binary configuration scripts
1820 now disable the scripts due to the
1821 scripts previously requiring error-prone path substitution.
1822 Software that links against these libraries using these scripts
1823 should use the much more robust <filename>pkg-config</filename>
1824 instead.
1825 The list of recipes changed in this version (and their
1826 configuration scripts) is as follows:
1827 <literallayout class='monospaced'>
1828 directfb (directfb-config)
1829 freetype (freetype-config)
1830 gpgme (gpgme-config)
1831 libassuan (libassuan-config)
1832 libcroco (croco-6.0-config)
1833 libgcrypt (libgcrypt-config)
1834 libgpg-error (gpg-error-config)
1835 libksba (ksba-config)
1836 libpcap (pcap-config)
1837 libpcre (pcre-config)
1838 libpng (libpng-config, libpng16-config)
1839 libsdl (sdl-config)
1840 libusb-compat (libusb-config)
1841 libxml2 (xml2-config)
1842 libxslt (xslt-config)
1843 ncurses (ncurses-config)
1844 neon (neon-config)
1845 npth (npth-config)
1846 pth (pth-config)
1847 taglib (taglib-config)
1848 </literallayout>
1849 Additionally, support for <filename>pkg-config</filename> has been
1850 added to some recipes in the previous list in the rare cases
1851 where the upstream software package does not already provide
1852 it.
1853 </para>
1854 </section>
1855
1856 <section id='migration-1.7-glibc-replaces-eglibc'>
1857 <title><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></title>
1858
1859 <para>
1860 Because <filename>eglibc</filename> and
1861 <filename>glibc</filename> were already fairly close, this
1862 replacement should not require any significant changes to other
1863 software that links to <filename>eglibc</filename>.
1864 However, there were a number of minor changes in
1865 <filename>glibc 2.20</filename> upstream that could require
1866 patching some software (e.g. the removal of the
1867 <filename>_BSD_SOURCE</filename> feature test macro).
1868 </para>
1869
1870 <para>
1871 <filename>glibc 2.20</filename> requires version 2.6.32 or greater
1872 of the Linux kernel.
1873 Thus, older kernels will no longer be usable in conjunction with it.
1874 </para>
1875
1876 <para>
1877 For full details on the changes in <filename>glibc 2.20</filename>,
1878 see the upstream release notes
1879 <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>.
1880 </para>
1881 </section>
1882
1883 <section id='migration-1.7-kernel-module-autoloading'>
1884 <title>Kernel Module Autoloading</title>
1885
1886 <para>
1887 The
1888 <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link>
1889 variable is now deprecated and a new
1890 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
1891 variable should be used instead.
1892 Also,
1893 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
1894 must now be used in conjunction with a new
1895 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
1896 variable.
1897 The new variables no longer require you to specify the module name
1898 as part of the variable name.
1899 This change not only simplifies usage but also allows the values
1900 of these variables to be appropriately incorporated into task
1901 signatures and thus trigger the appropriate tasks to re-execute
1902 when changed.
1903 You should replace any references to
1904 <filename>module_autoload_*</filename> with
1905 <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules
1906 for which <filename>module_conf_*</filename> is specified to
1907 <filename>KERNEL_MODULE_PROBECONF</filename>.
1908 </para>
1909 </section>
1910
1911 <section id='migration-1.7-qa-check-changes'>
1912 <title>QA Check Changes</title>
1913
1914 <para>
1915 The following changes have occurred to the QA check process:
1916 <itemizedlist>
1917 <listitem><para>
1918 Additional QA checks <filename>file-rdeps</filename>
1919 and <filename>build-deps</filename> have been added in
1920 order to verify that file dependencies are satisfied
1921 (e.g. package contains a script requiring
1922 <filename>/bin/bash</filename>) and build-time dependencies
1923 are declared, respectively.
1924 For more information, please see the
1925 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1926 chapter.
1927 </para></listitem>
1928 <listitem><para>
1929 Package QA checks are now performed during a new
1930 <link linkend='ref-tasks-package_qa'><filename>do_package_qa</filename></link>
1931 task rather than being part of the
1932 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
1933 task.
1934 This allows more parallel execution.
1935 This change is unlikely to be an issue except for highly
1936 customized recipes that disable packaging tasks themselves
1937 by marking them as <filename>noexec</filename>.
1938 For those packages, you will need to disable the
1939 <filename>do_package_qa</filename> task as well.
1940 </para></listitem>
1941 <listitem><para>
1942 Files being overwritten during the
1943 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
1944 task now trigger an error instead of a warning.
1945 Recipes should not be overwriting files written to the
1946 sysroot by other recipes.
1947 If you have these types of recipes, you need to alter them
1948 so that they do not overwrite these files.</para>
1949 <para>You might now receive this error after changes in
1950 configuration or metadata resulting in orphaned files
1951 being left in the sysroot.
1952 If you do receive this error, the way to resolve the issue
1953 is to delete your
1954 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1955 or to move it out of the way and then re-start the build.
1956 Anything that has been fully built up to that point and
1957 does not need rebuilding will be restored from the shared
1958 state cache and the rest of the build will be able to
1959 proceed as normal.
1960 </para></listitem>
1961 </itemizedlist>
1962 </para>
1963 </section>
1964
1965 <section id='migration-1.7-removed-recipes'>
1966 <title>Removed Recipes</title>
1967
1968 <para>
1969 The following recipes have been removed:
1970 <itemizedlist>
1971 <listitem><para>
1972 <filename>x-load</filename>:
1973 This recipe has been superseded by
1974 U-boot SPL for all Cortex-based TI SoCs.
1975 For legacy boards, the <filename>meta-ti</filename>
1976 layer, which contains a maintained recipe, should be used
1977 instead.
1978 </para></listitem>
1979 <listitem><para>
1980 <filename>ubootchart</filename>:
1981 This recipe is obsolete.
1982 A <filename>bootchart2</filename> recipe has been added
1983 to functionally replace it.
1984 </para></listitem>
1985 <listitem><para>
1986 <filename>linux-yocto 3.4</filename>:
1987 Support for the linux-yocto 3.4 kernel has been dropped.
1988 Support for the 3.10 and 3.14 kernels remains, while
1989 support for version 3.17 has been added.
1990 </para></listitem>
1991 <listitem><para>
1992 <filename>eglibc</filename> has been removed in favor of
1993 <filename>glibc</filename>.
1994 See the
1995 "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>"
1996 section for more information.
1997 </para></listitem>
1998 </itemizedlist>
1999 </para>
2000 </section>
2001
2002 <section id='migration-1.7-miscellaneous-changes'>
2003 <title>Miscellaneous Changes</title>
2004
2005 <para>
2006 The following miscellaneous change occurred:
2007 <itemizedlist>
2008 <listitem><para>
2009 The build history feature now writes
2010 <filename>build-id.txt</filename> instead of
2011 <filename>build-id</filename>.
2012 Additionally, <filename>build-id.txt</filename>
2013 now contains the full build header as printed by
2014 BitBake upon starting the build.
2015 You should manually remove old "build-id" files from your
2016 existing build history repositories to avoid confusion.
2017 For information on the build history feature, see the
2018 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
2019 section in the Yocto Project Development Tasks Manual.
2020 </para></listitem>
2021 </itemizedlist>
2022 </para>
2023 </section>
2024</section>
2025
2026<section id='moving-to-the-yocto-project-1.8-release'>
2027 <title>Moving to the Yocto Project 1.8 Release</title>
2028
2029 <para>
2030 This section provides migration information for moving to the
2031 Yocto Project 1.8 Release from the prior release.
2032 </para>
2033
2034 <section id='migration-1.8-removed-recipes'>
2035 <title>Removed Recipes</title>
2036
2037 <para>
2038 The following recipes have been removed:
2039 <itemizedlist>
2040 <listitem><para><filename>owl-video</filename>:
2041 Functionality replaced by <filename>gst-player</filename>.
2042 </para></listitem>
2043 <listitem><para><filename>gaku</filename>:
2044 Functionality replaced by <filename>gst-player</filename>.
2045 </para></listitem>
2046 <listitem><para><filename>gnome-desktop</filename>:
2047 This recipe is now available in
2048 <filename>meta-gnome</filename> and is no longer needed.
2049 </para></listitem>
2050 <listitem><para><filename>gsettings-desktop-schemas</filename>:
2051 This recipe is now available in
2052 <filename>meta-gnome</filename> and is no longer needed.
2053 </para></listitem>
2054 <listitem><para><filename>python-argparse</filename>:
2055 The <filename>argparse</filename> module is already
2056 provided in the default Python distribution in a
2057 package named <filename>python-argparse</filename>.
2058 Consequently, the separate
2059 <filename>python-argparse</filename> recipe is no
2060 longer needed.
2061 </para></listitem>
2062 <listitem><para><filename>telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control</filename>:
2063 All these recipes have moved to
2064 <filename>meta-oe</filename> and are consequently no
2065 longer needed by any recipes in OpenEmbedded-Core.
2066 </para></listitem>
2067 <listitem><para><filename>linux-yocto_3.10</filename> and <filename>linux-yocto_3.17</filename>:
2068 Support for the linux-yocto 3.10 and 3.17 kernels has been
2069 dropped.
2070 Support for the 3.14 kernel remains, while support for
2071 3.19 kernel has been added.
2072 </para></listitem>
2073 <listitem><para><filename>poky-feed-config-opkg</filename>:
2074 This recipe has become obsolete and is no longer needed.
2075 Use <filename>distro-feed-config</filename> from
2076 <filename>meta-oe</filename> instead.
2077 </para></listitem>
2078 <listitem><para><filename>libav 0.8.x</filename>:
2079 <filename>libav 9.x</filename> is now used.
2080 </para></listitem>
2081 <listitem><para><filename>sed-native</filename>:
2082 No longer needed.
2083 A working version of <filename>sed</filename> is expected
2084 to be provided by the host distribution.
2085 </para></listitem>
2086 </itemizedlist>
2087 </para>
2088 </section>
2089
2090 <section id='migration-1.8-bluez'>
2091 <title>BlueZ 4.x / 5.x Selection</title>
2092
2093 <para>
2094 Proper built-in support for selecting BlueZ 5.x in preference
2095 to the default of 4.x now exists.
2096 To use BlueZ 5.x, simply add "bluez5" to your
2097 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2098 value.
2099 If you had previously added append files
2100 (<filename>*.bbappend</filename>) to make this selection, you can
2101 now remove them.
2102 </para>
2103
2104 <para>
2105 Additionally, a <filename>bluetooth</filename> class has been added
2106 to make selection of the appropriate bluetooth support within a
2107 recipe a little easier.
2108 If you wish to make use of this class in a recipe, add something
2109 such as the following:
2110 <literallayout class='monospaced'>
2111 inherit bluetooth
2112 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
2113 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
2114 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
2115 </literallayout>
2116 </para>
2117 </section>
2118
2119 <section id='migration-1.8-kernel-build-changes'>
2120 <title>Kernel Build Changes</title>
2121
2122 <para>
2123 The kernel build process was changed to place the source
2124 in a common shared work area and to place build artifacts
2125 separately in the source code tree.
2126 In theory, migration paths have been provided for most common
2127 usages in kernel recipes but this might not work in all cases.
2128 In particular, users need to ensure that
2129 <filename>${S}</filename> (source files) and
2130 <filename>${B}</filename> (build artifacts) are used
2131 correctly in functions such as
2132 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2133 and
2134 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
2135 For kernel recipes that do not inherit from
2136 <filename>kernel-yocto</filename> or include
2137 <filename>linux-yocto.inc</filename>, you might wish to
2138 refer to the <filename>linux.inc</filename> file in the
2139 <filename>meta-oe</filename> layer for the kinds of changes you
2140 need to make.
2141 For reference, here is the
2142 <ulink url='http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee'>commit</ulink>
2143 where the <filename>linux.inc</filename> file in
2144 <filename>meta-oe</filename> was updated.
2145 </para>
2146
2147 <para>
2148 Recipes that rely on the kernel source code and do not inherit
2149 the module classes might need to add explicit dependencies on
2150 the <filename>do_shared_workdir</filename> kernel task, for example:
2151 <literallayout class='monospaced'>
2152 do_configure[depends] += "virtual/kernel:do_shared_workdir"
2153 </literallayout>
2154 </para>
2155 </section>
2156
2157 <section id='migration-1.8-ssl'>
2158 <title>SSL 3.0 is Now Disabled in OpenSSL</title>
2159
2160 <para>
2161 SSL 3.0 is now disabled when building OpenSSL.
2162 Disabling SSL 3.0 avoids any lingering instances of the POODLE
2163 vulnerability.
2164 If you feel you must re-enable SSL 3.0, then you can add an
2165 append file (<filename>*.bbappend</filename>) for the
2166 <filename>openssl</filename> recipe to remove "-no-ssl3"
2167 from
2168 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>.
2169 </para>
2170 </section>
2171
2172 <section id='migration-1.8-default-sysroot-poisoning'>
2173 <title>Default Sysroot Poisoning</title>
2174
2175 <para>
2176 <filename>gcc's</filename> default sysroot and include directories
2177 are now "poisoned".
2178 In other words, the sysroot and include directories are being
2179 redirected to a non-existent location in order to catch when
2180 host directories are being used due to the correct options not
2181 being passed.
2182 This poisoning applies both to the cross-compiler used within the
2183 build and to the cross-compiler produced in the SDK.
2184 </para>
2185
2186 <para>
2187 If this change causes something in the build to fail, it almost
2188 certainly means the various compiler flags and commands are not
2189 being passed correctly to the underlying piece of software.
2190 In such cases, you need to take corrective steps.
2191 </para>
2192 </section>
2193
2194 <section id='migration-1.8-rebuild-improvements'>
2195 <title>Rebuild Improvements</title>
2196
2197 <para>
2198 Changes have been made to the
2199 <link linkend='ref-classes-base'><filename>base</filename></link>,
2200 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>,
2201 and
2202 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
2203 classes to clean out generated files when the
2204 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2205 task needs to be re-executed.
2206 </para>
2207
2208 <para>
2209 One of the improvements is to attempt to run "make clean" during
2210 the <filename>do_configure</filename> task if a
2211 <filename>Makefile</filename> exists.
2212 Some software packages do not provide a working clean target
2213 within their make files.
2214 If you have such recipes, you need to set
2215 <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link>
2216 to "1" within the recipe, for example:
2217 <literallayout class='monospaced'>
2218 CLEANBROKEN = "1"
2219 </literallayout>
2220 </para>
2221 </section>
2222
2223 <section id='migration-1.8-qa-check-and-validation-changes'>
2224 <title>QA Check and Validation Changes</title>
2225
2226 <para>
2227 The following QA Check and Validation Changes have occurred:
2228 <itemizedlist>
2229 <listitem><para>
2230 Usage of <filename>PRINC</filename>
2231 previously triggered a warning.
2232 It now triggers an error.
2233 You should remove any remaining usage of
2234 <filename>PRINC</filename> in any recipe or append file.
2235 </para></listitem>
2236 <listitem><para>
2237 An additional QA check has been added to detect usage of
2238 <filename>${D}</filename> in
2239 <link linkend='var-FILES'><filename>FILES</filename></link>
2240 values where
2241 <link linkend='var-D'><filename>D</filename></link> values
2242 should not be used at all.
2243 The same check ensures that <filename>$D</filename> is used
2244 in
2245 <filename>pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm</filename>
2246 functions instead of <filename>${D}</filename>.
2247 </para></listitem>
2248 <listitem><para>
2249 <link linkend='var-S'><filename>S</filename></link> now
2250 needs to be set to a valid value within a recipe.
2251 If <filename>S</filename> is not set in the recipe, the
2252 directory is not automatically created.
2253 If <filename>S</filename> does not point to a directory
2254 that exists at the time the
2255 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
2256 task finishes, a warning will be shown.
2257 </para></listitem>
2258 <listitem><para>
2259 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2260 is now validated for correct formatting of multiple
2261 licenses.
2262 If the format is invalid (e.g. multiple licenses are
2263 specified with no operators to specify how the multiple
2264 licenses interact), then a warning will be shown.
2265 </para></listitem>
2266 </itemizedlist>
2267 </para>
2268 </section>
2269
2270 <section id='migration-1.8-miscellaneous-changes'>
2271 <title>Miscellaneous Changes</title>
2272
2273 <para>
2274 The following miscellaneous changes have occurred:
2275 <itemizedlist>
2276 <listitem><para>
2277 The <filename>send-error-report</filename> script now
2278 expects a "-s" option to be specified before the server
2279 address.
2280 This assumes a server address is being specified.
2281 </para></listitem>
2282 <listitem><para>
2283 The <filename>oe-pkgdata-util</filename> script now
2284 expects a "-p" option to be specified before the
2285 <filename>pkgdata</filename> directory, which is now
2286 optional.
2287 If the <filename>pkgdata</filename> directory is not
2288 specified, the script will run BitBake to query
2289 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
2290 from the build environment.
2291 </para></listitem>
2292 </itemizedlist>
2293 </para>
2294 </section>
2295</section>
2296
2297<section id='moving-to-the-yocto-project-2.0-release'>
2298 <title>Moving to the Yocto Project 2.0 Release</title>
2299
2300 <para>
2301 This section provides migration information for moving to the
2302 Yocto Project 2.0 Release from the prior release.
2303 </para>
2304
2305 <section id='migration-2.0-gcc-5'>
2306 <title>GCC 5</title>
2307
2308 <para>
2309 The default compiler is now GCC 5.2.
2310 This change has required fixes for compilation errors in a number
2311 of other recipes.
2312 </para>
2313
2314 <para>
2315 One important example is a fix for when the Linux kernel freezes at
2316 boot time on ARM when built with GCC 5.
2317 If you are using your own kernel recipe or source tree and
2318 building for ARM, you will likely need to apply this
2319 <ulink url='https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit?id=a077224fd35b2f7fbc93f14cf67074fc792fbac2'>patch</ulink>.
2320 The standard <filename>linux-yocto</filename> kernel source tree
2321 already has a workaround for the same issue.
2322 </para>
2323
2324 <para>
2325 For further details, see
2326 <ulink url='https://gcc.gnu.org/gcc-5/changes.html'></ulink> and
2327 the porting guide at
2328 <ulink url='https://gcc.gnu.org/gcc-5/porting_to.html'></ulink>.
2329 </para>
2330
2331 <para>
2332 Alternatively, you can switch back to GCC 4.9 or 4.8 by
2333 setting <filename>GCCVERSION</filename> in your configuration,
2334 as follows:
2335 <literallayout class='monospaced'>
2336 GCCVERSION = "4.9%"
2337 </literallayout>
2338 </para>
2339 </section>
2340
2341 <section id='migration-2.0-Gstreamer-0.10-removed'>
2342 <title>Gstreamer 0.10 Removed</title>
2343
2344 <para>
2345 Gstreamer 0.10 has been removed in favor of Gstreamer 1.x.
2346 As part of the change, recipes for Gstreamer 0.10 and related
2347 software are now located
2348 in <filename>meta-multimedia</filename>.
2349 This change results in Qt4 having Phonon and Gstreamer
2350 support in QtWebkit disabled by default.
2351 </para>
2352 </section>
2353
2354 <section id='migration-2.0-removed-recipes'>
2355 <title>Removed Recipes</title>
2356
2357 <para>
2358 The following recipes have been moved or removed:
2359 <itemizedlist>
2360 <listitem><para>
2361 <filename>bluez4</filename>: The recipe is obsolete and
2362 has been moved due to <filename>bluez5</filename>
2363 becoming fully integrated.
2364 The <filename>bluez4</filename> recipe now resides in
2365 <filename>meta-oe</filename>.
2366 </para></listitem>
2367 <listitem><para>
2368 <filename>gamin</filename>: The recipe is obsolete and
2369 has been removed.
2370 </para></listitem>
2371 <listitem><para>
2372 <filename>gnome-icon-theme</filename>: The recipe's
2373 functionally has been replaced by
2374 <filename>adwaita-icon-theme</filename>.
2375 </para></listitem>
2376 <listitem><para>
2377 Gstreamer 0.10 Recipes: Recipes for Gstreamer 0.10 have
2378 been removed in favor of the recipes for Gstreamer 1.x.
2379 </para></listitem>
2380 <listitem><para>
2381 <filename>insserv</filename>: The recipe is obsolete and
2382 has been removed.
2383 </para></listitem>
2384 <listitem><para>
2385 <filename>libunique</filename>: The recipe is no longer
2386 used and has been moved to <filename>meta-oe</filename>.
2387 </para></listitem>
2388 <listitem><para>
2389 <filename>midori</filename>: The recipe's functionally
2390 has been replaced by <filename>epiphany</filename>.
2391 </para></listitem>
2392 <listitem><para>
2393 <filename>python-gst</filename>: The recipe is obsolete
2394 and has been removed since it only contains bindings for
2395 Gstreamer 0.10.
2396 </para></listitem>
2397 <listitem><para>
2398 <filename>qt-mobility</filename>: The recipe is obsolete and
2399 has been removed since it requires
2400 <filename>Gstreamer 0.10</filename>, which has been
2401 replaced.
2402 </para></listitem>
2403 <listitem><para>
2404 <filename>subversion</filename>: All 1.6.x versions of this
2405 recipe have been removed.
2406 </para></listitem>
2407 <listitem><para>
2408 <filename>webkit-gtk</filename>: The older 1.8.3 version
2409 of this recipe has been removed in favor of
2410 <filename>webkitgtk</filename>.
2411 </para></listitem>
2412 </itemizedlist>
2413 </para>
2414 </section>
2415
2416 <section id='migration-2.0-bitbake-datastore-improvements'>
2417 <title>BitBake datastore improvements</title>
2418
2419 <para>
2420 The method by which BitBake's datastore handles overrides has
2421 changed.
2422 Overrides are now applied dynamically and
2423 <filename>bb.data.update_data()</filename> is now a no-op.
2424 Thus, <filename>bb.data.update_data()</filename> is no longer
2425 required in order to apply the correct overrides.
2426 In practice, this change is unlikely to require any changes to
2427 Metadata.
2428 However, these minor changes in behavior exist:
2429 <itemizedlist>
2430 <listitem><para>
2431 All potential overrides are now visible in the variable
2432 history as seen when you run the following:
2433 <literallayout class='monospaced'>
2434 $ bitbake -e
2435 </literallayout>
2436 </para></listitem>
2437 <listitem><para>
2438 <filename>d.delVar('</filename><replaceable>VARNAME</replaceable><filename>')</filename> and
2439 <filename>d.setVar('</filename><replaceable>VARNAME</replaceable><filename>', None)</filename>
2440 result in the variable and all of its overrides being
2441 cleared out.
2442 Before the change, only the non-overridden values
2443 were cleared.
2444 </para></listitem>
2445 </itemizedlist>
2446 </para>
2447 </section>
2448
2449 <section id='migration-2.0-shell-message-function-changes'>
2450 <title>Shell Message Function Changes</title>
2451
2452 <para>
2453 The shell versions of the BitBake message functions (i.e.
2454 <filename>bbdebug</filename>, <filename>bbnote</filename>,
2455 <filename>bbwarn</filename>, <filename>bbplain</filename>,
2456 <filename>bberror</filename>, and <filename>bbfatal</filename>)
2457 are now connected through to their BitBake equivalents
2458 <filename>bb.debug()</filename>, <filename>bb.note()</filename>,
2459 <filename>bb.warn()</filename>, <filename>bb.plain()</filename>,
2460 <filename>bb.error()</filename>, and
2461 <filename>bb.fatal()</filename>, respectively.
2462 Thus, those message functions that you would expect to be printed
2463 by the BitBake UI are now actually printed.
2464 In practice, this change means two things:
2465 <itemizedlist>
2466 <listitem><para>
2467 If you now see messages on the console that you did not
2468 previously see as a result of this change, you might
2469 need to clean up the calls to
2470 <filename>bbwarn</filename>, <filename>bberror</filename>,
2471 and so forth.
2472 Or, you might want to simply remove the calls.
2473 </para></listitem>
2474 <listitem><para>
2475 The <filename>bbfatal</filename> message function now
2476 suppresses the full error log in the UI, which means any
2477 calls to <filename>bbfatal</filename> where you still
2478 wish to see the full error log should be replaced by
2479 <filename>die</filename> or
2480 <filename>bbfatal_log</filename>.
2481 </para></listitem>
2482 </itemizedlist>
2483 </para>
2484 </section>
2485
2486 <section id='migration-2.0-extra-development-debug-package-cleanup'>
2487 <title>Extra Development/Debug Package Cleanup</title>
2488
2489 <para>
2490 The following recipes have had extra
2491 <filename>dev/dbg</filename> packages removed:
2492 <itemizedlist>
2493 <listitem><para>
2494 <filename>acl</filename>
2495 </para></listitem>
2496 <listitem><para>
2497 <filename>apmd</filename>
2498 </para></listitem>
2499 <listitem><para>
2500 <filename>aspell</filename>
2501 </para></listitem>
2502 <listitem><para>
2503 <filename>attr</filename>
2504 </para></listitem>
2505 <listitem><para>
2506 <filename>augeas</filename>
2507 </para></listitem>
2508 <listitem><para>
2509 <filename>bzip2</filename>
2510 </para></listitem>
2511 <listitem><para>
2512 <filename>cogl</filename>
2513 </para></listitem>
2514 <listitem><para>
2515 <filename>curl</filename>
2516 </para></listitem>
2517 <listitem><para>
2518 <filename>elfutils</filename>
2519 </para></listitem>
2520 <listitem><para>
2521 <filename>gcc-target</filename>
2522 </para></listitem>
2523 <listitem><para>
2524 <filename>libgcc</filename>
2525 </para></listitem>
2526 <listitem><para>
2527 <filename>libtool</filename>
2528 </para></listitem>
2529 <listitem><para>
2530 <filename>libxmu</filename>
2531 </para></listitem>
2532 <listitem><para>
2533 <filename>opkg</filename>
2534 </para></listitem>
2535 <listitem><para>
2536 <filename>pciutils</filename>
2537 </para></listitem>
2538 <listitem><para>
2539 <filename>rpm</filename>
2540 </para></listitem>
2541 <listitem><para>
2542 <filename>sysfsutils</filename>
2543 </para></listitem>
2544 <listitem><para>
2545 <filename>tiff</filename>
2546 </para></listitem>
2547 <listitem><para>
2548 <filename>xz</filename>
2549 </para></listitem>
2550 </itemizedlist>
2551 All of the above recipes now conform to the standard packaging
2552 scheme where a single <filename>-dev</filename>,
2553 <filename>-dbg</filename>, and <filename>-staticdev</filename>
2554 package exists per recipe.
2555 </para>
2556 </section>
2557
2558 <section id='migration-2.0-recipe-maintenance-tracking-data-moved-to-oe-core'>
2559 <title>Recipe Maintenance Tracking Data Moved to OE-Core</title>
2560
2561 <para>
2562 Maintenance tracking data for recipes that was previously part
2563 of <filename>meta-yocto</filename> has been moved to
2564 <link linkend='oe-core'>OE-Core</link>.
2565 The change includes <filename>package_regex.inc</filename> and
2566 <filename>distro_alias.inc</filename>, which are typically enabled
2567 when using the <filename>distrodata</filename> class.
2568 Additionally, the contents of
2569 <filename>upstream_tracking.inc</filename> has now been split out
2570 to the relevant recipes.
2571 </para>
2572 </section>
2573
2574 <section id='migration-2.0-automatic-stale-sysroot-file-cleanup'>
2575 <title>Automatic Stale Sysroot File Cleanup</title>
2576
2577 <para>
2578 Stale files from recipes that no longer exist in the current
2579 configuration are now automatically removed from
2580 sysroot as well as removed from
2581 any other place managed by shared state.
2582 This automatic cleanup means that the build system now properly
2583 handles situations such as renaming the build system side of
2584 recipes, removal of layers from
2585 <filename>bblayers.conf</filename>, and
2586 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
2587 changes.
2588 </para>
2589
2590 <para>
2591 Additionally, work directories for old versions of recipes are
2592 now pruned.
2593 If you wish to disable pruning old work directories, you can set
2594 the following variable in your configuration:
2595 <literallayout class='monospaced'>
2596 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
2597 </literallayout>
2598 </para>
2599 </section>
2600
2601 <section id='migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source'>
2602 <title><filename>linux-yocto</filename> Kernel Metadata Repository Now Split from Source</title>
2603
2604 <para>
2605 The <filename>linux-yocto</filename> tree has up to now been a
2606 combined set of kernel changes and configuration (meta) data
2607 carried in a single tree.
2608 While this format is effective at keeping kernel configuration and
2609 source modifications synchronized, it is not always obvious to
2610 developers how to manipulate the Metadata as compared to the
2611 source.
2612 </para>
2613
2614 <para>
2615 Metadata processing has now been removed from the
2616 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
2617 class and the external Metadata repository
2618 <filename>yocto-kernel-cache</filename>, which has always been used
2619 to seed the <filename>linux-yocto</filename> "meta" branch.
2620 This separate <filename>linux-yocto</filename> cache repository
2621 is now the primary location for this data.
2622 Due to this change, <filename>linux-yocto</filename> is no longer
2623 able to process combined trees.
2624 Thus, if you need to have your own combined kernel repository,
2625 you must do the split there as well and update your recipes
2626 accordingly.
2627 See the <filename>meta/recipes-kernel/linux/linux-yocto_4.1.bb</filename>
2628 recipe for an example.
2629 </para>
2630 </section>
2631
2632 <section id='migration-2.0-additional-qa-checks'>
2633 <title>Additional QA checks</title>
2634
2635 <para>
2636 The following QA checks have been added:
2637 <itemizedlist>
2638 <listitem><para>
2639 Added a "host-user-contaminated" check for ownership
2640 issues for packaged files outside of
2641 <filename>/home</filename>.
2642 The check looks for files that are incorrectly owned by the
2643 user that ran BitBake instead of owned by a valid user in
2644 the target system.
2645 </para></listitem>
2646 <listitem><para>
2647 Added an "invalid-chars" check for invalid (non-UTF8)
2648 characters in recipe metadata variable values
2649 (i.e.
2650 <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>,
2651 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>,
2652 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>,
2653 and
2654 <link linkend='var-SECTION'><filename>SECTION</filename></link>).
2655 Some package managers do not support these characters.
2656 </para></listitem>
2657 <listitem><para>
2658 Added an "invalid-packageconfig" check for any options
2659 specified in
2660 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
2661 that do not match any <filename>PACKAGECONFIG</filename>
2662 option defined for the recipe.
2663 </para></listitem>
2664 </itemizedlist>
2665 </para>
2666 </section>
2667
2668 <section id='migration-2.0-miscellaneous'>
2669 <title>Miscellaneous Changes</title>
2670
2671 <para>
2672 These additional changes exist:
2673 <itemizedlist>
2674 <listitem><para>
2675 <filename>gtk-update-icon-cache</filename> has been
2676 renamed to <filename>gtk-icon-utils</filename>.
2677 </para></listitem>
2678 <listitem><para>
2679 The <filename>tools-profile</filename>
2680 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
2681 item as well as its corresponding packagegroup and
2682 <filename>packagegroup-core-tools-profile</filename> no
2683 longer bring in <filename>oprofile</filename>.
2684 Bringing in <filename>oprofile</filename> was originally
2685 added to aid compilation on resource-constrained
2686 targets.
2687 However, this aid has not been widely used and is not
2688 likely to be used going forward due to the more powerful
2689 target platforms and the existence of better
2690 cross-compilation tools.
2691 </para></listitem>
2692 <listitem><para>
2693 The
2694 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
2695 variable's default value now specifies
2696 <filename>ext4</filename> instead of
2697 <filename>ext3</filename>.
2698 </para></listitem>
2699 <listitem><para>
2700 All support for the <filename>PRINC</filename>
2701 variable has been removed.
2702 </para></listitem>
2703 <listitem><para>
2704 The <filename>packagegroup-core-full-cmdline</filename>
2705 packagegroup no longer brings in
2706 <filename>lighttpd</filename> due to the fact that
2707 bringing in <filename>lighttpd</filename> is not really in
2708 line with the packagegroup's purpose, which is to add full
2709 versions of command-line tools that by default are
2710 provided by <filename>busybox</filename>.
2711 </para></listitem>
2712 </itemizedlist>
2713 </para>
2714 </section>
2715</section>
2716
2717<section id='moving-to-the-yocto-project-2.1-release'>
2718 <title>Moving to the Yocto Project 2.1 Release</title>
2719
2720 <para>
2721 This section provides migration information for moving to the
2722 Yocto Project 2.1 Release from the prior release.
2723 </para>
2724
2725 <section id='migration-2.1-variable-expansion-in-python-functions'>
2726 <title>Variable Expansion in Python Functions</title>
2727
2728 <para>
2729 Variable expressions, such as
2730 <filename>${</filename><replaceable>VARNAME</replaceable><filename>}</filename>
2731 no longer expand automatically within Python functions.
2732 Suppressing expansion was done to allow Python functions to
2733 construct shell scripts or other code for situations in which you
2734 do not want such expressions expanded.
2735 For any existing code that relies on these expansions, you need to
2736 change the expansions to expand the value of individual
2737 variables through <filename>d.getVar()</filename>.
2738 To alternatively expand more complex expressions,
2739 use <filename>d.expand()</filename>.
2740 </para>
2741 </section>
2742
2743 <section id='migration-2.1-overrides-must-now-be-lower-case'>
2744 <title>Overrides Must Now be Lower-Case</title>
2745
2746 <para>
2747 The convention for overrides has always been for them to be
2748 lower-case characters.
2749 This practice is now a requirement as BitBake's datastore now
2750 assumes lower-case characters in order to give a slight performance
2751 boost during parsing.
2752 In practical terms, this requirement means that anything that ends
2753 up in
2754 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
2755 must now appear in lower-case characters (e.g. values for
2756 <filename>MACHINE</filename>, <filename>TARGET_ARCH</filename>,
2757 <filename>DISTRO</filename>, and also recipe names if
2758 <filename>_pn-</filename><replaceable>recipename</replaceable>
2759 overrides are to be effective).
2760 </para>
2761 </section>
2762
2763 <section id='migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory'>
2764 <title>Expand Parameter to <filename>getVar()</filename> and
2765 <filename>getVarFlag()</filename> is Now Mandatory</title>
2766
2767 <para>
2768 The expand parameter to <filename>getVar()</filename> and
2769 <filename>getVarFlag()</filename> previously defaulted to
2770 False if not specified.
2771 Now, however, no default exists so one must be specified.
2772 You must change any <filename>getVar()</filename> calls that
2773 do not specify the final expand parameter to calls that do specify
2774 the parameter.
2775 You can run the following <filename>sed</filename> command at the
2776 base of a layer to make this change:
2777 <literallayout class='monospaced'>
2778 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
2779 sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
2780 </literallayout>
2781 <note>
2782 The reason for this change is that it prepares the way for
2783 changing the default to True in a future Yocto Project release.
2784 This future change is a much more sensible default than False.
2785 However, the change needs to be made gradually as a sudden
2786 change of the default would potentially cause side-effects
2787 that would be difficult to detect.
2788 </note>
2789 </para>
2790 </section>
2791
2792 <section id='migration-2.1-makefile-environment-changes'>
2793 <title>Makefile Environment Changes</title>
2794
2795 <para>
2796 <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link>
2797 now defaults to "" instead of "-e MAKEFLAGS=".
2798 Setting <filename>EXTRA_OEMAKE</filename> to "-e MAKEFLAGS=" by
2799 default was a historical accident that has required many classes
2800 (e.g. <filename>autotools</filename>, <filename>module</filename>)
2801 and recipes to override this default in order to work with
2802 sensible build systems.
2803 When upgrading to the release, you must edit any recipe that
2804 relies upon this old default by either setting
2805 <filename>EXTRA_OEMAKE</filename> back to "-e MAKEFLAGS=" or by
2806 explicitly setting any required variable value overrides using
2807 <filename>EXTRA_OEMAKE</filename>, which is typically only needed
2808 when a Makefile sets a default value for a variable that is
2809 inappropriate for cross-compilation using the "=" operator rather
2810 than the "?=" operator.
2811 </para>
2812 </section>
2813
2814 <section id='migration-2.1-libexecdir-reverted-to-prefix-libexec'>
2815 <title><filename>libexecdir</filename> Reverted to <filename>${prefix}/libexec</filename></title>
2816
2817 <para>
2818 The use of <filename>${libdir}/${BPN}</filename> as
2819 <filename>libexecdir</filename> is different as compared to all
2820 other mainstream distributions, which either uses
2821 <filename>${prefix}/libexec</filename> or
2822 <filename>${libdir}</filename>.
2823 The use is also contrary to the GNU Coding Standards
2824 (i.e. <ulink url='https://www.gnu.org/prep/standards/html_node/Directory-Variables.html'></ulink>)
2825 that suggest <filename>${prefix}/libexec</filename> and also
2826 notes that any package-specific nesting should be done by the
2827 package itself.
2828 Finally, having <filename>libexecdir</filename> change between
2829 recipes makes it very difficult for different recipes to invoke
2830 binaries that have been installed into
2831 <filename>libexecdir</filename>.
2832 The Filesystem Hierarchy Standard
2833 (i.e. <ulink url='http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html'></ulink>)
2834 now recognizes the use of <filename>${prefix}/libexec/</filename>,
2835 giving distributions the choice between
2836 <filename>${prefix}/lib</filename> or
2837 <filename>${prefix}/libexec</filename> without breaking FHS.
2838 </para>
2839 </section>
2840
2841 <section id='migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files'>
2842 <title><filename>ac_cv_sizeof_off_t</filename> is No Longer Cached in Site Files</title>
2843
2844 <para>
2845 For recipes inheriting the
2846 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2847 class, <filename>ac_cv_sizeof_off_t</filename> is no longer cached
2848 in the site files for <filename>autoconf</filename>.
2849 The reason for this change is because the
2850 <filename>ac_cv_sizeof_off_t</filename> value is not necessarily
2851 static per architecture as was previously assumed.
2852 Rather, the value changes based on whether large file support is
2853 enabled.
2854 For most software that uses <filename>autoconf</filename>, this
2855 change should not be a problem.
2856 However, if you have a recipe that bypasses the standard
2857 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2858 task from the <filename>autotools</filename> class and the software
2859 the recipe is building uses a very old version of
2860 <filename>autoconf</filename>, the recipe might be incapable of
2861 determining the correct size of <filename>off_t</filename> during
2862 <filename>do_configure</filename>.
2863 </para>
2864
2865 <para>
2866 The best course of action is to patch the software as necessary
2867 to allow the default implementation from the
2868 <filename>autotools</filename> class to work such that
2869 <filename>autoreconf</filename> succeeds and produces a working
2870 configure script, and to remove the
2871 overridden <filename>do_configure</filename> task such that the
2872 default implementation does get used.
2873 </para>
2874 </section>
2875
2876 <section id='migration-2.1-image-generation-split-out-from-filesystem-generation'>
2877 <title>Image Generation is Now Split Out from Filesystem Generation</title>
2878
2879 <para>
2880 Previously, for image recipes the
2881 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
2882 task assembled the filesystem and then from that filesystem
2883 generated images.
2884 With this Yocto Project release, image generation is split into
2885 separate
2886 <link linkend='ref-tasks-image'><filename>do_image_*</filename></link>
2887 tasks for clarity both in operation and in the code.
2888 </para>
2889
2890 <para>
2891 For most cases, this change does not present any problems.
2892 However, if you have made customizations that directly modify the
2893 <filename>do_rootfs</filename> task or that mention
2894 <filename>do_rootfs</filename>, you might need to update those
2895 changes.
2896 In particular, if you had added any tasks after
2897 <filename>do_rootfs</filename>, you should make edits so that
2898 those tasks are after the
2899 <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link>
2900 task rather than after <filename>do_rootfs</filename>
2901 so that the your added tasks
2902 run at the correct time.
2903 </para>
2904
2905 <para>
2906 A minor part of this restructuring is that the post-processing
2907 definitions and functions have been moved from the
2908 <link linkend='ref-classes-image'><filename>image</filename></link>
2909 class to the
2910 <link linkend='ref-classes-rootfs*'><filename>rootfs-postcommands</filename></link>
2911 class.
2912 Functionally, however, they remain unchanged.
2913 </para>
2914 </section>
2915
2916 <section id='migration-2.1-removed-recipes'>
2917 <title>Removed Recipes</title>
2918
2919 <para>
2920 The following recipes have been removed in the 2.1 release:
2921 <itemizedlist>
2922 <listitem><para><filename>gcc</filename> version 4.8:
2923 Versions 4.9 and 5.3 remain.
2924 </para></listitem>
2925 <listitem><para><filename>qt4</filename>:
2926 All support for Qt 4.x has been moved out to a separate
2927 <filename>meta-qt4</filename> layer because Qt 4 is no
2928 longer supported upstream.
2929 </para></listitem>
2930 <listitem><para><filename>x11vnc</filename>:
2931 Moved to the <filename>meta-oe</filename> layer.
2932 </para></listitem>
2933 <listitem><para><filename>linux-yocto-3.14</filename>:
2934 No longer supported.
2935 </para></listitem>
2936 <listitem><para><filename>linux-yocto-3.19</filename>:
2937 No longer supported.
2938 </para></listitem>
2939 <listitem><para><filename>libjpeg</filename>:
2940 Replaced by the <filename>libjpeg-turbo</filename> recipe.
2941 </para></listitem>
2942 <listitem><para><filename>pth</filename>:
2943 Became obsolete.
2944 </para></listitem>
2945 <listitem><para><filename>liboil</filename>:
2946 Recipe is no longer needed and has been moved to the
2947 <filename>meta-multimedia</filename> layer.
2948 </para></listitem>
2949 <listitem><para><filename>gtk-theme-torturer</filename>:
2950 Recipe is no longer needed and has been moved to the
2951 <filename>meta-gnome</filename> layer.
2952 </para></listitem>
2953 <listitem><para><filename>gnome-mime-data</filename>:
2954 Recipe is no longer needed and has been moved to the
2955 <filename>meta-gnome</filename> layer.
2956 </para></listitem>
2957 <listitem><para><filename>udev</filename>:
2958 Replaced by the <filename>eudev</filename> recipe for
2959 compatibility when using <filename>sysvinit</filename>
2960 with newer kernels.
2961 </para></listitem>
2962 <listitem><para><filename>python-pygtk</filename>:
2963 Recipe became obsolete.
2964 </para></listitem>
2965 <listitem><para><filename>adt-installer</filename>:
2966 Recipe became obsolete.
2967 See the
2968 "<link linkend='migration-2.1-adt-removed'>ADT Removed</link>"
2969 section for more information.
2970 </para></listitem>
2971 </itemizedlist>
2972 </para>
2973 </section>
2974
2975 <section id='migration-2.1-class-changes'>
2976 <title>Class Changes</title>
2977
2978 <para>
2979 The following classes have changed:
2980 <itemizedlist>
2981 <listitem><para><filename>autotools_stage</filename>:
2982 Removed because the
2983 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2984 class now provides its functionality.
2985 Recipes that inherited from
2986 <filename>autotools_stage</filename> should now inherit
2987 from <filename>autotools</filename> instead.
2988 </para></listitem>
2989 <listitem><para><filename>boot-directdisk</filename>:
2990 Merged into the <filename>image-vm</filename>
2991 class.
2992 The <filename>boot-directdisk</filename> class was rarely
2993 directly used.
2994 Consequently, this change should not cause any issues.
2995 </para></listitem>
2996 <listitem><para><filename>bootimg</filename>:
2997 Merged into the
2998 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
2999 class.
3000 The <filename>bootimg</filename> class was rarely
3001 directly used.
3002 Consequently, this change should not cause any issues.
3003 </para></listitem>
3004 <listitem><para><filename>packageinfo</filename>:
3005 Removed due to its limited use by the Hob UI, which has
3006 itself been removed.
3007 </para></listitem>
3008 </itemizedlist>
3009 </para>
3010 </section>
3011
3012 <section id='migration-2.1-build-system-ui-changes'>
3013 <title>Build System User Interface Changes</title>
3014
3015 <para>
3016 The following changes have been made to the build system user
3017 interface:
3018 <itemizedlist>
3019 <listitem><para><emphasis>Hob GTK+-based UI</emphasis>:
3020 Removed because it is unmaintained and based on the
3021 outdated GTK+ 2 library.
3022 The Toaster web-based UI is much more capable and is
3023 actively maintained.
3024 See the
3025 "<ulink url='&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface'>Using the Toaster Web Interface</ulink>"
3026 section in the Toaster User Manual for more
3027 information on this interface.
3028 </para></listitem>
3029 <listitem><para><emphasis>"puccho" BitBake UI</emphasis>:
3030 Removed because is unmaintained and no longer useful.
3031 </para></listitem>
3032 </itemizedlist>
3033 </para>
3034 </section>
3035
3036 <section id='migration-2.1-adt-removed'>
3037 <title>ADT Removed</title>
3038
3039 <para>
3040 The Application Development Toolkit (ADT) has been removed
3041 because its functionality almost completely overlapped with the
3042 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink>
3043 and the
3044 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>.
3045 For information on these SDKs and how to build and use them, see the
3046 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
3047 manual.
3048 <note>
3049 The Yocto Project Eclipse IDE Plug-in is still supported and
3050 is not affected by this change.
3051 </note>
3052 </para>
3053 </section>
3054
3055 <section id='migration-2.1-poky-reference-distribution-changes'>
3056 <title>Poky Reference Distribution Changes</title>
3057
3058 <para>
3059 The following changes have been made for the Poky distribution:
3060 <itemizedlist>
3061 <listitem><para>
3062 The <filename>meta-yocto</filename> layer has been renamed
3063 to <filename>meta-poky</filename> to better match its
3064 purpose, which is to provide the Poky reference
3065 distribution.
3066 The <filename>meta-yocto-bsp</filename> layer retains its
3067 original name since it provides reference machines for
3068 the Yocto Project and it is otherwise unrelated to Poky.
3069 References to <filename>meta-yocto</filename> in your
3070 <filename>conf/bblayers.conf</filename> should
3071 automatically be updated, so you should not need to change
3072 anything unless you are relying on this naming elsewhere.
3073 </para></listitem>
3074 <listitem><para>
3075 The
3076 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
3077 class is now enabled by default in Poky.
3078 This class attempts to isolate the build system from the
3079 host distribution's C library and makes re-use of native
3080 shared state artifacts across different host distributions
3081 practical.
3082 With this class enabled, a tarball containing a pre-built
3083 C library is downloaded at the start of the build.</para>
3084
3085 <para>The <filename>uninative</filename> class is enabled
3086 through the
3087 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>
3088 file, which for those not using the Poky distribution, can
3089 include to easily enable the same functionality.</para>
3090
3091 <para>Alternatively, if you wish to build your own
3092 <filename>uninative</filename> tarball, you can do so by
3093 building the <filename>uninative-tarball</filename> recipe,
3094 making it available to your build machines
3095 (e.g. over HTTP/HTTPS) and setting a similar configuration
3096 as the one set by <filename>yocto-uninative.inc</filename>.
3097 </para></listitem>
3098 <listitem><para>
3099 Static library generation, for most cases, is now disabled
3100 by default in the Poky distribution.
3101 Disabling this generation saves some build time as well
3102 as the size used for build output artifacts.</para>
3103
3104 <para>Disabling this library generation is accomplished
3105 through a
3106 <filename>meta/conf/distro/include/no-static-libs.inc</filename>,
3107 which for those not using the Poky distribution can
3108 easily include to enable the same functionality.</para>
3109
3110 <para>Any recipe that needs to opt-out of having the
3111 "--disable-static" option specified on the configure
3112 command line either because it is not a supported option
3113 for the configure script or because static libraries are
3114 needed should set the following variable:
3115 <literallayout class='monospaced'>
3116 DISABLE_STATIC = ""
3117 </literallayout>
3118 </para></listitem>
3119 <listitem><para>
3120 The separate <filename>poky-tiny</filename> distribution
3121 now uses the musl C library instead of a heavily pared
3122 down <filename>glibc</filename>.
3123 Using musl results in a smaller
3124 distribution and facilitates much greater maintainability
3125 because musl is designed to have a small footprint.</para>
3126
3127 <para>If you have used <filename>poky-tiny</filename> and
3128 have customized the <filename>glibc</filename>
3129 configuration you will need to redo those customizations
3130 with musl when upgrading to the new release.
3131 </para></listitem>
3132 </itemizedlist>
3133 </para>
3134 </section>
3135
3136 <section id='migration-2.1-packaging-changes'>
3137 <title>Packaging Changes</title>
3138
3139 <para>
3140 The following changes have been made to packaging:
3141 <itemizedlist>
3142 <listitem><para>
3143 The <filename>runuser</filename> and
3144 <filename>mountpoint</filename> binaries, which were
3145 previously in the main <filename>util-linux</filename>
3146 package, have been split out into the
3147 <filename>util-linux-runuser</filename> and
3148 <filename>util-linux-mountpoint</filename> packages,
3149 respectively.
3150 </para></listitem>
3151 <listitem><para>
3152 The <filename>python-elementtree</filename> package has
3153 been merged into the <filename>python-xml</filename>
3154 package.
3155 </para></listitem>
3156 </itemizedlist>
3157 </para>
3158 </section>
3159
3160 <section id='migration-2.1-tuning-file-changes'>
3161 <title>Tuning File Changes</title>
3162
3163 <para>
3164 The following changes have been made to the tuning files:
3165 <itemizedlist>
3166 <listitem><para>
3167 The "no-thumb-interwork" tuning feature has been dropped
3168 from the ARM tune include files.
3169 Because interworking is required for ARM EABI, attempting
3170 to disable it through a tuning feature no longer makes
3171 sense.
3172 <note>
3173 Support for ARM OABI was deprecated in gcc 4.7.
3174 </note>
3175 </para></listitem>
3176 <listitem><para>
3177 The <filename>tune-cortexm*.inc</filename> and
3178 <filename>tune-cortexr4.inc</filename> files have been
3179 removed because they are poorly tested.
3180 Until the OpenEmbedded build system officially gains
3181 support for CPUs without an MMU, these tuning files would
3182 probably be better maintained in a separate layer
3183 if needed.
3184 </para></listitem>
3185 </itemizedlist>
3186 </para>
3187 </section>
3188
3189 <section id='migration-2.1-supporting-gobject-introspection'>
3190 <title>Supporting GObject Introspection</title>
3191
3192 <para>
3193 This release supports generation of GLib Introspective
3194 Repository (GIR) files through GObject introspection, which is
3195 the standard mechanism for accessing GObject-based software from
3196 runtime environments.
3197 You can enable, disable, and test the generation of this data.
3198 See the
3199 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support'>Enabling GObject Introspection Support</ulink>"
3200 section in the Yocto Project Development Tasks Manual
3201 for more information.
3202 </para>
3203 </section>
3204
3205 <section id='migration-2.1-miscellaneous-changes'>
3206 <title>Miscellaneous Changes</title>
3207
3208 <para>
3209 These additional changes exist:
3210 <itemizedlist>
3211 <listitem><para>
3212 The minimum Git version has been increased to 1.8.3.1.
3213 If your host distribution does not provide a sufficiently
3214 recent version, you can install the buildtools, which
3215 will provide it.
3216 See the
3217 "<link linkend='required-git-tar-python-and-gcc-versions'>Required Git, tar, Python and gcc Versions</link>"
3218 section for more information on the buildtools tarball.
3219 </para></listitem>
3220 <listitem><para>
3221 The buggy and incomplete support for the RPM version 4
3222 package manager has been removed.
3223 The well-tested and maintained support for RPM version 5
3224 remains.
3225 </para></listitem>
3226 <listitem><para>
3227 Previously, the following list of packages were removed
3228 if package-management was not in
3229 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>,
3230 regardless of any dependencies:
3231 <literallayout class='monospaced'>
3232 update-rc.d
3233 base-passwd
3234 shadow
3235 update-alternatives
3236 run-postinsts
3237 </literallayout>
3238 With the Yocto Project 2.1 release, these packages are only
3239 removed if "read-only-rootfs" is in
3240 <filename>IMAGE_FEATURES</filename>, since they might
3241 still be needed for a read-write image even in the absence
3242 of a package manager (e.g. if users need to be added,
3243 modified, or removed at runtime).
3244 </para></listitem>
3245 <listitem><para>
3246 The
3247 <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'><filename>devtool modify</filename></ulink>
3248 command now defaults to extracting the source since that
3249 is most commonly expected.
3250 The "-x" or "--extract" options are now no-ops.
3251 If you wish to provide your own existing source tree, you
3252 will now need to specify either the "-n" or
3253 "--no-extract" options when running
3254 <filename>devtool modify</filename>.
3255 </para></listitem>
3256 <listitem><para>
3257 If the formfactor for a machine is either not supplied
3258 or does not specify whether a keyboard is attached, then
3259 the default is to assume a keyboard is attached rather
3260 than assume no keyboard.
3261 This change primarily affects the Sato UI.
3262 </para></listitem>
3263 <listitem><para>
3264 The <filename>.debug</filename> directory packaging is
3265 now automatic.
3266 If your recipe builds software that installs binaries into
3267 directories other than the standard ones, you no longer
3268 need to take care of setting
3269 <filename>FILES_${PN}-dbg</filename> to pick up the
3270 resulting <filename>.debug</filename> directories as these
3271 directories are automatically found and added.
3272 </para></listitem>
3273 <listitem><para>
3274 Inaccurate disk and CPU percentage data has been dropped
3275 from <filename>buildstats</filename> output.
3276 This data has been replaced with
3277 <filename>getrusage()</filename> data and corrected IO
3278 statistics.
3279 You will probably need to update any custom code that reads
3280 the <filename>buildstats</filename> data.
3281 </para></listitem>
3282 <listitem><para>
3283 The
3284 <filename>meta/conf/distro/include/package_regex.inc</filename>
3285 is now deprecated.
3286 The contents of this file have been moved to individual
3287 recipes.
3288 <note><title>Tip</title>
3289 Because this file will likely be removed in a future
3290 Yocto Project release, it is suggested that you remove
3291 any references to the file that might be in your
3292 configuration.
3293 </note>
3294 </para></listitem>
3295 <listitem><para>
3296 The <filename>v86d/uvesafb</filename> has been removed from
3297 the <filename>genericx86</filename> and
3298 <filename>genericx86-64</filename> reference machines,
3299 which are provided by the
3300 <filename>meta-yocto-bsp</filename> layer.
3301 Most modern x86 boards do not rely on this file and it only
3302 adds kernel error messages during startup.
3303 If you do still need to support
3304 <filename>uvesafb</filename>, you can
3305 simply add <filename>v86d</filename> to your image.
3306 </para></listitem>
3307 <listitem><para>
3308 Build sysroot paths are now removed from debug symbol
3309 files.
3310 Removing these paths means that remote GDB using an
3311 unstripped build system sysroot will no longer work
3312 (although this was never documented to work).
3313 The supported method to accomplish something similar is
3314 to set <filename>IMAGE_GEN_DEBUGFS</filename> to "1",
3315 which will generate a companion debug image
3316 containing unstripped binaries and associated debug
3317 sources alongside the image.
3318 </para></listitem>
3319 </itemizedlist>
3320 </para>
3321 </section>
3322</section>
3323
3324<section id='moving-to-the-yocto-project-2.2-release'>
3325 <title>Moving to the Yocto Project 2.2 Release</title>
3326
3327 <para>
3328 This section provides migration information for moving to the
3329 Yocto Project 2.2 Release from the prior release.
3330 </para>
3331
3332 <section id='migration-2.2-minimum-kernel-version'>
3333 <title>Minimum Kernel Version</title>
3334
3335 <para>
3336 The minimum kernel version for the target system and for SDK
3337 is now 3.2.0, due to the upgrade
3338 to <filename>glibc 2.24</filename>.
3339 Specifically, for AArch64-based targets the version is
3340 3.14.
3341 For Nios II-based targets, the minimum kernel version is 3.19.
3342 <note>
3343 For x86 and x86_64, you can reset
3344 <link linkend='var-OLDEST_KERNEL'><filename>OLDEST_KERNEL</filename></link>
3345 to anything down to 2.6.32 if desired.
3346 </note>
3347 </para>
3348 </section>
3349
3350 <section id='migration-2.2-staging-directories-in-sysroot-simplified'>
3351 <title>Staging Directories in Sysroot Has Been Simplified</title>
3352
3353 <para>
3354 The way directories are staged in sysroot has been simplified and
3355 introduces the new
3356 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
3357 <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
3358 and
3359 <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>.
3360 See the
3361 <ulink url='http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html'>v2 patch series on the OE-Core Mailing List</ulink>
3362 for additional information.
3363 </para>
3364 </section>
3365
3366 <section id='migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled'>
3367 <title>Removal of Old Images and Other Files in <filename>tmp/deploy</filename> Now Enabled</title>
3368
3369 <para>
3370 Removal of old images and other files in
3371 <filename>tmp/deploy/</filename> is now enabled by default due
3372 to a new staging method used for those files.
3373 As a result of this change, the
3374 <filename>RM_OLD_IMAGE</filename> variable is now redundant.
3375 </para>
3376 </section>
3377
3378 <section id='migration-2.2-python-changes'>
3379 <title>Python Changes</title>
3380
3381 <para>
3382 The following changes for Python occurred:
3383 </para>
3384
3385 <section id='migration-2.2-bitbake-now-requires-python-3.4'>
3386 <title>BitBake Now Requires Python 3.4+</title>
3387
3388 <para>
3389 BitBake requires Python 3.4 or greater.
3390 </para>
3391 </section>
3392
3393 <section id='migration-2.2-utf-8-locale-required-on-build-host'>
3394 <title>UTF-8 Locale Required on Build Host</title>
3395
3396 <para>
3397 A UTF-8 locale is required on the build host due to Python 3.
3398 Since C.UTF-8 is not a standard, the default is en_US.UTF-8.
3399 </para>
3400 </section>
3401
3402 <section id='migration-2.2-metadata-now-must-use-python-3-syntax'>
3403 <title>Metadata Must Now Use Python 3 Syntax</title>
3404
3405 <para>
3406 The metadata is now required to use Python 3 syntax.
3407 For help preparing metadata, see any of the many Python 3 porting
3408 guides available.
3409 Alternatively, you can reference the conversion commits for Bitbake
3410 and you can use
3411 <link linkend='oe-core'>OE-Core</link> as a guide for changes.
3412 Following are particular areas of interest:
3413 <literallayout class='monospaced'>
3414 * subprocess command-line pipes needing locale decoding
3415 * the syntax for octal values changed
3416 * the <filename>iter*()</filename> functions changed name
3417 * iterators now return views, not lists
3418 * changed names for Python modules
3419 </literallayout>
3420 </para>
3421 </section>
3422
3423 <section id='migration-2.2-target-python-recipes-switched-to-python-3'>
3424 <title>Target Python Recipes Switched to Python 3</title>
3425
3426 <para>
3427 Most target Python recipes have now been switched to Python 3.
3428 Unfortunately, systems using RPM as a package manager and
3429 providing online package-manager support through SMART still
3430 require Python 2.
3431 <note>
3432 Python 2 and recipes that use it can still be built for the
3433 target as with previous versions.
3434 </note>
3435 </para>
3436 </section>
3437
3438 <section id='migration-2.2-buildtools-tarball-includes-python-3'>
3439 <title><filename>buildtools-tarball</filename> Includes Python 3</title>
3440
3441 <para>
3442 <filename>buildtools-tarball</filename> now includes Python 3.
3443 </para>
3444 </section>
3445 </section>
3446
3447 <section id='migration-2.2-uclibc-replaced-by-musl'>
3448 <title>uClibc Replaced by musl</title>
3449
3450 <para>
3451 uClibc has been removed in favor of musl.
3452 Musl has matured, is better maintained, and is compatible with a
3453 wider range of applications as compared to uClibc.
3454 </para>
3455 </section>
3456
3457 <section id='migration-2.2-B-no-longer-default-working-directory-for-tasks'>
3458 <title><filename>${B}</filename> No Longer Default Working Directory for Tasks</title>
3459
3460 <para>
3461 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>
3462 is no longer the default working directory for tasks.
3463 Consequently, any custom tasks you define now need to either
3464 have the
3465 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>dirs</filename></ulink><filename>]</filename> flag set, or the task needs to change into the
3466 appropriate working directory manually (e.g using
3467 <filename>cd</filename> for a shell task).
3468 <note>
3469 The preferred method is to use the
3470 <filename>[dirs]</filename> flag.
3471 </note>
3472 </para>
3473 </section>
3474
3475 <section id='migration-2.2-runqemu-ported-to-python'>
3476 <title><filename>runqemu</filename> Ported to Python</title>
3477
3478 <para>
3479 <filename>runqemu</filename> has been ported to Python and has
3480 changed behavior in some cases.
3481 Previous usage patterns continue to be supported.
3482 </para>
3483
3484 <para>
3485 The new <filename>runqemu</filename> is a Python script.
3486 Machine knowledge is no longer hardcoded into
3487 <filename>runqemu</filename>.
3488 You can choose to use the <filename>qemuboot</filename>
3489 configuration file to define the BSP's own arguments and to make
3490 it bootable with <filename>runqemu</filename>.
3491 If you use a configuration file, use the following form:
3492 <literallayout class='monospaced'>
3493 <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf
3494 </literallayout>
3495 The configuration file enables fine-grained tuning of options
3496 passed to QEMU without the <filename>runqemu</filename> script
3497 hard-coding any knowledge about different machines.
3498 Using a configuration file is particularly convenient when trying
3499 to use QEMU with machines other than the
3500 <filename>qemu*</filename> machines in
3501 <link linkend='oe-core'>OE-Core</link>.
3502 The <filename>qemuboot.conf</filename> file is generated by the
3503 <filename>qemuboot</filename>
3504 class when the root filesystem is being build (i.e.
3505 build rootfs).
3506 QEMU boot arguments can be set in BSP's configuration file and
3507 the <filename>qemuboot</filename> class will save them to
3508 <filename>qemuboot.conf</filename>.
3509 </para>
3510
3511
3512 <para>
3513 If you want to use <filename>runqemu</filename> without a
3514 configuration file, use the following command form:
3515 <literallayout class='monospaced'>
3516 $ runqemu <replaceable>machine</replaceable> <replaceable>rootfs</replaceable> <replaceable>kernel</replaceable> [<replaceable>options</replaceable>]
3517 </literallayout>
3518 Supported <replaceable>machines</replaceable> are as follows:
3519 <literallayout class='monospaced'>
3520 qemuarm
3521 qemuarm64
3522 qemux86
3523 qemux86-64
3524 qemuppc
3525 qemumips
3526 qemumips64
3527 qemumipsel
3528 qemumips64el
3529 </literallayout>
3530 Consider the following example, which uses the
3531 <filename>qemux86-64</filename> machine,
3532 provides a root filesystem, provides an image, and uses
3533 the <filename>nographic</filename> option:
3534 <literallayout class='monospaced'>
3535$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
3536 </literallayout>
3537 </para>
3538
3539 <para>
3540 Following is a list of variables that can be set in configuration
3541 files such as <filename>bsp.conf</filename> to enable the BSP
3542 to be booted by <filename>runqemu</filename>:
3543 <note>
3544 "QB" means "QEMU Boot".
3545 </note>
3546 <literallayout class='monospaced'>
3547 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
3548 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
3549 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
3550 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
3551 QB_MEM: Memory (e.g. "-m 512")
3552 QB_MACHINE: QEMU machine (e.g. "-machine virt")
3553 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
3554 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
3555 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
3556 option (e.g. "console=ttyS0 console=tty")
3557 QB_DTB: QEMU dtb name
3558 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
3559 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
3560 when QB_AUDIO_DRV is set.
3561 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
3562 QB_TAP_OPT: Network option for 'tap' mode (e.g.
3563 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
3564 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
3565 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
3566 QB_ROOTFS_OPT: Used as rootfs (e.g.
3567 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
3568 runqemu will replace "@ROOTFS@" with the one which is used, such as
3569 core-image-minimal-qemuarm64.ext4.
3570 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
3571 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
3572 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
3573 runqemu will replace "@PORT@" with the port number which is used.
3574 </literallayout>
3575 </para>
3576
3577 <para>
3578 To use <filename>runqemu</filename>, set
3579 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3580 as follows and run <filename>runqemu</filename>:
3581 <note>
3582 For command-line syntax, use
3583 <filename>runqemu help</filename>.
3584 </note>
3585 <literallayout class='monospaced'>
3586 IMAGE_CLASSES += "qemuboot"
3587 </literallayout>
3588 </para>
3589 </section>
3590
3591 <section id='migration-2.2-default-linker-hash-style-changed'>
3592 <title>Default Linker Hash Style Changed</title>
3593
3594 <para>
3595 The default linker hash style for <filename>gcc-cross</filename>
3596 is now "sysv" in order to catch recipes that are building software
3597 without using the OpenEmbedded
3598 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>.
3599 This change could result in seeing some "No GNU_HASH in the elf
3600 binary" QA issues when building such recipes.
3601 You need to fix these recipes so that they use the expected
3602 <filename>LDFLAGS</filename>.
3603 Depending on how the software is built, the build system used by
3604 the software (e.g. a Makefile) might need to be patched.
3605 However, sometimes making this fix is as simple as adding the
3606 following to the recipe:
3607 <literallayout class='monospaced'>
3608 TARGET_CC_ARCH += "${LDFLAGS}"
3609 </literallayout>
3610 </para>
3611 </section>
3612
3613 <section id='migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype'>
3614 <title><filename>KERNEL_IMAGE_BASE_NAME</filename> no Longer Uses <filename>KERNEL_IMAGETYPE</filename></title>
3615
3616 <para>
3617 The
3618 <filename>KERNEL_IMAGE_BASE_NAME</filename>
3619 variable no longer uses the
3620 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
3621 variable to create the image's base name.
3622 Because the OpenEmbedded build system can now build multiple kernel
3623 image types, this part of the kernel image base name as been
3624 removed leaving only the following:
3625 <literallayout class='monospaced'>
3626 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
3627 </literallayout>
3628 If you have recipes or classes that use
3629 <filename>KERNEL_IMAGE_BASE_NAME</filename> directly, you might
3630 need to update the references to ensure they continue to work.
3631 </para>
3632 </section>
3633
3634 <section id='migration-2.2-bitbake-changes'>
3635 <title>BitBake Changes</title>
3636
3637 <para>
3638 The following changes took place for BitBake:
3639 <itemizedlist>
3640 <listitem><para>
3641 The "goggle" UI and standalone image-writer tool have
3642 been removed as they both require GTK+ 2.0 and
3643 were not being maintained.
3644 </para></listitem>
3645 <listitem><para>
3646 The Perforce fetcher now supports
3647 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3648 for specifying the source revision to use, be it
3649 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>,
3650 changelist number, p4date, or label, in preference to
3651 separate
3652 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
3653 parameters to specify these.
3654 This change is more in-line with how the other fetchers
3655 work for source control systems.
3656 Recipes that fetch from Perforce will need to be updated
3657 to use <filename>SRCREV</filename> in place of specifying
3658 the source revision within
3659 <filename>SRC_URI</filename>.
3660 </para></listitem>
3661 <listitem><para>
3662 Some of BitBake's internal code structures for accessing
3663 the recipe cache needed to be changed to support the new
3664 multi-configuration functionality.
3665 These changes will affect external tools that use BitBake's
3666 tinfoil module.
3667 For information on these changes, see the changes made to
3668 the scripts supplied with OpenEmbedded-Core:
3669 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee'>1</ulink>
3670 and
3671 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67'>2</ulink>.
3672 </para></listitem>
3673 <listitem><para>
3674 The task management code has been rewritten to avoid using
3675 ID indirection in order to improve performance.
3676 This change is unlikely to cause any problems for most
3677 users.
3678 However, the setscene verification function as pointed to
3679 by <filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
3680 needed to change signature.
3681 Consequently, a new variable named
3682 <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
3683 has been added allowing multiple versions of BitBake
3684 to work with suitably written metadata, which includes
3685 OpenEmbedded-Core and Poky.
3686 Anyone with custom BitBake task scheduler code might also
3687 need to update the code to handle the new structure.
3688 </para></listitem>
3689 </itemizedlist>
3690 </para>
3691 </section>
3692
3693 <section id='migration-2.2-swabber-has-been-removed'>
3694 <title>Swabber has Been Removed</title>
3695
3696 <para>
3697 Swabber, a tool that was intended to detect host contamination in
3698 the build process, has been removed, as it has been unmaintained
3699 and unused for some time and was never particularly effective.
3700 The OpenEmbedded build system has since incorporated a number of
3701 mechanisms including enhanced QA checks that mean that there is
3702 less of a need for such a tool.
3703 </para>
3704 </section>
3705
3706 <section id='migration-2.2-removed-recipes'>
3707 <title>Removed Recipes</title>
3708
3709 <para>
3710 The following recipes have been removed:
3711 <itemizedlist>
3712 <listitem><para>
3713 <filename>augeas</filename>:
3714 No longer needed and has been moved to
3715 <filename>meta-oe</filename>.
3716 </para></listitem>
3717 <listitem><para>
3718 <filename>directfb</filename>:
3719 Unmaintained and has been moved to
3720 <filename>meta-oe</filename>.
3721 </para></listitem>
3722 <listitem><para>
3723 <filename>gcc</filename>:
3724 Removed 4.9 version.
3725 Versions 5.4 and 6.2 are still present.
3726 </para></listitem>
3727 <listitem><para>
3728 <filename>gnome-doc-utils</filename>:
3729 No longer needed.
3730 </para></listitem>
3731 <listitem><para>
3732 <filename>gtk-doc-stub</filename>:
3733 Replaced by <filename>gtk-doc</filename>.
3734 </para></listitem>
3735 <listitem><para>
3736 <filename>gtk-engines</filename>:
3737 No longer needed and has been moved to
3738 <filename>meta-gnome</filename>.
3739 </para></listitem>
3740 <listitem><para>
3741 <filename>gtk-sato-engine</filename>:
3742 Became obsolete.
3743 </para></listitem>
3744 <listitem><para>
3745 <filename>libglade</filename>:
3746 No longer needed and has been moved to
3747 <filename>meta-oe</filename>.
3748 </para></listitem>
3749 <listitem><para>
3750 <filename>libmad</filename>:
3751 Unmaintained and functionally replaced by
3752 <filename>libmpg123</filename>.
3753 <filename>libmad</filename> has been moved to
3754 <filename>meta-oe</filename>.
3755 </para></listitem>
3756 <listitem><para>
3757 <filename>libowl</filename>:
3758 Became obsolete.
3759 </para></listitem>
3760 <listitem><para>
3761 <filename>libxsettings-client</filename>:
3762 No longer needed.
3763 </para></listitem>
3764 <listitem><para>
3765 <filename>oh-puzzles</filename>:
3766 Functionally replaced by
3767 <filename>puzzles</filename>.
3768 </para></listitem>
3769 <listitem><para>
3770 <filename>oprofileui</filename>:
3771 Became obsolete.
3772 OProfile has been largely supplanted by perf.
3773 </para></listitem>
3774 <listitem><para>
3775 <filename>packagegroup-core-directfb.bb</filename>:
3776 Removed.
3777 </para></listitem>
3778 <listitem><para>
3779 <filename>core-image-directfb.bb</filename>:
3780 Removed.
3781 </para></listitem>
3782 <listitem><para>
3783 <filename>pointercal</filename>:
3784 No longer needed and has been moved to
3785 <filename>meta-oe</filename>.
3786 </para></listitem>
3787 <listitem><para>
3788 <filename>python-imaging</filename>:
3789 No longer needed and moved to
3790 <filename>meta-python</filename>
3791 </para></listitem>
3792 <listitem><para>
3793 <filename>python-pyrex</filename>:
3794 No longer needed and moved to
3795 <filename>meta-python</filename>.
3796 </para></listitem>
3797 <listitem><para>
3798 <filename>sato-icon-theme</filename>:
3799 Became obsolete.
3800 </para></listitem>
3801 <listitem><para>
3802 <filename>swabber-native</filename>:
3803 Swabber has been removed.
3804 See the
3805 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3806 </para></listitem>
3807 <listitem><para>
3808 <filename>tslib</filename>:
3809 No longer needed and has been moved to
3810 <filename>meta-oe</filename>.
3811 </para></listitem>
3812 <listitem><para>
3813 <filename>uclibc</filename>:
3814 Removed in favor of musl.
3815 </para></listitem>
3816 <listitem><para>
3817 <filename>xtscal</filename>:
3818 No longer needed and moved to
3819 <filename>meta-oe</filename>
3820 </para></listitem>
3821 </itemizedlist>
3822 </para>
3823 </section>
3824
3825 <section id='migration-2.2-removed-classes'>
3826 <title>Removed Classes</title>
3827
3828 <para>
3829 The following classes have been removed:
3830 <itemizedlist>
3831 <listitem><para>
3832 <filename>distutils-native-base</filename>:
3833 No longer needed.
3834 </para></listitem>
3835 <listitem><para>
3836 <filename>distutils3-native-base</filename>:
3837 No longer needed.
3838 </para></listitem>
3839 <listitem><para>
3840 <filename>sdl</filename>:
3841 Only set
3842 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
3843 and
3844 <link linkend='var-SECTION'><filename>SECTION</filename></link>,
3845 which are better set within the recipe instead.
3846 </para></listitem>
3847 <listitem><para>
3848 <filename>sip</filename>:
3849 Mostly unused.
3850 </para></listitem>
3851 <listitem><para>
3852 <filename>swabber</filename>:
3853 See the
3854 <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>.
3855 </para></listitem>
3856 </itemizedlist>
3857 </para>
3858 </section>
3859
3860 <section id='migration-2.2-minor-packaging-changes'>
3861 <title>Minor Packaging Changes</title>
3862
3863 <para>
3864 The following minor packaging changes have occurred:
3865 <itemizedlist>
3866 <listitem><para>
3867 <filename>grub</filename>:
3868 Split <filename>grub-editenv</filename> into its own
3869 package.
3870 </para></listitem>
3871 <listitem><para>
3872 <filename>systemd</filename>:
3873 Split container and vm related units into a new package,
3874 systemd-container.
3875 </para></listitem>
3876 <listitem><para>
3877 <filename>util-linux</filename>:
3878 Moved <filename>prlimit</filename> to a separate
3879 <filename>util-linux-prlimit</filename> package.
3880 </para></listitem>
3881 </itemizedlist>
3882 </para>
3883 </section>
3884
3885 <section id='migration-2.2-miscellaneous-changes'>
3886 <title>Miscellaneous Changes</title>
3887
3888 <para>
3889 The following miscellaneous changes have occurred:
3890 <itemizedlist>
3891 <listitem><para>
3892 <filename>package_regex.inc</filename>:
3893 Removed because the definitions
3894 <filename>package_regex.inc</filename> previously contained
3895 have been moved to their respective recipes.
3896 </para></listitem>
3897 <listitem><para>
3898 Both <filename>devtool add</filename> and
3899 <filename>recipetool create</filename> now use a fixed
3900 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
3901 by default when fetching from a Git repository.
3902 You can override this in either case to use
3903 <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>
3904 instead by using the <filename>-a</filename> or
3905 <filename>&dash;&dash;autorev</filename> command-line
3906 option
3907 </para></listitem>
3908 <listitem><para>
3909 <filename>distcc</filename>:
3910 GTK+ UI is now disabled by default.
3911 </para></listitem>
3912 <listitem><para>
3913 <filename>packagegroup-core-tools-testapps</filename>:
3914 Removed Piglit.
3915 </para></listitem>
3916 <listitem><para>
3917 <filename>image.bbclass</filename>:
3918 Renamed COMPRESS(ION) to CONVERSION.
3919 This change means that
3920 <filename>COMPRESSIONTYPES</filename>,
3921 <filename>COMPRESS_DEPENDS</filename> and
3922 <filename>COMPRESS_CMD</filename> are deprecated in favor
3923 of <filename>CONVERSIONTYPES</filename>,
3924 <filename>CONVERSION_DEPENDS</filename> and
3925 <filename>CONVERSION_CMD</filename>.
3926 The <filename>COMPRESS*</filename> variable names will
3927 still work in the 2.2 release but metadata that does not
3928 need to be backwards-compatible should be changed to
3929 use the new names as the <filename>COMPRESS*</filename>
3930 ones will be removed in a future release.
3931 </para></listitem>
3932 <listitem><para>
3933 <filename>gtk-doc</filename>:
3934 A full version of <filename>gtk-doc</filename> is now
3935 made available.
3936 However, some old software might not be capable of using
3937 the current version of <filename>gtk-doc</filename>
3938 to build documentation.
3939 You need to change recipes that build such software so that
3940 they explicitly disable building documentation with
3941 <filename>gtk-doc</filename>.
3942 </para></listitem>
3943 </itemizedlist>
3944 </para>
3945 </section>
3946</section>
3947
3948<section id='moving-to-the-yocto-project-2.3-release'>
3949 <title>Moving to the Yocto Project 2.3 Release</title>
3950
3951 <para>
3952 This section provides migration information for moving to the
3953 Yocto Project 2.3 Release from the prior release.
3954 </para>
3955
3956 <section id='migration-2.3-recipe-specific-sysroots'>
3957 <title>Recipe-specific Sysroots</title>
3958
3959 <para>
3960 The OpenEmbedded build system now uses one sysroot per
3961 recipe to resolve long-standing issues with configuration
3962 script auto-detection of undeclared dependencies.
3963 Consequently, you might find that some of your previously
3964 written custom recipes are missing declared dependencies,
3965 particularly those dependencies that are incidentally built
3966 earlier in a typical build process and thus are already likely
3967 to be present in the shared sysroot in previous releases.
3968 </para>
3969
3970 <para>
3971 Consider the following:
3972 <itemizedlist>
3973 <listitem><para>
3974 <emphasis>Declare Build-Time Dependencies:</emphasis>
3975 Because of this new feature, you must explicitly
3976 declare all build-time dependencies for your recipe.
3977 If you do not declare these dependencies, they are not
3978 populated into the sysroot for the recipe.
3979 </para></listitem>
3980 <listitem><para>
3981 <emphasis>Specify Pre-Installation and Post-Installation
3982 Native Tool Dependencies:</emphasis>
3983 You must specifically specify any special native tool
3984 dependencies of <filename>pkg_preinst</filename> and
3985 <filename>pkg_postinst</filename> scripts by using the
3986 <link linkend='var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></link>
3987 variable.
3988 Specifying these dependencies ensures that these tools
3989 are available if these scripts need to be run on the
3990 build host during the
3991 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
3992 task.</para>
3993
3994 <para>As an example, see the <filename>dbus</filename>
3995 recipe.
3996 You will see that this recipe has a
3997 <filename>pkg_postinst</filename> that calls
3998 <filename>systemctl</filename> if "systemd" is in
3999 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
4000 In the example,
4001 <filename>systemd-systemctl-native</filename> is added to
4002 <filename>PACKAGE_WRITE_DEPS</filename>, which is also
4003 conditional on "systemd" being in
4004 <filename>DISTRO_FEATURES</filename>.
4005 </para></listitem>
4006 <listitem><para>
4007 <emphasis>Examine Recipes that Use
4008 <filename>SSTATEPOSTINSTFUNCS</filename>:</emphasis>
4009 You need to examine any recipe that uses
4010 <filename>SSTATEPOSTINSTFUNCS</filename> and determine
4011 steps to take.</para>
4012
4013 <para>Functions added to
4014 <filename>SSTATEPOSTINSTFUNCS</filename> are still
4015 called as they were in previous Yocto Project releases.
4016 However, since a separate sysroot is now being populated
4017 for every recipe and if existing functions being called
4018 through <filename>SSTATEPOSTINSTFUNCS</filename> are
4019 doing relocation, then you will need to change these
4020 to use a post-installation script that is installed by a
4021 function added to
4022 <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>.
4023 </para>
4024
4025 <para>For an example, see the
4026 <filename>pixbufcache</filename> class in
4027 <filename>meta/classes/</filename> in the Yocto Project
4028 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
4029 <note>
4030 The <filename>SSTATEPOSTINSTFUNCS</filename> variable
4031 itself is now deprecated in favor of the
4032 <filename>do_populate_sysroot[postfuncs]</filename>
4033 task.
4034 Consequently, if you do still have any function or
4035 functions that need to be called after the sysroot
4036 component is created for a recipe, then you would be
4037 well advised to take steps to use a post installation
4038 script as described previously.
4039 Taking these steps prepares your code for when
4040 <filename>SSTATEPOSTINSTFUNCS</filename> is
4041 removed in a future Yocto Project release.
4042 </note>
4043 </para></listitem>
4044 <listitem><para>
4045 <emphasis>Specify the Sysroot when Using Certain
4046 External Scripts:</emphasis>
4047 Because the shared sysroot is now gone, the scripts
4048 <filename>oe-find-native-sysroot</filename> and
4049 <filename>oe-run-native</filename> have been changed such
4050 that you need to specify which recipe's
4051 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>
4052 is used.
4053 </para></listitem>
4054 </itemizedlist>
4055 <note>
4056 You can find more information on how recipe-specific sysroots
4057 work in the
4058 "<link linkend='ref-classes-staging'><filename>staging.bbclass</filename></link>"
4059 section.
4060 </note>
4061 </para>
4062 </section>
4063
4064 <section id='migration-2.3-path-variable'>
4065 <title><filename>PATH</filename> Variable</title>
4066
4067 <para>
4068 Within the environment used to run build tasks, the environment
4069 variable <filename>PATH</filename> is now sanitized such that
4070 the normal native binary paths
4071 (<filename>/bin</filename>, <filename>/sbin</filename>,
4072 <filename>/usr/bin</filename> and so forth) are
4073 removed and a directory containing symbolic links linking only
4074 to the binaries from the host mentioned in the
4075 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>
4076 and
4077 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>
4078 variables is added to <filename>PATH</filename>.
4079 </para>
4080
4081 <para>
4082 Consequently, any native binaries provided by the host that you
4083 need to call needs to be in one of these two variables at
4084 the configuration level.
4085 </para>
4086
4087 <para>
4088 Alternatively, you can add a native recipe (i.e.
4089 <filename>-native</filename>) that provides the
4090 binary to the recipe's
4091 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
4092 value.
4093 <note>
4094 <filename>PATH</filename> is not sanitized in the same way
4095 within <filename>devshell</filename>.
4096 If it were, you would have difficulty running host tools for
4097 development and debugging within the shell.
4098 </note>
4099 </para>
4100 </section>
4101
4102 <section id='migration-2.3-scripts'>
4103 <title>Changes to Scripts</title>
4104
4105 <para>
4106 The following changes to scripts took place:
4107 <itemizedlist>
4108 <listitem><para>
4109 <emphasis><filename>oe-find-native-sysroot</filename>:</emphasis>
4110 The usage for the
4111 <filename>oe-find-native-sysroot</filename> script has
4112 changed to the following:
4113 <literallayout class='monospaced'>
4114 $ . oe-find-native-sysroot <replaceable>recipe</replaceable>
4115 </literallayout>
4116 You must now supply a recipe for
4117 <replaceable>recipe</replaceable> as part of the command.
4118 Prior to the Yocto Project &DISTRO; release, it was not
4119 necessary to provide the script with the command.
4120 </para></listitem>
4121 <listitem><para>
4122 <emphasis><filename>oe-run-native</filename>:</emphasis>
4123 The usage for the
4124 <filename>oe-run-native</filename> script has changed
4125 to the following:
4126 <literallayout class='monospaced'>
4127 $ oe-run-native <replaceable>native_recipe</replaceable> <replaceable>tool</replaceable>
4128 </literallayout>
4129 You must supply the name of the native recipe and the tool
4130 you want to run as part of the command.
4131 Prior to the Yocto Project &DISTRO; release, it was not
4132 necessary to provide the native recipe with the command.
4133 </para></listitem>
4134 <listitem><para>
4135 <emphasis><filename>cleanup-workdir</filename>:</emphasis>
4136 The <filename>cleanup-workdir</filename> script has been
4137 removed because the script was found to be deleting
4138 files it should not have, which lead to broken build
4139 trees.
4140 Rather than trying to delete portions of
4141 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
4142 and getting it wrong, it is recommended that you
4143 delete <filename>TMPDIR</filename> and have it restored
4144 from shared state (sstate) on subsequent builds.
4145 </para></listitem>
4146 <listitem><para>
4147 <emphasis><filename>wipe-sysroot</filename>:</emphasis>
4148 The <filename>wipe-sysroot</filename> script has been
4149 removed as it is no longer needed with recipe-specific
4150 sysroots.
4151 </para></listitem>
4152 </itemizedlist>
4153 </para>
4154 </section>
4155
4156 <section id='migration-2.3-functions'>
4157 <title>Changes to Functions</title>
4158
4159 <para>
4160 The previously deprecated
4161 <filename>bb.data.getVar()</filename>,
4162 <filename>bb.data.setVar()</filename>, and
4163 related functions have been removed in favor of
4164 <filename>d.getVar()</filename>,
4165 <filename>d.setVar()</filename>, and so forth.
4166 </para>
4167
4168 <para>
4169 You need to fix any references to these old functions.
4170 </para>
4171 </section>
4172
4173 <section id='migration-2.3-bitbake-changes'>
4174 <title>BitBake Changes</title>
4175
4176 <para>
4177 The following changes took place for BitBake:
4178 <itemizedlist>
4179 <listitem><para>
4180 <emphasis>BitBake's Graphical Dependency Explorer UI Replaced:</emphasis>
4181 BitBake's graphical dependency explorer UI
4182 <filename>depexp</filename> was replaced by
4183 <filename>taskexp</filename> ("Task Explorer"), which
4184 provides a graphical way of exploring the
4185 <filename>task-depends.dot</filename> file.
4186 The data presented by Task Explorer is much more
4187 accurate than the data that was presented by
4188 <filename>depexp</filename>.
4189 Being able to visualize the data is an often requested
4190 feature as standard <filename>*.dot</filename> file
4191 viewers cannot usual cope with the size of
4192 the <filename>task-depends.dot</filename> file.
4193 </para></listitem>
4194 <listitem><para>
4195 <emphasis>BitBake "-g" Output Changes:</emphasis>
4196 The <filename>package-depends.dot</filename> and
4197 <filename>pn-depends.dot</filename> files as previously
4198 generated using the <filename>bitbake -g</filename> command
4199 have been removed.
4200 A <filename>recipe-depends.dot</filename> file
4201 is now generated as a collapsed version of
4202 <filename>task-depends.dot</filename> instead.
4203 </para>
4204
4205 <para>The reason for this change is because
4206 <filename>package-depends.dot</filename> and
4207 <filename>pn-depends.dot</filename> largely date back
4208 to a time before task-based execution and do not take
4209 into account task-level dependencies between recipes,
4210 which could be misleading.
4211 </para></listitem>
4212 <listitem><para>
4213 <emphasis>Mirror Variable Splitting Changes:</emphasis>
4214 Mirror variables including
4215 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>,
4216 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
4217 and
4218 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
4219 can now separate values entirely with spaces.
4220 Consequently, you no longer need "\\n".
4221 BitBake looks for pairs of values, which simplifies usage.
4222 There should be no change required to existing mirror
4223 variable values themselves.
4224 </para></listitem>
4225 <listitem><para>
4226 <emphasis>The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter:</emphasis>
4227 The SVN fetcher now takes an "ssh" parameter instead of an
4228 "rsh" parameter.
4229 This new optional parameter is used when the "protocol"
4230 parameter is set to "svn+ssh".
4231 You can only use the new parameter to specify the
4232 <filename>ssh</filename> program used by SVN.
4233 The SVN fetcher passes the new parameter through the
4234 <filename>SVN_SSH</filename> environment variable during
4235 the
4236 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
4237 task.</para>
4238
4239 <para>See the
4240 "<ulink url='&YOCTO_DOCS_BB_URL;#svn-fetcher'>Subversion (SVN) Fetcher (svn://)</ulink>"
4241 section in the BitBake User Manual for additional
4242 information.
4243 </para></listitem>
4244 <listitem><para>
4245 <emphasis><filename>BB_SETSCENE_VERIFY_FUNCTION</filename>
4246 and <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
4247 Removed:</emphasis>
4248 Because the mechanism they were part of is no longer
4249 necessary with recipe-specific sysroots, the
4250 <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> and
4251 <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename>
4252 variables have been removed.
4253 </para></listitem>
4254 </itemizedlist>
4255 </para>
4256 </section>
4257
4258 <section id='migration-2.3-absolute-symlinks'>
4259 <title>Absolute Symbolic Links</title>
4260
4261 <para>
4262 Absolute symbolic links (symlinks) within staged files are no
4263 longer permitted and now trigger an error.
4264 Any explicit creation of symlinks can use the
4265 <filename>lnr</filename> script, which is a replacement for
4266 <filename>ln -r</filename>.
4267 </para>
4268
4269 <para>
4270 If the build scripts in the software that the recipe is building
4271 are creating a number of absolute symlinks that need to be
4272 corrected, you can inherit
4273 <filename>relative_symlinks</filename> within the recipe to turn
4274 those absolute symlinks into relative symlinks.
4275 </para>
4276 </section>
4277
4278 <section id='migration-2.3-gplv2-and-gplv3-moves'>
4279 <title>GPLv2 Versions of GPLv3 Recipes Moved</title>
4280
4281 <para>
4282 Older GPLv2 versions of GPLv3 recipes have moved to a
4283 separate <filename>meta-gplv2</filename> layer.
4284 </para>
4285
4286 <para>
4287 If you use
4288 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>
4289 to exclude GPLv3 or set
4290 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
4291 to substitute a GPLv2 version of a GPLv3 recipe, then you must add
4292 the <filename>meta-gplv2</filename> layer to your configuration.
4293 <note>
4294 You can find <filename>meta-gplv2</filename> layer in the
4295 OpenEmbedded layer index at
4296 <ulink url='https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/'></ulink>.
4297 </note>
4298 </para>
4299
4300 <para>
4301 These relocated GPLv2 recipes do not receive the same level of
4302 maintenance as other core recipes.
4303 The recipes do not get security fixes and upstream no longer
4304 maintains them.
4305 In fact, the upstream community is actively hostile towards people
4306 that use the old versions of the recipes.
4307 Moving these recipes into a separate layer both makes the different
4308 needs of the recipes clearer and clearly identifies the number of
4309 these recipes.
4310 <note>
4311 The long-term solution might be to move to BSD-licensed
4312 replacements of the GPLv3 components for those that need to
4313 exclude GPLv3-licensed components from the target system.
4314 This solution will be investigated for future Yocto
4315 Project releases.
4316 </note>
4317 </para>
4318 </section>
4319
4320 <section id='migration-2.3-package-management-changes'>
4321 <title>Package Management Changes</title>
4322
4323 <para>
4324 The following package management changes took place:
4325 <itemizedlist>
4326 <listitem><para>
4327 Smart package manager is replaced by DNF package manager.
4328 Smart has become unmaintained upstream, is not ported
4329 to Python 3.x.
4330 Consequently, Smart needed to be replaced.
4331 DNF is the only feasible candidate.</para>
4332 <para>The change in functionality is that the on-target
4333 runtime package management from remote package feeds is
4334 now done with a different tool that has a
4335 different set of command-line options.
4336 If you have scripts that call the
4337 tool directly, or use its API, they need to be fixed.</para>
4338 <para>For more information, see the
4339 <ulink url='http://dnf.readthedocs.io/en/latest/'>DNF Documentation</ulink>.
4340 </para></listitem>
4341 <listitem><para>
4342 Rpm 5.x is replaced with Rpm 4.x.
4343 This is done for two major reasons:
4344 <itemizedlist>
4345 <listitem><para>
4346 DNF is API-incompatible with Rpm 5.x and porting
4347 it and maintaining the port is non-trivial.
4348 </para></listitem>
4349 <listitem><para>
4350 Rpm 5.x itself has limited maintenance upstream,
4351 and the Yocto Project is one of the very few
4352 remaining users.
4353 </para></listitem>
4354 </itemizedlist>
4355 </para></listitem>
4356 <listitem><para>
4357 Berkeley DB 6.x is removed and Berkeley DB 5.x becomes
4358 the default:
4359 <itemizedlist>
4360 <listitem><para>
4361 Version 6.x of Berkeley DB has largely been
4362 rejected by the open source community due to its
4363 AGPLv3 license.
4364 As a result, most mainstream open source projects
4365 that require DB are still developed and tested with
4366 DB 5.x.
4367 </para></listitem>
4368 <listitem><para>
4369 In OE-core, the only thing that was requiring
4370 DB 6.x was Rpm 5.x.
4371 Thus, no reason exists to continue carrying DB 6.x
4372 in OE-core.
4373 </para></listitem>
4374 </itemizedlist>
4375 </para></listitem>
4376 <listitem><para>
4377 <filename>createrepo</filename> is replaced with
4378 <filename>createrepo_c</filename>.</para>
4379 <para><filename>createrepo_c</filename> is the current
4380 incarnation of the tool that generates remote repository
4381 metadata.
4382 It is written in C as compared to
4383 <filename>createrepo</filename>, which is written in
4384 Python.
4385 <filename>createrepo_c</filename> is faster and is
4386 maintained.
4387 </para></listitem>
4388 <listitem><para>
4389 Architecture-independent RPM packages are "noarch"
4390 instead of "all".</para>
4391 <para>This change was made because too many places in
4392 DNF/RPM4 stack already make that assumption.
4393 Only the filenames and the architecture tag has changed.
4394 Nothing else has changed in OE-core system, particularly
4395 in the
4396 <link linkend='ref-classes-allarch'><filename>allarch.bbclass</filename></link>
4397 class.
4398 </para></listitem>
4399 <listitem><para>
4400 Signing of remote package feeds using
4401 <filename>PACKAGE_FEED_SIGN</filename>
4402 is not currently supported.
4403 This issue will be fully addressed in a future
4404 Yocto Project release.
4405 See <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>defect 11209</ulink>
4406 for more information on a solution to package feed
4407 signing with RPM in the Yocto Project 2.3 release.
4408 </para></listitem>
4409 <listitem><para>
4410 OPKG now uses the libsolv backend for resolving package
4411 dependencies by default.
4412 This is vastly superior to OPKG's internal ad-hoc solver
4413 that was previously used.
4414 This change does have a small impact on disk (around
4415 500 KB) and memory footprint.
4416 <note>
4417 For further details on this change, see the
4418 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?
4419id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>.
4420 </note>
4421 </para></listitem>
4422 </itemizedlist>
4423 </para>
4424 </section>
4425
4426 <section id='migration-2.3-removed-recipes'>
4427 <title>Removed Recipes</title>
4428
4429 <para>
4430 The following recipes have been removed:
4431 <itemizedlist>
4432 <listitem><para>
4433 <emphasis><filename>linux-yocto 4.8:</filename></emphasis>
4434 Version 4.8 has been removed.
4435 Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10
4436 are now present.
4437 </para></listitem>
4438 <listitem><para>
4439 <emphasis><filename>python-smartpm:</filename></emphasis>
4440 Functionally replaced by <filename>dnf</filename>.
4441 </para></listitem>
4442 <listitem><para>
4443 <emphasis><filename>createrepo:</filename></emphasis>
4444 Replaced by the <filename>createrepo-c</filename> recipe.
4445 </para></listitem>
4446 <listitem><para>
4447 <emphasis><filename>rpmresolve:</filename></emphasis>
4448 No longer needed with the move to RPM 4 as RPM itself is
4449 used instead.
4450 </para></listitem>
4451 <listitem><para>
4452 <emphasis><filename>gstreamer:</filename></emphasis>
4453 Removed the GStreamer Git version recipes as they have
4454 been stale.
4455 <filename>1.10.</filename><replaceable>x</replaceable>
4456 recipes are still present.
4457 </para></listitem>
4458 <listitem><para>
4459 <emphasis><filename>alsa-conf-base:</filename></emphasis>
4460 Merged into <filename>alsa-conf</filename> since
4461 <filename>libasound</filename> depended on both.
4462 Essentially, no way existed to install only one of these.
4463 </para></listitem>
4464 <listitem><para>
4465 <emphasis><filename>tremor:</filename></emphasis>
4466 Moved to <filename>meta-multimedia</filename>.
4467 Fixed-integer Vorbis decoding is not
4468 needed by current hardware.
4469 Thus, GStreamer's ivorbis plugin has been disabled
4470 by default eliminating the need for the
4471 <filename>tremor</filename> recipe in
4472 <link linkend='oe-core'>OE-Core</link>.
4473 </para></listitem>
4474 <listitem><para>
4475 <emphasis><filename>gummiboot:</filename></emphasis>
4476 Replaced by <filename>systemd-boot</filename>.
4477 </para></listitem>
4478 </itemizedlist>
4479 </para>
4480 </section>
4481
4482 <section id='migration-2.3-wic-changes'>
4483 <title>Wic Changes</title>
4484
4485 <para>
4486 The following changes have been made to Wic:
4487 <note>
4488 For more information on Wic, see the
4489 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
4490 section in the Yocto Project Development Tasks Manual.
4491 </note>
4492 <itemizedlist>
4493 <listitem><para>
4494 <emphasis>Default Output Directory Changed:</emphasis>
4495 Wic's default output directory is now the current directory
4496 by default instead of the unusual
4497 <filename>/var/tmp/wic</filename>.</para>
4498
4499 <para>The "-o" and "--outdir" options remain unchanged
4500 and are used to specify your preferred output directory
4501 if you do not want to use the default directory.
4502 </para></listitem>
4503 <listitem><para>
4504 <emphasis>fsimage Plug-in Removed:</emphasis>
4505 The Wic fsimage plugin has been removed as it duplicates
4506 functionality of the rawcopy plugin.
4507 </para></listitem>
4508 </itemizedlist>
4509 </para>
4510 </section>
4511
4512 <section id='migration-2.3-qa-changes'>
4513 <title>QA Changes</title>
4514
4515 <para>
4516 The following QA checks have changed:
4517 <itemizedlist>
4518 <listitem><para>
4519 <emphasis><filename>unsafe-references-in-binaries</filename>:</emphasis>
4520 The <filename>unsafe-references-in-binaries</filename>
4521 QA check, which was disabled by default, has now been
4522 removed.
4523 This check was intended to detect binaries in
4524 <filename>/bin</filename> that link to libraries in
4525 <filename>/usr/lib</filename> and have the case where
4526 the user has <filename>/usr</filename> on a separate
4527 filesystem to <filename>/</filename>.</para>
4528
4529 <para>The removed QA check was buggy.
4530 Additionally, <filename>/usr</filename> residing on a
4531 separate partition from <filename>/</filename> is now
4532 a rare configuration.
4533 Consequently,
4534 <filename>unsafe-references-in-binaries</filename> was
4535 removed.
4536 </para></listitem>
4537 <listitem><para>
4538 <emphasis><filename>file-rdeps</filename>:</emphasis>
4539 The <filename>file-rdeps</filename> QA check is now an
4540 error by default instead of a warning.
4541 Because it is an error instead of a warning, you need to
4542 address missing runtime dependencies.</para>
4543
4544 <para>For additional information, see the
4545 <link linkend='ref-classes-insane'><filename>insane</filename></link>
4546 class and the
4547 "<link linkend='qa-errors-and-warnings'>Errors and Warnings</link>"
4548 section.
4549 </para></listitem>
4550 </itemizedlist>
4551 </para>
4552 </section>
4553
4554 <section id='migration-2.3-miscellaneous-changes'>
4555 <title>Miscellaneous Changes</title>
4556
4557 <para>
4558 The following miscellaneous changes have occurred:
4559 <itemizedlist>
4560 <listitem><para>
4561 In this release, a number of recipes have been changed to
4562 ignore the <filename>largefile</filename>
4563 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
4564 item, enabling large file support unconditionally.
4565 This feature has always been enabled by default.
4566 Disabling the feature has not been widely tested.
4567 <note>
4568 Future releases of the Yocto Project will remove
4569 entirely the ability to disable the
4570 <filename>largefile</filename> feature,
4571 which would make it unconditionally enabled everywhere.
4572 </note>
4573 </para></listitem>
4574 <listitem><para>
4575 If the
4576 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
4577 value contains the value of the
4578 <link linkend='var-DATE'><filename>DATE</filename></link>
4579 variable, which is the default between Poky releases,
4580 the <filename>DATE</filename> value is explicitly excluded
4581 from <filename>/etc/issue</filename> and
4582 <filename>/etc/issue.net</filename>, which is displayed at
4583 the login prompt, in order to avoid conflicts with
4584 Multilib enabled.
4585 Regardless, the <filename>DATE</filename> value is
4586 inaccurate if the <filename>base-files</filename>
4587 recipe is restored from shared state (sstate) rather
4588 than rebuilt.</para>
4589
4590 <para>If you need the build date recorded in
4591 <filename>/etc/issue*</filename> or anywhere else in your
4592 image, a better method is to define a post-processing
4593 function to do it and have the function called from
4594 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
4595 Doing so ensures the value is always up-to-date with the
4596 created image.
4597 </para></listitem>
4598 <listitem><para>
4599 Dropbear's <filename>init</filename> script now disables
4600 DSA host keys by default.
4601 This change is in line with the systemd service
4602 file, which supports RSA keys only, and with recent
4603 versions of OpenSSH, which deprecates DSA host keys.
4604 </para></listitem>
4605 <listitem><para>
4606 The
4607 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
4608 class now correctly uses tabs as separators between all
4609 columns in <filename>installed-package-sizes.txt</filename>
4610 in order to aid import into other tools.
4611 </para></listitem>
4612 <listitem><para>
4613 The <filename>USE_LDCONFIG</filename> variable has been
4614 replaced with the "ldconfig"
4615 <filename>DISTRO_FEATURES</filename> feature.
4616 Distributions that previously set:
4617 <literallayout class='monospaced'>
4618 USE_LDCONFIG = "0"
4619 </literallayout>
4620 should now instead use the following:
4621 <literallayout class='monospaced'>
4622 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
4623 </literallayout>
4624 </para></listitem>
4625 <listitem><para>
4626 The default value of
4627 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
4628 now includes all versions of AGPL licenses in addition
4629 to GPL and LGPL.
4630 <note>
4631 The default list is not intended to be guaranteed
4632 as a complete safe list.
4633 You should seek legal advice based on what you are
4634 distributing if you are unsure.
4635 </note>
4636 </para></listitem>
4637 <listitem><para>
4638 Kernel module packages are now suffixed with the kernel
4639 version in order to allow module packages from multiple
4640 kernel versions to co-exist on a target system.
4641 If you wish to return to the previous naming scheme
4642 that does not include the version suffix, use the
4643 following:
4644 <literallayout class='monospaced'>
4645 KERNEL_MODULE_PACKAGE_SUFFIX to ""
4646 </literallayout>
4647 </para></listitem>
4648 <listitem><para>
4649 Removal of <filename>libtool</filename>
4650 <filename>*.la</filename> files is now enabled by default.
4651 The <filename>*.la</filename> files are not actually
4652 needed on Linux and relocating them is an unnecessary
4653 burden.</para>
4654
4655 <para>If you need to preserve these
4656 <filename>.la</filename> files (e.g. in a custom
4657 distribution), you must change
4658 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
4659 such that "remove-libtool" is not included in the value.
4660 </para></listitem>
4661 <listitem><para>
4662 Extensible SDKs built for GCC 5+ now refuse to install on a
4663 distribution where the host GCC version is 4.8 or 4.9.
4664 This change resulted from the fact that the installation
4665 is known to fail due to the way the
4666 <filename>uninative</filename> shared state (sstate)
4667 package is built.
4668 See the
4669 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
4670 class for additional information.
4671 </para></listitem>
4672 <listitem><para>
4673 All native and nativesdk recipes now use a separate
4674 <filename>DISTRO_FEATURES</filename> value instead of
4675 sharing the value used by recipes for the target, in order
4676 to avoid unnecessary rebuilds.</para>
4677
4678 <para>The <filename>DISTRO_FEATURES</filename> for
4679 <filename>native</filename> recipes is
4680 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
4681 added to an intersection of
4682 <filename>DISTRO_FEATURES</filename> and
4683 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>.
4684 </para>
4685
4686 <para>For nativesdk recipes, the
4687 corresponding variables are
4688 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
4689 and
4690 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>.
4691 </para></listitem>
4692 <listitem><para>
4693 The <filename>FILESDIR</filename>
4694 variable, which was previously deprecated and rarely used,
4695 has now been removed.
4696 You should change any recipes that set
4697 <filename>FILESDIR</filename> to set
4698 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4699 instead.
4700 </para></listitem>
4701 <listitem><para>
4702 The <filename>MULTIMACH_HOST_SYS</filename>
4703 variable has been removed as it is no longer needed
4704 with recipe-specific sysroots.
4705 </para></listitem>
4706 </itemizedlist>
4707 </para>
4708 </section>
4709</section>
4710
4711<section id='moving-to-the-yocto-project-2.4-release'>
4712 <title>Moving to the Yocto Project 2.4 Release</title>
4713
4714 <para>
4715 This section provides migration information for moving to the
4716 Yocto Project 2.4 Release from the prior release.
4717 </para>
4718
4719 <section id='migration-2.4-memory-resident-mode'>
4720 <title>Memory Resident Mode</title>
4721
4722 <para>
4723 A persistent mode is now available in BitBake's default operation,
4724 replacing its previous "memory resident mode" (i.e.
4725 <filename>oe-init-build-env-memres</filename>).
4726 Now you only need to set
4727 <link linkend='var-BB_SERVER_TIMEOUT'><filename>BB_SERVER_TIMEOUT</filename></link>
4728 to a timeout (in seconds) and BitBake's server stays resident for
4729 that amount of time between invocations.
4730 The <filename>oe-init-build-env-memres</filename> script has been
4731 removed since a separate environment setup script is no longer
4732 needed.
4733 </para>
4734 </section>
4735
4736 <section id='migration-2.4-packaging-changes'>
4737 <title>Packaging Changes</title>
4738
4739 <para>
4740 This section provides information about packaging changes that have
4741 occurred:
4742 <itemizedlist>
4743 <listitem><para>
4744 <emphasis><filename>python3</filename> Changes:</emphasis>
4745 <itemizedlist>
4746 <listitem><para>
4747 The main "python3" package now brings in all of the
4748 standard Python 3 distribution rather than a subset.
4749 This behavior matches what is expected based on
4750 traditional Linux distributions.
4751 If you wish to install a subset of Python 3, specify
4752 <filename>python-core</filename> plus one or more of
4753 the individual packages that are still produced.
4754 </para></listitem>
4755 <listitem><para>
4756 <emphasis><filename>python3</filename>:</emphasis>
4757 The <filename>bz2.py</filename>,
4758 <filename>lzma.py</filename>, and
4759 <filename>_compression.py</filename> scripts have
4760 been moved from the
4761 <filename>python3-misc</filename> package to
4762 the <filename>python3-compression</filename> package.
4763 </para></listitem>
4764 </itemizedlist>
4765 </para></listitem>
4766 <listitem><para>
4767 <emphasis><filename>binutils</filename>:</emphasis>
4768 The <filename>libbfd</filename> library is now packaged in
4769 a separate "libbfd" package.
4770 This packaging saves space when certain tools
4771 (e.g. <filename>perf</filename>) are installed.
4772 In such cases, the tools only need
4773 <filename>libbfd</filename> rather than all the packages in
4774 <filename>binutils</filename>.
4775 </para></listitem>
4776 <listitem><para>
4777 <emphasis><filename>util-linux</filename> Changes:</emphasis>
4778 <itemizedlist>
4779 <listitem><para>
4780 The <filename>su</filename> program is now packaged
4781 in a separate "util-linux-su" package, which is only
4782 built when "pam" is listed in the
4783 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
4784 variable.
4785 <filename>util-linux</filename> should not be
4786 installed unless it is needed because
4787 <filename>su</filename> is normally provided through
4788 the shadow file format.
4789 The main <filename>util-linux</filename> package has
4790 runtime dependencies (i.e.
4791 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
4792 on the <filename>util-linux-su</filename> package
4793 when "pam" is in
4794 <filename>DISTRO_FEATURES</filename>.
4795 </para></listitem>
4796 <listitem><para>
4797 The <filename>switch_root</filename> program is now
4798 packaged in a separate "util-linux-switch-root"
4799 package for small initramfs images that do not need
4800 the whole <filename>util-linux</filename> package or
4801 the busybox binary, which are both much larger than
4802 <filename>switch_root</filename>.
4803 The main <filename>util-linux</filename> package has
4804 a recommended runtime dependency (i.e.
4805 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
4806 on the <filename>util-linux-switch-root</filename> package.
4807 </para></listitem>
4808 <listitem><para>
4809 The <filename>ionice</filename> program is now
4810 packaged in a separate "util-linux-ionice" package.
4811 The main <filename>util-linux</filename> package has
4812 a recommended runtime dependency (i.e.
4813 <filename>RRECOMMENDS</filename>)
4814 on the <filename>util-linux-ionice</filename> package.
4815 </para></listitem>
4816 </itemizedlist>
4817 </para></listitem>
4818 <listitem><para>
4819 <emphasis><filename>initscripts</filename>:</emphasis>
4820 The <filename>sushell</filename> program is now packaged in
4821 a separate "initscripts-sushell" package.
4822 This packaging change allows systems to pull
4823 <filename>sushell</filename> in when
4824 <filename>selinux</filename> is enabled.
4825 The change also eliminates needing to pull in the entire
4826 <filename>initscripts</filename> package.
4827 The main <filename>initscripts</filename> package has a
4828 runtime dependency (i.e. <filename>RDEPENDS</filename>)
4829 on the <filename>sushell</filename> package when
4830 "selinux" is in <filename>DISTRO_FEATURES</filename>.
4831 </para></listitem>
4832 <listitem><para>
4833 <emphasis><filename>glib-2.0</filename>:</emphasis>
4834 The <filename>glib-2.0</filename> package now has a
4835 recommended runtime dependency (i.e.
4836 <filename>RRECOMMENDS</filename>) on the
4837 <filename>shared-mime-info</filename> package, since large
4838 portions of GIO are not useful without the MIME database.
4839 You can remove the dependency by using the
4840 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
4841 variable if <filename>shared-mime-info</filename> is too
4842 large and is not required.
4843 </para></listitem>
4844 <listitem><para>
4845 <emphasis>Go Standard Runtime:</emphasis>
4846 The Go standard runtime has been split out from the main
4847 <filename>go</filename> recipe into a separate
4848 <filename>go-runtime</filename> recipe.
4849 </para></listitem>
4850 </itemizedlist>
4851 </para>
4852 </section>
4853
4854 <section id='migration-2.4-removed-recipes'>
4855 <title>Removed Recipes</title>
4856
4857 <para>
4858 The following recipes have been removed:
4859 <itemizedlist>
4860 <listitem><para>
4861 <emphasis><filename>acpitests</filename>:</emphasis>
4862 This recipe is not maintained.
4863 </para></listitem>
4864 <listitem><para>
4865 <emphasis><filename>autogen-native</filename>:</emphasis>
4866 No longer required by Grub, oe-core, or meta-oe.
4867 </para></listitem>
4868 <listitem><para>
4869 <emphasis><filename>bdwgc</filename>:</emphasis>
4870 Nothing in OpenEmbedded-Core requires this recipe.
4871 It has moved to meta-oe.
4872 </para></listitem>
4873 <listitem><para>
4874 <emphasis><filename>byacc</filename>:</emphasis>
4875 This recipe was only needed by rpm 5.x and has moved to
4876 meta-oe.
4877 </para></listitem>
4878 <listitem><para>
4879 <emphasis><filename>gcc (5.4)</filename>:</emphasis>
4880 The 5.4 series dropped the recipe in favor of 6.3 / 7.2.
4881 </para></listitem>
4882 <listitem><para>
4883 <emphasis><filename>gnome-common</filename>:</emphasis>
4884 Deprecated upstream and no longer needed.
4885 </para></listitem>
4886 <listitem><para>
4887 <emphasis><filename>go-bootstrap-native</filename>:</emphasis>
4888 Go 1.9 does its own bootstrapping so this recipe has been
4889 removed.
4890 </para></listitem>
4891 <listitem><para>
4892 <emphasis><filename>guile</filename>:</emphasis>
4893 This recipe was only needed by
4894 <filename>autogen-native</filename> and
4895 <filename>remake</filename>.
4896 The recipe is no longer needed by either of these programs.
4897 </para></listitem>
4898 <listitem><para>
4899 <emphasis><filename>libclass-isa-perl</filename>:</emphasis>
4900 This recipe was previously needed for LSB 4, no longer
4901 needed.
4902 </para></listitem>
4903 <listitem><para>
4904 <emphasis><filename>libdumpvalue-perl</filename>:</emphasis>
4905 This recipe was previously needed for LSB 4, no longer
4906 needed.
4907 </para></listitem>
4908 <listitem><para>
4909 <emphasis><filename>libenv-perl</filename>:</emphasis>
4910 This recipe was previously needed for LSB 4, no longer
4911 needed.
4912 </para></listitem>
4913 <listitem><para>
4914 <emphasis><filename>libfile-checktree-perl</filename>:</emphasis>
4915 This recipe was previously needed for LSB 4, no longer
4916 needed.
4917 </para></listitem>
4918 <listitem><para>
4919 <emphasis><filename>libi18n-collate-perl</filename>:</emphasis>
4920 This recipe was previously needed for LSB 4, no longer
4921 needed.
4922 </para></listitem>
4923 <listitem><para>
4924 <emphasis><filename>libiconv</filename>:</emphasis>
4925 This recipe was only needed for <filename>uclibc</filename>,
4926 which was removed in the previous release.
4927 <filename>glibc</filename> and <filename>musl</filename>
4928 have their own implementations.
4929 <filename>meta-mingw</filename> still needs
4930 <filename>libiconv</filename>, so it has
4931 been moved to <filename>meta-mingw</filename>.
4932 </para></listitem>
4933 <listitem><para>
4934 <emphasis><filename>libpng12</filename>:</emphasis>
4935 This recipe was previously needed for LSB. The current
4936 <filename>libpng</filename> is 1.6.x.
4937 </para></listitem>
4938 <listitem><para>
4939 <emphasis><filename>libpod-plainer-perl</filename>:</emphasis>
4940 This recipe was previously needed for LSB 4, no longer
4941 needed.
4942 </para></listitem>
4943 <listitem><para>
4944 <emphasis><filename>linux-yocto (4.1)</filename>:</emphasis>
4945 This recipe was removed in favor of 4.4, 4.9, 4.10 and 4.12.
4946 </para></listitem>
4947 <listitem><para>
4948 <emphasis><filename>mailx</filename>:</emphasis>
4949 This recipe was previously only needed for LSB
4950 compatibility, and upstream is defunct.
4951 </para></listitem>
4952 <listitem><para>
4953 <emphasis><filename>mesa (git version only)</filename>:</emphasis>
4954 The git version recipe was stale with respect to the release
4955 version.
4956 </para></listitem>
4957 <listitem><para>
4958 <emphasis><filename>ofono (git version only)</filename>:</emphasis>
4959 The git version recipe was stale with respect to the release
4960 version.
4961 </para></listitem>
4962 <listitem><para>
4963 <emphasis><filename>portmap</filename>:</emphasis>
4964 This recipe is obsolete and is superseded by
4965 <filename>rpcbind</filename>.
4966 </para></listitem>
4967 <listitem><para>
4968 <emphasis><filename>python3-pygpgme</filename>:</emphasis>
4969 This recipe is old and unmaintained. It was previously
4970 required by <filename>dnf</filename>, which has switched
4971 to official <filename>gpgme</filename> Python bindings.
4972 </para></listitem>
4973 <listitem><para>
4974 <emphasis><filename>python-async</filename>:</emphasis>
4975 This recipe has been removed in favor of the Python 3
4976 version.
4977 </para></listitem>
4978 <listitem><para>
4979 <emphasis><filename>python-gitdb</filename>:</emphasis>
4980 This recipe has been removed in favor of the Python 3
4981 version.
4982 </para></listitem>
4983 <listitem><para>
4984 <emphasis><filename>python-git</filename>:</emphasis>
4985 This recipe was removed in favor of the Python 3
4986 version.
4987 </para></listitem>
4988 <listitem><para>
4989 <emphasis><filename>python-mako</filename>:</emphasis>
4990 This recipe was removed in favor of the Python 3
4991 version.
4992 </para></listitem>
4993 <listitem><para>
4994 <emphasis><filename>python-pexpect</filename>:</emphasis>
4995 This recipe was removed in favor of the Python 3 version.
4996 </para></listitem>
4997 <listitem><para>
4998 <emphasis><filename>python-ptyprocess</filename>:</emphasis>
4999 This recipe was removed in favor of Python the 3 version.
5000 </para></listitem>
5001 <listitem><para>
5002 <emphasis><filename>python-pycurl</filename>:</emphasis>
5003 Nothing is using this recipe in OpenEmbedded-Core
5004 (i.e. <filename>meta-oe</filename>).
5005 </para></listitem>
5006 <listitem><para>
5007 <emphasis><filename>python-six</filename>:</emphasis>
5008 This recipe was removed in favor of the Python 3 version.
5009 </para></listitem>
5010 <listitem><para>
5011 <emphasis><filename>python-smmap</filename>:</emphasis>
5012 This recipe was removed in favor of the Python 3 version.
5013 </para></listitem>
5014 <listitem><para>
5015 <emphasis><filename>remake</filename>:</emphasis>
5016 Using <filename>remake</filename> as the provider of
5017 <filename>virtual/make</filename> is broken.
5018 Consequently, this recipe is not needed in OpenEmbedded-Core.
5019 </para></listitem>
5020 </itemizedlist>
5021 </para>
5022 </section>
5023
5024 <section id='migration-2.4-kernel-device-tree-move'>
5025 <title>Kernel Device Tree Move</title>
5026
5027 <para>
5028 Kernel Device Tree support is now easier to enable in a kernel
5029 recipe.
5030 The Device Tree code has moved to a
5031 <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
5032 class.
5033 Functionality is automatically enabled for any recipe that inherits
5034 the
5035 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
5036 class and sets the
5037 <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link>
5038 variable.
5039 The previous mechanism for doing this,
5040 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>,
5041 is still available to avoid breakage, but triggers a
5042 deprecation warning.
5043 Future releases of the Yocto Project will remove
5044 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>.
5045 It is advisable to remove any <filename>require</filename>
5046 statements that request
5047 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>
5048 from any custom kernel recipes you might have.
5049 This will avoid breakage in post 2.4 releases.
5050 </para>
5051 </section>
5052
5053 <section id='migration-2.4-package-qa-changes'>
5054 <title>Package QA Changes</title>
5055
5056 <para>
5057 The following package QA changes took place:
5058 <itemizedlist>
5059 <listitem><para>
5060 The "unsafe-references-in-scripts" QA check has been
5061 removed.
5062 </para></listitem>
5063 <listitem><para>
5064 If you refer to <filename>${COREBASE}/LICENSE</filename>
5065 within
5066 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
5067 you receive a warning because this file is a description of
5068 the license for OE-Core.
5069 Use <filename>${COMMON_LICENSE_DIR}/MIT</filename>
5070 if your recipe is MIT-licensed and you cannot use the
5071 preferred method of referring to a file within the source
5072 tree.
5073 </para></listitem>
5074 </itemizedlist>
5075 </para>
5076 </section>
5077
5078 <section id='migration-2.4-readme-changes'>
5079 <title><filename>README</filename> File Changes</title>
5080
5081 <para>
5082 The following are changes to <filename>README</filename> files:
5083 <itemizedlist>
5084 <listitem><para>
5085 The main Poky <filename>README</filename> file has been
5086 moved to the <filename>meta-poky</filename> layer and
5087 has been renamed <filename>README.poky</filename>.
5088 A symlink has been created so that references to the old
5089 location work.
5090 </para></listitem>
5091 <listitem><para>
5092 The <filename>README.hardware</filename> file has been moved
5093 to <filename>meta-yocto-bsp</filename>.
5094 A symlink has been created so that references to the old
5095 location work.
5096 </para></listitem>
5097 <listitem><para>
5098 A <filename>README.qemu</filename> file has been created
5099 with coverage of the <filename>qemu*</filename> machines.
5100 </para></listitem>
5101 </itemizedlist>
5102 </para>
5103 </section>
5104
5105 <section id='migration-2.4-miscellaneous-changes'>
5106 <title>Miscellaneous Changes</title>
5107
5108 <para>
5109 The following are additional changes:
5110 <itemizedlist>
5111 <listitem><para>
5112 The <filename>ROOTFS_PKGMANAGE_BOOTSTRAP</filename>
5113 variable and any references to it have been removed.
5114 You should remove this variable from any custom recipes.
5115 </para></listitem>
5116 <listitem><para>
5117 The <filename>meta-yocto</filename> directory has been
5118 removed.
5119 <note>
5120 In the Yocto Project 2.1 release
5121 <filename>meta-yocto</filename> was renamed to
5122 <filename>meta-poky</filename> and the
5123 <filename>meta-yocto</filename> subdirectory remained
5124 to avoid breaking existing configurations.
5125 </note>
5126 </para></listitem>
5127 <listitem><para>
5128 The <filename>maintainers.inc</filename> file, which tracks
5129 maintainers by listing a primary person responsible for each
5130 recipe in OE-Core, has been moved from
5131 <filename>meta-poky</filename> to OE-Core (i.e. from
5132 <filename>meta-poky/conf/distro/include</filename> to
5133 <filename>meta/conf/distro/include</filename>).
5134 </para></listitem>
5135 <listitem><para>
5136 The
5137 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
5138 class now makes a single commit per build rather than one
5139 commit per subdirectory in the repository.
5140 This behavior assumes the commits are enabled with
5141 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
5142 = "1", which is typical.
5143 Previously, the <filename>buildhistory</filename> class made
5144 one commit per subdirectory in the repository in order to
5145 make it easier to see the changes for a particular
5146 subdirectory.
5147 To view a particular change, specify that subdirectory as
5148 the last parameter on the <filename>git show</filename>
5149 or <filename>git diff</filename> commands.
5150 </para></listitem>
5151 <listitem><para>
5152 The <filename>x86-base.inc</filename> file, which is
5153 included by all x86-based machine configurations, now sets
5154 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
5155 using <filename>?=</filename> to "live" rather than
5156 appending with <filename>+=</filename>.
5157 This change makes the default easier to override.
5158 </para></listitem>
5159 <listitem><para>
5160 BitBake fires multiple "BuildStarted" events when
5161 multiconfig is enabled (one per configuration).
5162 For more information, see the
5163 "<ulink url='&YOCTO_DOCS_BB_URL;#events'>Events</ulink>"
5164 section in the BitBake User Manual.
5165 </para></listitem>
5166 <listitem><para>
5167 By default, the <filename>security_flags.inc</filename> file
5168 sets a
5169 <link linkend='var-GCCPIE'><filename>GCCPIE</filename></link>
5170 variable with an option to enable Position Independent
5171 Executables (PIE) within <filename>gcc</filename>.
5172 Enabling PIE in the GNU C Compiler (GCC), makes Return
5173 Oriented Programming (ROP) attacks much more difficult to
5174 execute.
5175 </para></listitem>
5176 <listitem><para>
5177 OE-Core now provides a
5178 <filename>bitbake-layers</filename> plugin that implements
5179 a "create-layer" subcommand.
5180 The implementation of this subcommand has resulted in the
5181 <filename>yocto-layer</filename> script being deprecated and
5182 will likely be removed in the next Yocto Project release.
5183 </para></listitem>
5184 <listitem><para>
5185 The <filename>vmdk</filename>, <filename>vdi</filename>,
5186 and <filename>qcow2</filename> image file types are now
5187 used in conjunction with the "wic" image type through
5188 <filename>CONVERSION_CMD</filename>.
5189 Consequently, the equivalent image types are now
5190 <filename>wic.vmdk</filename>, <filename>wic.vdi</filename>,
5191 and <filename>wic.qcow2</filename>, respectively.
5192 </para></listitem>
5193 <listitem><para>
5194 <filename>do_image_&lt;type&gt;[depends]</filename> has
5195 replaced <filename>IMAGE_DEPENDS_&lt;type&gt;</filename>.
5196 If you have your own classes that implement custom image
5197 types, then you need to update them.
5198 </para></listitem>
5199 <listitem><para>
5200 OpenSSL 1.1 has been introduced.
5201 However, the default is still 1.0.x through the
5202 <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link>
5203 variable.
5204 This preference is set is due to the remaining compatibility
5205 issues with other software.
5206 The
5207 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
5208 variable in the openssl 1.0 recipe now includes "openssl10"
5209 as a marker that can be used in
5210 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
5211 within recipes that build software that still depend on
5212 OpenSSL 1.0.
5213 </para></listitem>
5214 <listitem><para>
5215 To ensure consistent behavior, BitBake's "-r" and "-R"
5216 options (i.e. prefile and postfile), which are used to
5217 read or post-read additional configuration files from the
5218 command line, now only affect the current BitBake command.
5219 Before these BitBake changes, these options would "stick"
5220 for future executions.
5221 </para></listitem>
5222 </itemizedlist>
5223 </para>
5224 </section>
5225</section>
5226
5227<section id='moving-to-the-yocto-project-2.5-release'>
5228 <title>Moving to the Yocto Project 2.5 Release</title>
5229
5230 <para>
5231 This section provides migration information for moving to the
5232 Yocto Project 2.5 Release from the prior release.
5233 </para>
5234
5235 <section id='migration-2.5-packaging-changes'>
5236 <title>Packaging Changes</title>
5237
5238 <para>
5239 This section provides information about packaging changes that have
5240 occurred:
5241 <itemizedlist>
5242 <listitem><para>
5243 <emphasis><filename>bind-libs</filename>:</emphasis>
5244 The libraries packaged by the bind recipe are in a
5245 separate <filename>bind-libs</filename> package.
5246 </para></listitem>
5247 <listitem><para>
5248 <emphasis><filename>libfm-gtk</filename>:</emphasis>
5249 The <filename>libfm</filename> GTK+ bindings are split into
5250 a separate <filename>libfm-gtk</filename> package.
5251 </para></listitem>
5252 <listitem><para>
5253 <emphasis><filename>flex-libfl</filename>:</emphasis>
5254 The flex recipe splits out libfl into a separate
5255 <filename>flex-libfl</filename> package to avoid too many
5256 dependencies being pulled in where only the library is
5257 needed.
5258 </para></listitem>
5259 <listitem><para>
5260 <emphasis><filename>grub-efi</filename>:</emphasis>
5261 The <filename>grub-efi</filename> configuration is split
5262 into a separate <filename>grub-bootconf</filename>
5263 recipe.
5264 However, the dependency relationship from
5265 <filename>grub-efi</filename> is through a
5266 virtual/grub-bootconf provider making it possible to have
5267 your own recipe provide the dependency.
5268 Alternatively, you can use a BitBake append file to bring
5269 the configuration back into the
5270 <filename>grub-efi</filename> recipe.
5271 </para></listitem>
5272 <listitem><para>
5273 <emphasis>armv7a Legacy Package Feed Support:</emphasis>
5274 Legacy support is removed for transitioning from
5275 <filename>armv7a</filename> to
5276 <filename>armv7a-vfp-neon</filename> in package feeds,
5277 which was previously enabled by setting
5278 <filename>PKGARCHCOMPAT_ARMV7A</filename>.
5279 This transition occurred in 2011 and active package feeds
5280 should by now be updated to the new naming.
5281 </para></listitem>
5282 </itemizedlist>
5283 </para>
5284 </section>
5285
5286 <section id='migration-2.5-removed-recipes'>
5287 <title>Removed Recipes</title>
5288
5289 <para>
5290 The following recipes have been removed:
5291 <itemizedlist>
5292 <listitem><para>
5293 <emphasis><filename>gcc</filename>:</emphasis>
5294 The version 6.4 recipes are replaced by 7.x.
5295 </para></listitem>
5296 <listitem><para>
5297 <emphasis><filename>gst-player</filename>:</emphasis>
5298 Renamed to <filename>gst-examples</filename> as per
5299 upstream.
5300 </para></listitem>
5301 <listitem><para>
5302 <emphasis><filename>hostap-utils</filename>:</emphasis>
5303 This software package is obsolete.
5304 </para></listitem>
5305 <listitem><para>
5306 <emphasis><filename>latencytop</filename>:</emphasis>
5307 This recipe is no longer maintained upstream.
5308 The last release was in 2009.
5309 </para></listitem>
5310 <listitem><para>
5311 <emphasis><filename>libpfm4</filename>:</emphasis>
5312 The only file that requires this recipe is
5313 <filename>oprofile</filename>, which has been removed.
5314 </para></listitem>
5315 <listitem><para>
5316 <emphasis><filename>linux-yocto</filename>:</emphasis>
5317 The version 4.4, 4.9, and 4.10 recipes have been removed.
5318 Versions 4.12, 4.14, and 4.15 remain.
5319 </para></listitem>
5320 <listitem><para>
5321 <emphasis><filename>man</filename>:</emphasis>
5322 This recipe has been replaced by modern
5323 <filename>man-db</filename>
5324 </para></listitem>
5325 <listitem><para>
5326 <emphasis><filename>mkelfimage</filename>:</emphasis>
5327 This tool has been removed in the upstream coreboot project,
5328 and is no longer needed with the removal of the ELF image
5329 type.
5330 </para></listitem>
5331 <listitem><para>
5332 <emphasis><filename>nativesdk-postinst-intercept</filename>:</emphasis>
5333 This recipe is not maintained.
5334 </para></listitem>
5335 <listitem><para>
5336 <emphasis><filename>neon</filename>:</emphasis>
5337 This software package is no longer maintained upstream and
5338 is no longer needed by anything in OpenEmbedded-Core.
5339 </para></listitem>
5340 <listitem><para>
5341 <emphasis><filename>oprofile</filename>:</emphasis>
5342 The functionality of this recipe is replaced by
5343 <filename>perf</filename> and keeping compatibility on
5344 an ongoing basis with <filename>musl</filename> is
5345 difficult.
5346 </para></listitem>
5347 <listitem><para>
5348 <emphasis><filename>pax</filename>:</emphasis>
5349 This software package is obsolete.
5350 </para></listitem>
5351 <listitem><para>
5352 <emphasis><filename>stat</filename>:</emphasis>
5353 This software package is not maintained upstream.
5354 <filename>coreutils</filename> provides a modern stat binary.
5355 </para></listitem>
5356 <listitem><para>
5357 <emphasis><filename>zisofs-tools-native</filename>:</emphasis>
5358 This recipe is no longer needed because the compressed
5359 ISO image feature has been removed.
5360 </para></listitem>
5361 </itemizedlist>
5362 </para>
5363 </section>
5364
5365 <section id='migration-2.5-scripts-and-tools-changes'>
5366 <title>Scripts and Tools Changes</title>
5367
5368 <para>
5369 The following are changes to scripts and tools:
5370 <itemizedlist>
5371 <listitem><para>
5372 <emphasis><filename>yocto-bsp</filename>,
5373 <filename>yocto-kernel</filename>, and
5374 <filename>yocto-layer</filename></emphasis>:
5375 The <filename>yocto-bsp</filename>,
5376 <filename>yocto-kernel</filename>, and
5377 <filename>yocto-layer</filename> scripts previously shipped
5378 with poky but not in OpenEmbedded-Core have been removed.
5379 These scripts are not maintained and are outdated.
5380 In many cases, they are also limited in scope.
5381 The <filename>bitbake-layers create-layer</filename> command
5382 is a direct replacement for <filename>yocto-layer</filename>.
5383 See the documentation to create a BSP or kernel recipe in
5384 the
5385 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-kernel-recipe-example'>BSP Kernel Recipe Example</ulink>"
5386 section.
5387 </para></listitem>
5388 <listitem><para>
5389 <emphasis><filename>devtool finish</filename>:</emphasis>
5390 <filename>devtool finish</filename> now exits with an error
5391 if there are uncommitted changes or a rebase/am in progress
5392 in the recipe's source repository.
5393 If this error occurs, there might be uncommitted changes
5394 that will not be included in updates to the patches applied
5395 by the recipe.
5396 A -f/--force option is provided for situations that the
5397 uncommitted changes are inconsequential and you want to
5398 proceed regardless.
5399 </para></listitem>
5400 <listitem><para>
5401 <emphasis><filename>scripts/oe-setup-rpmrepo</filename> script:</emphasis>
5402 The functionality of
5403 <filename>scripts/oe-setup-rpmrepo</filename> is replaced by
5404 <filename>bitbake package-index</filename>.
5405 </para></listitem>
5406 <listitem><para>
5407 <emphasis><filename>scripts/test-dependencies.sh</filename> script:</emphasis>
5408 The script is largely made obsolete by the
5409 recipe-specific sysroots functionality introduced in the
5410 previous release.
5411 </para></listitem>
5412 </itemizedlist>
5413 </para>
5414 </section>
5415
5416 <section id='migration-2.5-bitbake-changes'>
5417 <title>BitBake Changes</title>
5418
5419 <para>
5420 The following are BitBake changes:
5421 <itemizedlist>
5422 <listitem><para>
5423 The <filename>--runall</filename> option has changed.
5424 There are two different behaviors people might want:
5425 <itemizedlist>
5426 <listitem><para>
5427 <emphasis>Behavior A:</emphasis>
5428 For a given target (or set of targets) look through
5429 the task graph and run task X only if it is present
5430 and will be built.
5431 </para></listitem>
5432 <listitem><para>
5433 <emphasis>Behavior B:</emphasis>
5434 For a given target (or set of targets) look through
5435 the task graph and run task X if any recipe in the
5436 taskgraph has such a target, even if it is not in
5437 the original task graph.
5438 </para></listitem>
5439 </itemizedlist>
5440 The <filename>--runall</filename> option now performs
5441 "Behavior B".
5442 Previously <filename>--runall</filename> behaved like
5443 "Behavior A".
5444 A <filename>--runonly</filename> option has been added to
5445 retain the ability to perform "Behavior A".
5446 </para></listitem>
5447 <listitem><para>
5448 Several explicit "run this task for all recipes in the
5449 dependency tree" tasks have been removed (e.g.
5450 <filename>fetchall</filename>,
5451 <filename>checkuriall</filename>, and the
5452 <filename>*all</filename> tasks provided by the
5453 <filename>distrodata</filename> and
5454 <filename>archiver</filename> classes).
5455 There is a BitBake option to complete this for any arbitrary
5456 task. For example:
5457 <literallayout class='monospaced'>
5458 bitbake &lt;target&gt; -c fetchall
5459 </literallayout>
5460 should now be replaced with:
5461 <literallayout class='monospaced'>
5462 bitbake &lt;target&gt; --runall=fetch
5463 </literallayout>
5464 </para></listitem>
5465 </itemizedlist>
5466 </para>
5467 </section>
5468
5469 <section id='migration-2.5-python-and-python3-changes'>
5470 <title>Python and Python 3 Changes</title>
5471
5472 <para>
5473 The following are auto-packaging changes to Python and Python 3:
5474 </para>
5475 <para>
5476 The script-managed <filename>python-*-manifest.inc</filename> files
5477 that were previously used to generate Python and Python 3
5478 packages have been replaced with a JSON-based file that is
5479 easier to read and maintain.
5480 A new task is available for maintainers of the Python recipes to
5481 update the JSON file when upgrading to new Python versions.
5482 You can now edit the file directly instead of having to edit a
5483 script and run it to update the file.
5484 </para>
5485 <para>
5486 One particular change to note is that the Python recipes no longer
5487 have build-time provides for their packages.
5488 This assumes <filename>python-foo</filename> is one of the packages
5489 provided by the Python recipe.
5490 You can no longer run <filename>bitbake python-foo</filename> or
5491 have a <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> on
5492 <filename>python-foo</filename>, but doing either of the following
5493 causes the package to work as expected:
5494 <literallayout class='monospaced'>
5495 IMAGE_INSTALL_append = " python-foo"
5496 </literallayout>
5497 or
5498 <literallayout class='monospaced'>
5499 RDEPENDS_${PN} = "python-foo"
5500 </literallayout>
5501 The earlier build-time provides behavior was a quirk of the way the
5502 Python manifest file was created.
5503 For more information on this change please see
5504 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce'>this commit</ulink>.
5505 </para>
5506 </section>
5507
5508 <section id='migration-2.5-miscellaneous-changes'>
5509 <title>Miscellaneous Changes</title>
5510
5511 <para>
5512 The following are additional changes:
5513 <itemizedlist>
5514 <listitem><para>
5515 The <filename>kernel</filename> class supports building
5516 packages for multiple kernels.
5517 If your kernel recipe or <filename>.bbappend</filename> file
5518 mentions packaging at all, you should replace references to
5519 the kernel in package names with
5520 <filename>${KERNEL_PACKAGE_NAME}</filename>.
5521 For example, if you disable automatic installation of the
5522 kernel image using
5523 <filename>RDEPENDS_kernel-base = ""</filename> you can avoid
5524 warnings using
5525 <filename>RDEPENDS_${KERNEL_PACKAGE_NAME}-base = ""</filename>
5526 instead.
5527 </para></listitem>
5528 <listitem><para>
5529 The <filename>buildhistory</filename> class commits changes
5530 to the repository by default so you no longer need to set
5531 <filename>BUILDHISTORY_COMMIT = "1"</filename>.
5532 If you want to disable commits you need to set
5533 <filename>BUILDHISTORY_COMMIT = "0"</filename> in your
5534 configuration.
5535 </para></listitem>
5536 <listitem><para>
5537 The <filename>beaglebone</filename> reference machine has
5538 been renamed to <filename>beaglebone-yocto</filename>.
5539 The <filename>beaglebone-yocto</filename> BSP is a reference
5540 implementation using only mainline components available in
5541 OpenEmbedded-Core and <filename>meta-yocto-bsp</filename>,
5542 whereas Texas Instruments maintains a full-featured BSP in
5543 the <filename>meta-ti</filename> layer.
5544 This rename avoids the previous name clash that existed
5545 between the two BSPs.
5546 </para></listitem>
5547 <listitem><para>
5548 The <filename>update-alternatives</filename> class no longer
5549 works with SysV <filename>init</filename> scripts because
5550 this usage has been problematic.
5551 Also, the <filename>sysklogd</filename> recipe no longer
5552 uses <filename>update-alternatives</filename> because it is
5553 incompatible with other implementations.
5554 </para></listitem>
5555 <listitem><para>
5556 By default, the
5557 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
5558 class uses <filename>ninja</filename> instead of
5559 <filename>make</filename> for building.
5560 This improves build performance.
5561 If a recipe is broken with <filename>ninja</filename>, then
5562 the recipe can set
5563 <filename>OECMAKE_GENERATOR = "Unix Makefiles"</filename>
5564 to change back to <filename>make</filename>.
5565 </para></listitem>
5566 <listitem><para>
5567 The previously deprecated <filename>base_*</filename>
5568 functions have been removed in favor of their replacements
5569 in <filename>meta/lib/oe</filename> and
5570 <filename>bitbake/lib/bb</filename>.
5571 These are typically used from recipes and classes.
5572 Any references to the old functions must be updated.
5573 The following table shows the removed functions and their
5574 replacements:
5575
5576 <literallayout class='monospaced'>
5577 <emphasis>Removed</emphasis> <emphasis>Replacement</emphasis>
5578 ============================ ============================
5579 base_path_join() oe.path.join()
5580 base_path_relative() oe.path.relative()
5581 base_path_out() oe.path.format_display()
5582 base_read_file() oe.utils.read_file()
5583 base_ifelse() oe.utils.ifelse()
5584 base_conditional() oe.utils.conditional()
5585 base_less_or_equal() oe.utils.less_or_equal()
5586 base_version_less_or_equal() oe.utils.version_less_or_equal()
5587 base_contains() bb.utils.contains()
5588 base_both_contain() oe.utils.both_contain()
5589 base_prune_suffix() oe.utils.prune_suffix()
5590 oe_filter() oe.utils.str_filter()
5591 oe_filter_out() oe.utils.str_filter_out() (or use the _remove operator).
5592 </literallayout>
5593 </para></listitem>
5594 <listitem><para>
5595 Using <filename>exit 1</filename> to explicitly defer a
5596 postinstall script until first boot is now deprecated since
5597 it is not an obvious mechanism and can mask actual errors.
5598 If you want to explicitly defer a postinstall to first boot
5599 on the target rather than at <filename>rootfs</filename>
5600 creation time, use
5601 <filename>pkg_postinst_ontarget()</filename>
5602 or call
5603 <filename>postinst_intercept delay_to_first_boot</filename>
5604 from <filename>pkg_postinst()</filename>.
5605 Any failure of a <filename>pkg_postinst()</filename>
5606 script (including <filename>exit 1</filename>)
5607 will trigger a warning during
5608 <filename>do_rootfs</filename>.</para>
5609
5610 <para>For more information, see the
5611 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
5612 section in the Yocto Project Development Tasks Manual.
5613 </para></listitem>
5614 <listitem><para>
5615 The <filename>elf</filename> image type has been removed.
5616 This image type was removed because the
5617 <filename>mkelfimage</filename> tool
5618 that was required to create it is no longer provided by
5619 coreboot upstream and required updating every time
5620 <filename>binutils</filename> updated.
5621 </para></listitem>
5622 <listitem><para>
5623 Support for .iso image compression (previously enabled
5624 through <filename>COMPRESSISO = "1"</filename>) has been
5625 removed.
5626 The userspace tools (<filename>zisofs-tools</filename>) are
5627 unmaintained and <filename>squashfs</filename> provides
5628 better performance and compression.
5629 In order to build a live image with squashfs+lz4 compression
5630 enabled you should now set
5631 <filename>LIVE_ROOTFS_TYPE = "squashfs-lz4"</filename>
5632 and ensure that <filename>live</filename>
5633 is in <filename>IMAGE_FSTYPES</filename>.
5634 </para></listitem>
5635 <listitem><para>
5636 Recipes with an unconditional dependency on
5637 <filename>libpam</filename> are only buildable with
5638 <filename>pam</filename> in
5639 <filename>DISTRO_FEATURES</filename>.
5640 If the dependency is truly optional then it is recommended
5641 that the dependency be conditional upon
5642 <filename>pam</filename> being in
5643 <filename>DISTRO_FEATURES</filename>.
5644 </para></listitem>
5645 <listitem><para>
5646 For EFI-based machines, the bootloader
5647 (<filename>grub-efi</filename> by default) is installed into
5648 the image at /boot.
5649 Wic can be used to split the bootloader into separate boot
5650 and rootfs partitions if necessary.
5651 </para></listitem>
5652 <listitem><para>
5653 Patches whose context does not match exactly (i.e. where
5654 patch reports "fuzz" when applying) will generate a
5655 warning.
5656 For an example of this see
5657 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=cc97bc08125b63821ce3f616771830f77c456f57'>this commit</ulink>.
5658 </para></listitem>
5659 <listitem><para>
5660 Layers are expected to set
5661 <filename>LAYERSERIES_COMPAT_layername</filename>
5662 to match the version(s) of OpenEmbedded-Core they are
5663 compatible with.
5664 This is specified as codenames using spaces to separate
5665 multiple values (e.g. "rocko sumo").
5666 If a layer does not set
5667 <filename>LAYERSERIES_COMPAT_layername</filename>, a warning
5668 will is shown.
5669 If a layer sets a value that does not include the current
5670 version ("sumo" for the 2.5 release), then an error will be
5671 produced.
5672 </para></listitem>
5673 <listitem><para>
5674 The <filename>TZ</filename> environment variable is set to
5675 "UTC" within the build environment in order to fix
5676 reproducibility problems in some recipes.
5677 </para></listitem>
5678 </itemizedlist>
5679 </para>
5680 </section>
5681</section>
5682
5683<section id='moving-to-the-yocto-project-2.6-release'>
5684 <title>Moving to the Yocto Project 2.6 Release</title>
5685
5686 <para>
5687 This section provides migration information for moving to the
5688 Yocto Project 2.6 Release from the prior release.
5689 </para>
5690
5691 <section id='migration-2.6-gcc-changes'>
5692 <title>GCC 8.2 is Now Used by Default</title>
5693
5694 <para>
5695 The GNU Compiler Collection version 8.2 is now used by default
5696 for compilation.
5697 For more information on what has changed in the GCC 8.x release,
5698 see
5699 <ulink url='https://gcc.gnu.org/gcc-8/changes.html'></ulink>.
5700 </para>
5701
5702 <para>
5703 If you still need to compile with version 7.x, GCC 7.3 is
5704 also provided.
5705 You can select this version by setting the
5706 and can be selected by setting the
5707 <link linkend='var-GCCVERSION'><filename>GCCVERSION</filename></link>
5708 variable to "7.%" in your configuration.
5709 </para>
5710 </section>
5711
5712 <section id='migration-2.6-removed-recipes'>
5713 <title>Removed Recipes</title>
5714
5715 <para>
5716 The following recipes have been removed:
5717 <literallayout class='monospaced'>
5718 <emphasis><filename>beecrypt</filename>:</emphasis> No longer needed since moving to RPM 4.
5719 <emphasis><filename>bigreqsproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5720 <emphasis><filename>calibrateproto</filename>:</emphasis> Removed in favor of <filename>xinput</filename>.
5721 <emphasis><filename>compositeproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5722 <emphasis><filename>damageproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5723 <emphasis><filename>dmxproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5724 <emphasis><filename>dri2proto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5725 <emphasis><filename>dri3proto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5726 <emphasis><filename>eee-acpi-scripts</filename>:</emphasis> Became obsolete.
5727 <emphasis><filename>fixesproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5728 <emphasis><filename>fontsproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5729 <emphasis><filename>fstests</filename>:</emphasis> Became obsolete.
5730 <emphasis><filename>gccmakedep</filename>:</emphasis> No longer used.
5731 <emphasis><filename>glproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5732 <emphasis><filename>gnome-desktop3</filename>:</emphasis> No longer needed. This recipe has moved to <filename>meta-oe</filename>.
5733 <emphasis><filename>icon-naming-utils</filename>:</emphasis> No longer used since the Sato theme was removed in 2016.
5734 <emphasis><filename>inputproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5735 <emphasis><filename>kbproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5736 <emphasis><filename>libusb-compat</filename>:</emphasis> Became obsolete.
5737 <emphasis><filename>libuser</filename>:</emphasis> Became obsolete.
5738 <emphasis><filename>libnfsidmap</filename>:</emphasis> No longer an external requirement since <filename>nfs-utils</filename> 2.2.1. <filename>libnfsidmap</filename> is now integrated.
5739 <emphasis><filename>libxcalibrate</filename>:</emphasis> No longer needed with <filename>xinput</filename>
5740 <emphasis><filename>mktemp</filename>:</emphasis> Became obsolete. The <filename>mktemp</filename> command is provided by both <filename>busybox</filename> and <filename>coreutils</filename>.
5741 <emphasis><filename>ossp-uuid</filename>:</emphasis> Is not being maintained and has mostly been replaced by <filename>uuid.h</filename> in <filename>util-linux</filename>.
5742 <emphasis><filename>pax-utils</filename>:</emphasis> No longer needed. Previous QA tests that did use this recipe are now done at build time.
5743 <emphasis><filename>pcmciautils</filename>:</emphasis> Became obsolete.
5744 <emphasis><filename>pixz</filename>:</emphasis> No longer needed. <filename>xz</filename> now supports multi-threaded compression.
5745 <emphasis><filename>presentproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5746 <emphasis><filename>randrproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5747 <emphasis><filename>recordproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5748 <emphasis><filename>renderproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5749 <emphasis><filename>resourceproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5750 <emphasis><filename>scrnsaverproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5751 <emphasis><filename>trace-cmd</filename>:</emphasis> Became obsolete. <filename>perf</filename> replaced this recipe's functionally.
5752 <emphasis><filename>videoproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5753 <emphasis><filename>wireless-tools</filename>:</emphasis> Became obsolete. Superseded by <filename>iw</filename>.
5754 <emphasis><filename>xcmiscproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5755 <emphasis><filename>xextproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5756 <emphasis><filename>xf86dgaproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5757 <emphasis><filename>xf86driproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5758 <emphasis><filename>xf86miscproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5759 <emphasis><filename>xf86-video-omapfb</filename>:</emphasis> Became obsolete. Use kernel modesetting driver instead.
5760 <emphasis><filename>xf86-video-omap</filename>:</emphasis> Became obsolete. Use kernel modesetting driver instead.
5761 <emphasis><filename>xf86vidmodeproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5762 <emphasis><filename>xineramaproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5763 <emphasis><filename>xproto</filename>:</emphasis> Replaced by <filename>xorgproto</filename>.
5764 <emphasis><filename>yasm</filename>:</emphasis> No longer needed since previous usages are now satisfied by <filename>nasm</filename>.
5765 </literallayout>
5766 </para>
5767 </section>
5768
5769 <section id='migration-2.6-packaging-changes'>
5770 <title>Packaging Changes</title>
5771
5772 <para>
5773 The following packaging changes have been made:
5774 <itemizedlist>
5775 <listitem><para>
5776 <emphasis><filename>cmake</filename>:</emphasis>
5777 <filename>cmake.m4</filename> and
5778 <filename>toolchain</filename> files have been moved to the
5779 main package.
5780 </para></listitem>
5781 <listitem><para>
5782 <emphasis><filename>iptables</filename>:</emphasis>
5783 The <filename>iptables</filename> modules have been split
5784 into separate packages.
5785 </para></listitem>
5786 <listitem><para>
5787 <emphasis><filename>alsa-lib</filename>:</emphasis>
5788 <filename>libasound</filename> is now in the main
5789 <filename>alsa-lib</filename> package instead of
5790 <filename>libasound</filename>.
5791 </para></listitem>
5792 <listitem><para>
5793 <emphasis><filename>glibc</filename>:</emphasis>
5794 <filename>libnss-db</filename> is now in its own package
5795 along with a <filename>/var/db/makedbs.sh</filename>
5796 script to update databases.
5797 </para></listitem>
5798 <listitem><para>
5799 <emphasis><filename>python</filename> and <filename>python3</filename>:</emphasis>
5800 The main package has been removed from the recipe.
5801 You must install specific packages or
5802 <filename>python-modules</filename> /
5803 <filename>python3-modules</filename> for everything.
5804 </para></listitem>
5805 <listitem><para>
5806 <emphasis><filename>systemtap</filename>:</emphasis>
5807 Moved <filename>systemtap-exporter</filename> into its own
5808 package.
5809 </para></listitem>
5810 </itemizedlist>
5811 </para>
5812 </section>
5813
5814 <section id='migration-2.6-xorg-protocol-dependencies'>
5815 <title>XOrg Protocol dependencies</title>
5816
5817 <para>
5818 The "*proto" upstream repositories have been combined into one
5819 "xorgproto" repository.
5820 Thus, the corresponding recipes have also been combined into a
5821 single <filename>xorgproto</filename> recipe.
5822 Any recipes that depend upon the older <filename>*proto</filename>
5823 recipes need to be changed to depend on the newer
5824 <filename>xorgproto</filename> recipe instead.
5825 </para>
5826
5827 <para>
5828 For names of recipes removed because of this repository change,
5829 see the
5830 <link linkend="migration-2.6-removed-recipes">Removed Recipes</link>
5831 section.
5832 </para>
5833 </section>
5834
5835 <section id='migration-2.6-distutils-distutils3-fetching-dependencies'>
5836 <title><filename>distutils</filename> and <filename>distutils3</filename> Now Prevent Fetching Dependencies During the <filename>do_configure</filename> Task</title>
5837
5838 <para>
5839 Previously, it was possible for Python recipes that inherited
5840 the
5841 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>
5842 and
5843 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>
5844 classes to fetch code during the
5845 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
5846 task to satisfy dependencies mentioned in
5847 <filename>setup.py</filename> if those dependencies were not
5848 provided in the sysroot (i.e. recipes providing the dependencies
5849 were missing from
5850 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>).
5851 <note>
5852 This change affects classes beyond just the two mentioned
5853 (i.e. <filename>distutils</filename> and
5854 <filename>distutils3</filename>).
5855 Any recipe that inherits <filename>distutils*</filename>
5856 classes are affected.
5857 For example, the <filename>setuptools</filename> and
5858 <filename>setuptools3</filename> recipes are affected since
5859 they inherit the <filename>distutils*</filename> classes.
5860 </note>
5861 </para>
5862
5863 <para>
5864 Fetching these types of dependencies that are not provided in the
5865 sysroot negatively affects the ability to reproduce builds.
5866 This type of fetching is now explicitly disabled.
5867 Consequently, any missing dependencies in Python recipes that
5868 use these classes now result in an error during the
5869 <filename>do_configure</filename> task.
5870 </para>
5871 </section>
5872
5873 <section id='migration-2.6-linux-yocto-configuration-audit-issues-now-correctly-reported'>
5874 <title><filename>linux-yocto</filename> Configuration Audit Issues Now Correctly Reported</title>
5875
5876 <para>
5877 Due to a bug, the kernel configuration audit functionality was
5878 not writing out any resulting warnings during the build.
5879 This issue is now corrected.
5880 You might notice these warnings now if you have a custom kernel
5881 configuration with a <filename>linux-yocto</filename> style
5882 kernel recipe.
5883 </para>
5884 </section>
5885
5886 <section id='migration-2.6-image-kernel-artifact-naming-changes'>
5887 <title>Image/Kernel Artifact Naming Changes</title>
5888
5889 <para>
5890 The following changes have been made:
5891 <itemizedlist>
5892 <listitem><para>
5893 Name variables (e.g.
5894 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>)
5895 use a new <filename>IMAGE_VERSION_SUFFIX</filename>
5896 variable instead of
5897 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
5898 Using <filename>IMAGE_VERSION_SUFFIX</filename> allows
5899 easier and more direct changes.</para>
5900
5901 <para>The <filename>IMAGE_VERSION_SUFFIX</filename>
5902 variable is set in the
5903 <filename>bitbake.conf</filename> configuration file as
5904 follows:
5905 <literallayout class='monospaced'>
5906 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
5907 </literallayout>
5908 </para></listitem>
5909 <listitem><para>
5910 Several variables have changed names for consistency:
5911 <literallayout class='monospaced'>
5912 Old Variable Name New Variable Name
5913 ========================================================
5914 KERNEL_IMAGE_BASE_NAME <link linkend='var-KERNEL_IMAGE_NAME'>KERNEL_IMAGE_NAME</link>
5915 KERNEL_IMAGE_SYMLINK_NAME <link linkend='var-KERNEL_IMAGE_LINK_NAME'>KERNEL_IMAGE_LINK_NAME</link>
5916 MODULE_TARBALL_BASE_NAME <link linkend='var-MODULE_TARBALL_NAME'>MODULE_TARBALL_NAME</link>
5917 MODULE_TARBALL_SYMLINK_NAME <link linkend='var-MODULE_TARBALL_LINK_NAME'>MODULE_TARBALL_LINK_NAME</link>
5918 INITRAMFS_BASE_NAME <link linkend='var-INITRAMFS_NAME'>INITRAMFS_NAME</link>
5919 </literallayout>
5920 </para></listitem>
5921 <listitem><para>
5922 The <filename>MODULE_IMAGE_BASE_NAME</filename> variable
5923 has been removed.
5924 The module tarball name is now controlled directly with the
5925 <link linkend='var-MODULE_TARBALL_NAME'><filename>MODULE_TARBALL_NAME</filename></link>
5926 variable.
5927 </para></listitem>
5928 <listitem><para>
5929 The
5930 <link linkend='var-KERNEL_DTB_NAME'><filename>KERNEL_DTB_NAME</filename></link>
5931 and
5932 <link linkend='var-KERNEL_DTB_LINK_NAME'><filename>KERNEL_DTB_LINK_NAME</filename></link>
5933 variables have been introduced to control kernel Device
5934 Tree Binary (DTB) artifact names instead of mangling
5935 <filename>KERNEL_IMAGE_*</filename> variables.
5936 </para></listitem>
5937 <listitem><para>
5938 The
5939 <link linkend='var-KERNEL_FIT_NAME'><filename>KERNEL_FIT_NAME</filename></link>
5940 and
5941 <link linkend='var-KERNEL_FIT_LINK_NAME'><filename>KERNEL_FIT_LINK_NAME</filename></link>
5942 variables have been introduced to specify the name of
5943 flattened image tree (FIT) kernel images similar to other
5944 deployed artifacts.
5945 </para></listitem>
5946 <listitem><para>
5947 The
5948 <link linkend='var-MODULE_TARBALL_NAME'><filename>MODULE_TARBALL_NAME</filename></link>
5949 and
5950 <link linkend='var-MODULE_TARBALL_LINK_NAME'><filename>MODULE_TARBALL_LINK_NAME</filename></link>
5951 variable values no longer include the "module-" prefix or
5952 ".tgz" suffix.
5953 These parts are now hardcoded so that the values are
5954 consistent with other artifact naming variables.
5955 </para></listitem>
5956 <listitem><para>
5957 Added the
5958 <link linkend='var-INITRAMFS_LINK_NAME'><filename>INITRAMFS_LINK_NAME</filename></link>
5959 variable so that the symlink can be controlled similarly
5960 to other artifact types.
5961 </para></listitem>
5962 <listitem><para>
5963 <link linkend='var-INITRAMFS_NAME'><filename>INITRAMFS_NAME</filename></link>
5964 now uses
5965 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
5966 instead of
5967 "${PV}-${PR}-${MACHINE}-${DATETIME}", which
5968 makes it consistent with other variables.
5969 </para></listitem>
5970 </itemizedlist>
5971 </para>
5972 </section>
5973
5974 <section id='migration-2.6-serial-console-deprecated'>
5975 <title><filename>SERIAL_CONSOLE</filename> Deprecated</title>
5976
5977 <para>
5978 The
5979 <link linkend='var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></link>
5980 variable has been functionally replaced by the
5981 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
5982 variable for some time.
5983 With the Yocto Project 2.6 release,
5984 <filename>SERIAL_CONSOLE</filename> has been officially deprecated.
5985 </para>
5986
5987 <para>
5988 <filename>SERIAL_CONSOLE</filename> will continue to work as
5989 before for the 2.6 release.
5990 However, for the sake of future compatibility, it is recommended
5991 that you replace all instances of
5992 <filename>SERIAL_CONSOLE</filename> with
5993 <filename>SERIAL_CONSOLES</filename>.
5994 <note>
5995 The only difference in usage is that
5996 <filename>SERIAL_CONSOLES</filename> expects entries to be
5997 separated using semicolons as compared to
5998 <filename>SERIAL_CONSOLE</filename>, which expects spaces.
5999 </note>
6000 </para>
6001 </section>
6002
6003 <section id='migration-2.6-poky-sets-unknown-configure-option-to-qa-error'>
6004 <title>Configure Script Reports Unknown Options as Errors</title>
6005
6006 <para>
6007 If the configure script reports an unknown option, this now
6008 triggers a QA error instead of a warning.
6009 Any recipes that previously got away with specifying such unknown
6010 options now need to be fixed.
6011 </para>
6012 </section>
6013
6014 <section id='migration-2.6-override-changes'>
6015 <title>Override Changes</title>
6016
6017 <para>
6018 The following changes have occurred:
6019 <itemizedlist>
6020 <listitem><para>
6021 <emphasis>The <filename>virtclass-native</filename> and
6022 <filename>virtclass-nativesdk</filename> Overrides Have
6023 Been Removed:</emphasis>
6024 The <filename>virtclass-native</filename> and
6025 <filename>virtclass-nativesdk</filename> overrides have
6026 been deprecated since 2012 in favor of
6027 <filename>class-native</filename> and
6028 <filename>class-nativesdk</filename>, respectively.
6029 Both <filename>virtclass-native</filename> and
6030 <filename>virtclass-nativesdk</filename> are now dropped.
6031 <note>
6032 The <filename>virtclass-multilib-</filename> overrides
6033 for multilib are still valid.
6034 </note>
6035 </para></listitem>
6036 <listitem><para>
6037 <emphasis>The <filename>forcevariable</filename>
6038 Override Now Has a Higher Priority Than
6039 <filename>libc</filename> Overrides:</emphasis>
6040 The <filename>forcevariable</filename> override is
6041 documented to be the highest priority override.
6042 However, due to a long-standing quirk of how
6043 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
6044 is set, the <filename>libc</filename> overrides (e.g.
6045 <filename>libc-glibc</filename>,
6046 <filename>libc-musl</filename>, and so forth) erroneously
6047 had a higher priority.
6048 This issue is now corrected.</para>
6049
6050 <para>It is likely this change will not cause any
6051 problems.
6052 However, it is possible with some unusual configurations
6053 that you might see a change in behavior if you were
6054 relying on the previous behavior.
6055 Be sure to check how you use
6056 <filename>forcevariable</filename> and
6057 <filename>libc-*</filename> overrides in your custom
6058 layers and configuration files to ensure they make sense.
6059 </para></listitem>
6060 <listitem><para>
6061 <emphasis>The <filename>build-${BUILD_OS}</filename>
6062 Override Has Been Removed:</emphasis>
6063 The <filename>build-${BUILD_OS}</filename>, which is
6064 typically <filename>build-linux</filename>, override has
6065 been removed because building on a host operating system
6066 other than a recent version of Linux is neither supported
6067 nor recommended.
6068 Dropping the override avoids giving the impression that
6069 other host operating systems might be supported.
6070 </para></listitem>
6071 <listitem><para>
6072 The "_remove" operator now preserves whitespace.
6073 Consequently, when specifying list items to remove, be
6074 aware that leading and trailing whitespace resulting from
6075 the removal is retained.</para>
6076
6077 <para>See the
6078 "<ulink url='&YOCTO_DOCS_BB_URL;#removing-override-style-syntax'>Removal (Override Style Syntax)</ulink>"
6079 section in the BitBake User Manual for a detailed example.
6080 </para></listitem>
6081 </itemizedlist>
6082 </para>
6083 </section>
6084
6085 <section id='migration-2.6-systemd-configuration-now-split-out-to-system-conf'>
6086 <title><filename>systemd</filename> Configuration is Now Split Into <filename>systemd-conf</filename></title>
6087
6088 <para>
6089 The configuration for the <filename>systemd</filename> recipe
6090 has been moved into a <filename>system-conf</filename> recipe.
6091 Moving this configuration to a separate recipe avoids the
6092 <filename>systemd</filename> recipe from becoming machine-specific
6093 for cases where machine-specific configurations need to be applied
6094 (e.g. for <filename>qemu*</filename> machines).
6095 </para>
6096
6097 <para>
6098 Currently, the new recipe packages the following files:
6099 <literallayout class='monospaced'>
6100 ${sysconfdir}/machine-id
6101 ${sysconfdir}/systemd/coredump.conf
6102 ${sysconfdir}/systemd/journald.conf
6103 ${sysconfdir}/systemd/logind.conf
6104 ${sysconfdir}/systemd/system.conf
6105 ${sysconfdir}/systemd/user.conf
6106 </literallayout>
6107 If you previously used bbappend files to append the
6108 <filename>systemd</filename> recipe to change any of the
6109 listed files, you must do so for the
6110 <filename>systemd-conf</filename> recipe instead.
6111 </para>
6112 </section>
6113
6114 <section id='migration-2.6-automatic-testing-changes'>
6115 <title>Automatic Testing Changes</title>
6116
6117 <para>
6118 This section provides information about automatic testing
6119 changes:
6120 <itemizedlist>
6121 <listitem><para>
6122 <emphasis><filename>TEST_IMAGE</filename> Variable Removed:</emphasis>
6123 Prior to this release, you set the
6124 <filename>TEST_IMAGE</filename> variable to "1" to
6125 enable automatic testing for successfully built images.
6126 The <filename>TEST_IMAGE</filename> variable no longer
6127 exists and has been replaced by the
6128 <link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
6129 variable.
6130 </para></listitem>
6131 <listitem><para>
6132 <emphasis>Inheriting the <filename>testimage</filename> and
6133 <filename>testsdk</filename> Classes:</emphasis>
6134 Best practices now dictate that you use the
6135 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
6136 variable rather than the
6137 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
6138 variable when you inherit the
6139 <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
6140 and
6141 <link linkend='ref-classes-testsdk'><filename>testsdk</filename></link>
6142 classes used for automatic testing.
6143 </para></listitem>
6144 </itemizedlist>
6145 </para>
6146 </section>
6147
6148 <section id='migration-2.6-openssl-changes'>
6149 <title>OpenSSL Changes</title>
6150
6151 <para>
6152 <ulink url='https://www.openssl.org/'>OpenSSL</ulink> has been
6153 upgraded from 1.0 to 1.1.
6154 By default, this upgrade could cause problems for recipes that
6155 have both versions in their dependency chains.
6156 The problem is that both versions cannot be installed together
6157 at build time.
6158 <note>
6159 It is possible to have both versions of the library at runtime.
6160 </note>
6161 </para>
6162 </section>
6163
6164 <section id='migration-2.6-bitbake-changes'>
6165 <title>BitBake Changes</title>
6166
6167 <para>
6168 The server logfile <filename>bitbake-cookerdaemon.log</filename> is
6169 now always placed in the
6170 <link linkend='build-directory'>Build Directory</link>
6171 instead of the current directory.
6172 </para>
6173 </section>
6174
6175 <section id='migration-2.6-security-changes'>
6176 <title>Security Changes</title>
6177
6178 <para>
6179 The Poky distribution now uses security compiler flags by
6180 default.
6181 Inclusion of these flags could cause new failures due to stricter
6182 checking for various potential security issues in code.
6183 </para>
6184 </section>
6185
6186 <section id='migration-2.6-post-installation-changes'>
6187 <title>Post Installation Changes</title>
6188
6189 <para>
6190 You must explicitly mark post installs to defer to the target.
6191 If you want to explicitly defer a postinstall to first boot on
6192 the target rather than at rootfs creation time, use
6193 <filename>pkg_postinst_ontarget()</filename> or call
6194 <filename>postinst_intercept delay_to_first_boot</filename> from
6195 <filename>pkg_postinst()</filename>.
6196 Any failure of a <filename>pkg_postinst()</filename> script
6197 (including exit 1) triggers an error during the
6198 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> task.
6199 </para>
6200
6201 <para>
6202 For more information on post-installation behavior, see the
6203 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
6204 section in the Yocto Project Development Tasks Manual.
6205 </para>
6206 </section>
6207
6208 <section id='migration-2.6-python-3-profile-guided-optimizations'>
6209 <title>Python 3 Profile-Guided Optimization</title>
6210
6211 <para>
6212 The <filename>python3</filename> recipe now enables profile-guided
6213 optimization.
6214 Using this optimization requires a little extra build time in
6215 exchange for improved performance on the target at runtime.
6216 Additionally, the optimization is only enabled if the current
6217 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
6218 has support for user-mode emulation in QEMU (i.e. "qemu-usermode"
6219 is in
6220 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>,
6221 which it is by default).
6222 </para>
6223
6224 <para>
6225 If you wish to disable Python profile-guided optimization
6226 regardless of the value of
6227 <filename>MACHINE_FEATURES</filename>, then ensure that
6228 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
6229 for the <filename>python3</filename> recipe does not contain "pgo".
6230 You could accomplish the latter using the following at the
6231 configuration level:
6232 <literallayout class='monospaced'>
6233 PACKAGECONFIG_remove_pn-python3 = "pgo"
6234 </literallayout>
6235 Alternatively, you can set
6236 <filename>PACKAGECONFIG</filename> using an append file for the
6237 <filename>python3</filename> recipe.
6238 </para>
6239 </section>
6240
6241 <section id='migration-2.6-miscellaneous-changes'>
6242 <title>Miscellaneous Changes</title>
6243
6244 <para>
6245 The following miscellaneous changes occurred:
6246 <itemizedlist>
6247 <listitem><para>
6248 Default to using the Thumb-2 instruction set for armv7a
6249 and above.
6250 If you have any custom recipes that build software that
6251 needs to be built with the ARM instruction set, change the
6252 recipe to set the instruction set as follows:
6253 <literallayout class='monospaced'>
6254 ARM_INSTRUCTION_SET = "arm"
6255 </literallayout>
6256 </para></listitem>
6257 <listitem><para>
6258 <filename>run-postinsts</filename> no longer uses
6259 <filename>/etc/*-postinsts</filename> for
6260 <filename>dpkg/opkg</filename> in favor of built-in
6261 postinst support.
6262 RPM behavior remains unchanged.
6263 </para></listitem>
6264 <listitem><para>
6265 The <filename>NOISO</filename> and
6266 <filename>NOHDD</filename> variables are no longer used.
6267 You now control building <filename>*.iso</filename> and
6268 <filename>*.hddimg</filename> image types directly
6269 by using the
6270 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6271 variable.
6272 </para></listitem>
6273 <listitem><para>
6274 The <filename>scripts/contrib/mkefidisk.sh</filename>
6275 has been removed in favor of Wic.
6276 </para></listitem>
6277 <listitem><para>
6278 <filename>kernel-modules</filename> has been removed from
6279 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
6280 for <filename>qemumips</filename> and
6281 <filename>qemumips64</filename> machines.
6282 Removal also impacts the <filename>x86-base.inc</filename>
6283 file.
6284 <note>
6285 <filename>genericx86</filename> and
6286 <filename>genericx86-64</filename> retain
6287 <filename>kernel-modules</filename> as part of the
6288 <filename>RRECOMMENDS</filename> variable setting.
6289 </note>
6290 </para></listitem>
6291 <listitem><para>
6292 The <filename>LGPLv2_WHITELIST_GPL-3.0</filename>
6293 variable has been removed.
6294 If you are setting this variable in your configuration,
6295 set or append it to the
6296 <filename>WHITELIST_GPL-3.0</filename> variable instead.
6297 </para></listitem>
6298 <listitem><para>
6299 <filename>${ASNEEDED}</filename> is now included in
6300 the
6301 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
6302 variable directly.
6303 The remaining definitions from
6304 <filename>meta/conf/distro/include/as-needed.inc</filename>
6305 have been moved to corresponding recipes.
6306 </para></listitem>
6307 <listitem><para>
6308 Support for DSA host keys has been dropped from the
6309 OpenSSH recipes.
6310 If you are still using DSA keys, you must switch over to a
6311 more secure algorithm as recommended by OpenSSH upstream.
6312 </para></listitem>
6313 <listitem><para>
6314 The <filename>dhcp</filename> recipe now uses the
6315 <filename>dhcpd6.conf</filename> configuration file in
6316 <filename>dhcpd6.service</filename> for IPv6 DHCP rather
6317 than re-using <filename>dhcpd.conf</filename>, which is
6318 now reserved for IPv4.
6319 </para></listitem>
6320 </itemizedlist>
6321 </para>
6322 </section>
6323</section>
6324
6325<section id='moving-to-the-yocto-project-2.7-release'>
6326 <title>Moving to the Yocto Project 2.7 Release</title>
6327
6328 <para>
6329 This section provides migration information for moving to the
6330 Yocto Project 2.7 Release from the prior release.
6331 </para>
6332
6333 <section id='migration-2.7-bitbake-changes'>
6334 <title>BitBake Changes</title>
6335
6336 <para>
6337 The following changes have been made to BitBake:
6338 <itemizedlist>
6339 <listitem><para>
6340 BitBake now checks anonymous Python functions and pure
6341 Python functions (e.g. <filename>def funcname:</filename>)
6342 in the metadata for tab indentation.
6343 If found, BitBake produces a warning.
6344 </para></listitem>
6345 <listitem><para>
6346 Bitbake now checks
6347 <link linkend='var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></link>
6348 for duplicate entries and triggers an error if any are
6349 found.
6350 </para></listitem>
6351 </itemizedlist>
6352 </para>
6353 </section>
6354
6355 <section id='migration-2.7-eclipse-support-dropped'>
6356 <title><trademark class='trade'>Eclipse</trademark> Support Removed</title>
6357
6358 <para>
6359 Support for the Eclipse IDE has been removed.
6360 Support continues for those releases prior to 2.7 that did include
6361 support.
6362 The 2.7 release does not include the Eclipse Yocto plugin.
6363 </para>
6364 </section>
6365
6366 <section id='migration-2.7-qemu-native-splits-system-and-user-mode-parts'>
6367 <title><filename>qemu-native</filename> Splits the System and User-Mode Parts</title>
6368
6369 <para>
6370 The system and user-mode parts of <filename>qemu-native</filename>
6371 are now split.
6372 <filename>qemu-native</filename> provides the user-mode components
6373 and <filename>qemu-system-native</filename> provides the system
6374 components.
6375 If you have recipes that depend on QEMU's system emulation
6376 functionality at build time, they should now depend upon
6377 <filename>qemu-system-native</filename> instead of
6378 <filename>qemu-native</filename>.
6379 </para>
6380 </section>
6381
6382 <section id='migration-2.7-upstream-tracking.inc-removed'>
6383 <title>The <filename>upstream-tracking.inc</filename> File Has Been Removed</title>
6384
6385 <para>
6386 The previously deprecated <filename>upstream-tracking.inc</filename>
6387 file is now removed.
6388 Any <filename>UPSTREAM_TRACKING*</filename> variables are now set
6389 in the corresponding recipes instead.
6390 </para>
6391
6392 <para>
6393 Remove any references you have to the
6394 <filename>upstream-tracking.inc</filename> file in your
6395 configuration.
6396 </para>
6397 </section>
6398
6399 <section id='migration-2.7-distro-features-libc-removed'>
6400 <title>The <filename>DISTRO_FEATURES_LIBC</filename> Variable Has Been Removed</title>
6401
6402 <para>
6403 The <filename>DISTRO_FEATURES_LIBC</filename> variable is no
6404 longer used.
6405 The ability to configure glibc using kconfig has been removed
6406 for quite some time making the <filename>libc-*</filename> features
6407 set no longer effective.
6408 </para>
6409
6410 <para>
6411 Remove any references you have to
6412 <filename>DISTRO_FEATURES_LIBC</filename> in your own layers.
6413 </para>
6414 </section>
6415
6416 <section id='migration-2.7-license-values'>
6417 <title>License Value Corrections</title>
6418
6419 <para>
6420 The following corrections have been made to the
6421 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
6422 values set by recipes:
6423 <literallayout class='monospaced'>
6424 <emphasis>socat</emphasis>: Corrected <filename>LICENSE</filename> to be "GPLv2" rather than
6425 "GPLv2+".
6426
6427 <emphasis>libgfortran</emphasis>: Set license to "GPL-3.0-with-GCC-exception".
6428
6429 <emphasis>elfutils</emphasis>: Removed "Elfutils-Exception" and set to "GPLv2" for shared
6430 libraries
6431 </literallayout>
6432 </para>
6433 </section>
6434
6435 <section id='migration-2.7-packaging-changes'>
6436 <title>Packaging Changes</title>
6437
6438 <para>
6439 This section provides information about packaging changes.
6440 <itemizedlist>
6441 <listitem><para>
6442 <filename>bind</filename>: The
6443 <filename>nsupdate</filename> binary has been moved to
6444 the <filename>bind-utils</filename> package.
6445 </para></listitem>
6446 <listitem><para>
6447 Debug split: The default debug split has been changed to
6448 create separate source packages (i.e.
6449 <replaceable>package_name</replaceable><filename>-dbg</filename>
6450 and
6451 <replaceable>package_name</replaceable><filename>-src</filename>).
6452 If you are currently using <filename>dbg-pkgs</filename>
6453 in
6454 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
6455 to bring in debug symbols and you still need the sources,
6456 you must now also add <filename>src-pkgs</filename> to
6457 <filename>IMAGE_FEATURES</filename>.
6458 Source packages remain in the target portion of the SDK
6459 by default, unless you have set your own value for
6460 <link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>
6461 that does not include <filename>src-pkgs</filename>.
6462 </para></listitem>
6463 <listitem><para>
6464 Mount all using <filename>util-linux</filename>:
6465 <filename>/etc/default/mountall</filename> has
6466 moved into the -mount sub-package.
6467 </para></listitem>
6468 <listitem><para>
6469 Splitting binaries using <filename>util-linux</filename>:
6470 <filename>util-linux</filename> now splits each binary into
6471 its own package for fine-grained control.
6472 The main <filename>util-linux</filename> package pulls in
6473 the individual binary packages using the
6474 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
6475 and
6476 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
6477 variables.
6478 As a result, existing images should not see any changes
6479 assuming
6480 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
6481 is not set.
6482 </para></listitem>
6483 <listitem><para>
6484 <filename>netbase/base-files</filename>:
6485 <filename>/etc/hosts</filename> has moved from
6486 <filename>netbase</filename> to
6487 <filename>base-files</filename>.
6488 </para></listitem>
6489 <listitem><para>
6490 <filename>tzdata</filename>: The main package has been
6491 converted to an empty meta package that pulls in all
6492 <filename>tzdata</filename> packages by default.
6493 </para></listitem>
6494 <listitem><para>
6495 <filename>lrzsz</filename>: This package has been removed
6496 from <filename>packagegroup-self-hosted</filename> and
6497 <filename>packagegroup-core-tools-testapps</filename>.
6498 The X/Y/ZModem support is less likely to be needed on
6499 modern systems.
6500 If you are relying on these packagegroups to include the
6501 <filename>lrzsz</filename> package in your image, you
6502 now need to explicitly add the package.
6503 </para></listitem>
6504 </itemizedlist>
6505 </para>
6506 </section>
6507
6508 <section id='migration-2.7-removed-recipes'>
6509 <title>Removed Recipes</title>
6510
6511 <para>
6512 The following recipes have been removed:
6513 <literallayout class='monospaced'>
6514 <emphasis>gcc</emphasis>: Drop version 7.3 recipes. Version 8.3 now remains.
6515
6516 <emphasis>linux-yocto</emphasis>: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain.
6517
6518 <emphasis>go</emphasis>: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain.
6519
6520 <emphasis>xvideo-tests</emphasis>: Became obsolete.
6521
6522 <emphasis>libart-lgpl</emphasis>: Became obsolete.
6523
6524 <emphasis>gtk-icon-utils-native</emphasis>: These tools are now provided by gtk+3-native
6525
6526 <emphasis>gcc-cross-initial</emphasis>: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
6527
6528 <emphasis>gcc-crosssdk-initial</emphasis>: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
6529
6530 <emphasis>glibc-initial</emphasis>: Removed because the benefits of having it for site_config are
6531 currently outweighed by the cost of building the recipe.
6532 </literallayout>
6533 </para>
6534 </section>
6535
6536 <section id='migration-2.7-removed-classes'>
6537 <title>Removed Classes</title>
6538
6539 <para>
6540 The following classes have been removed:
6541 <literallayout class='monospaced'>
6542 <emphasis>distutils-tools</emphasis>: This class was never used.
6543
6544 <emphasis>bugzilla.bbclass</emphasis>: Became obsolete.
6545
6546 <emphasis>distrodata</emphasis>: This functionally has been replaced by a more modern
6547 tinfoil-based implementation.
6548 </literallayout>
6549 </para>
6550 </section>
6551
6552 <section id='migration-2.7-miscellaneous-changes'>
6553 <title>Miscellaneous Changes</title>
6554
6555 <para>
6556 The following miscellaneous changes occurred:
6557 <itemizedlist>
6558 <listitem><para>
6559 The <filename>distro</filename> subdirectory of the Poky
6560 repository has been removed from the top-level
6561 <filename>scripts</filename> directory.
6562 </para></listitem>
6563 <listitem><para>
6564 Perl now builds for the target using
6565 <ulink url='http://arsv.github.io/perl-cross/'><filename>perl-cross</filename></ulink>
6566 for better maintainability and improved build performance.
6567 This change should not present any problems unless you have
6568 heavily customized your Perl recipe.
6569 </para></listitem>
6570 <listitem><para>
6571 <filename>arm-tunes</filename>: Removed the "-march"
6572 option if mcpu is already added.
6573 </para></listitem>
6574 <listitem><para>
6575 <filename>update-alternatives</filename>: Convert file
6576 renames to
6577 <link linkend='var-PACKAGE_PREPROCESS_FUNCS'><filename>PACKAGE_PREPROCESS_FUNCS</filename></link>
6578 </para></listitem>
6579 <listitem><para>
6580 <filename>base/pixbufcache</filename>: Obsolete
6581 <filename>sstatecompletions</filename> code has been
6582 removed.
6583 </para></listitem>
6584 <listitem><para>
6585 <link linkend='ref-classes-native'><filename>native</filename></link>
6586 class:
6587 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
6588 handling has been enabled.
6589 </para></listitem>
6590 <listitem><para>
6591 <filename>inetutils</filename>: This recipe has rsh
6592 disabled.
6593 </para></listitem>
6594 </itemizedlist>
6595 </para>
6596 </section>
6597</section>
6598
6599<section id='moving-to-the-yocto-project-3.0-release'>
6600 <title>Moving to the Yocto Project 3.0 Release</title>
6601
6602 <para>
6603 This section provides migration information for moving to the
6604 Yocto Project 3.0 Release from the prior release.
6605 </para>
6606
6607 <section id='migration-3.0-init-system-selection'>
6608 <title>Init System Selection</title>
6609
6610 <para>
6611 Changing the init system manager previously required setting a
6612 number of different variables.
6613 You can now change the manager by setting the
6614 <filename>INIT_MANAGER</filename> variable and the corresponding
6615 include files
6616 (i.e. <filename>conf/distro/include/init-manager-*.conf</filename>).
6617 Include files are provided for four values: "none", "sysvinit",
6618 "systemd", and "mdev-busybox".
6619 The default value, "none", for <filename>INIT_MANAGER</filename>
6620 should allow your current settings to continue working.
6621 However, it is advisable to explicitly set
6622 <filename>INIT_MANAGER</filename>.
6623 </para>
6624 </section>
6625
6626 <section id='migration-3.0-lsb-support-removed'>
6627 <title>LSB Support Removed</title>
6628
6629 <para>
6630 Linux Standard Base (LSB) as a standard is not current, and
6631 is not well suited for embedded applications.
6632 Support can be continued in a separate layer if needed.
6633 However, presently LSB support has been removed from the core.
6634 </para>
6635
6636 <para>
6637 As a result of this change, the <filename>poky-lsb</filename>
6638 derivative distribution configuration that was also used for
6639 testing alternative configurations has been replaced with a
6640 <filename>poky-altcfg</filename> distribution that has LSB
6641 parts removed.
6642 </para>
6643 </section>
6644
6645 <section id='migration-3.0-removed-recipes'>
6646 <title>Removed Recipes</title>
6647
6648 <para>
6649 The following recipes have been removed.
6650 <itemizedlist>
6651 <listitem><para>
6652 <filename>core-image-lsb-dev</filename>: Part of removed
6653 LSB support.
6654 </para></listitem>
6655 <listitem><para>
6656 <filename>core-image-lsb</filename>: Part of removed
6657 LSB support.
6658 </para></listitem>
6659 <listitem><para>
6660 <filename>core-image-lsb-sdk</filename>: Part of removed
6661 LSB support.
6662 </para></listitem>
6663 <listitem><para>
6664 <filename>cve-check-tool</filename>: Functionally replaced
6665 by the <filename>cve-update-db</filename> recipe and
6666 <filename>cve-check</filename> class.
6667 </para></listitem>
6668 <listitem><para>
6669 <filename>eglinfo</filename>: No longer maintained.
6670 <filename>eglinfo</filename> from
6671 <filename>mesa-demos</filename> is an adequate and
6672 maintained alternative.
6673 </para></listitem>
6674 <listitem><para>
6675 <filename>gcc-8.3</filename>: Version 8.3 removed.
6676 Replaced by 9.2.
6677 </para></listitem>
6678 <listitem><para>
6679 <filename>gnome-themes-standard</filename>: Only needed
6680 by gtk+ 2.x, which has been removed.
6681 </para></listitem>
6682 <listitem><para>
6683 <filename>gtk+</filename>: GTK+ 2 is obsolete and has been
6684 replaced by gtk+3.
6685 </para></listitem>
6686 <listitem><para>
6687 <filename>irda-utils</filename>: Has become obsolete.
6688 IrDA support has been removed from the Linux kernel in
6689 version 4.17 and later.
6690 </para></listitem>
6691 <listitem><para>
6692 <filename>libnewt-python</filename>:
6693 <filename>libnewt</filename> Python support merged into
6694 main <filename>libnewt</filename> recipe.
6695 </para></listitem>
6696 <listitem><para>
6697 <filename>libsdl</filename>: Replaced by newer
6698 <filename>libsdl2</filename>.
6699 </para></listitem>
6700 <listitem><para>
6701 <filename>libx11-diet</filename>: Became obsolete.
6702 </para></listitem>
6703 <listitem><para>
6704 <filename>libxx86dga</filename>: Removed obsolete client
6705 library.
6706 </para></listitem>
6707 <listitem><para>
6708 <filename>libxx86misc</filename>: Removed. Library is
6709 redundant.
6710 </para></listitem>
6711 <listitem><para>
6712 <filename>linux-yocto</filename>: Version 5.0 removed,
6713 which is now redundant (5.2 / 4.19 present).
6714 </para></listitem>
6715 <listitem><para>
6716 <filename>lsbinitscripts</filename>: Part of removed LSB
6717 support.
6718 </para></listitem>
6719 <listitem><para>
6720 <filename>lsb</filename>: Part of removed LSB support.
6721 </para></listitem>
6722 <listitem><para>
6723 <filename>lsbtest</filename>: Part of removed LSB support.
6724 </para></listitem>
6725 <listitem><para>
6726 <filename>openssl10</filename>: Replaced by newer
6727 <filename>openssl</filename> version 1.1.
6728 </para></listitem>
6729 <listitem><para>
6730 <filename>packagegroup-core-lsb</filename>: Part of removed
6731 LSB support.
6732 </para></listitem>
6733 <listitem><para>
6734 <filename>python-nose</filename>: Removed the Python 2.x
6735 version of the recipe.
6736 </para></listitem>
6737 <listitem><para>
6738 <filename>python-numpy</filename>: Removed the Python 2.x
6739 version of the recipe.
6740 </para></listitem>
6741 <listitem><para>
6742 <filename>python-scons</filename>: Removed the Python 2.x
6743 version of the recipe.
6744 </para></listitem>
6745 <listitem><para>
6746 <filename>source-highlight</filename>: No longer needed.
6747 </para></listitem>
6748 <listitem><para>
6749 <filename>stress</filename>: Replaced by
6750 <filename>stress-ng</filename>.
6751 </para></listitem>
6752 <listitem><para>
6753 <filename>vulkan</filename>: Split into
6754 <filename>vulkan-loader</filename>,
6755 <filename>vulkan-headers</filename>, and
6756 <filename>vulkan-tools</filename>.
6757 </para></listitem>
6758 <listitem><para>
6759 <filename>weston-conf</filename>: Functionality moved to
6760 <filename>weston-init</filename>.
6761 </para></listitem>
6762 </itemizedlist>
6763 </para>
6764 </section>
6765
6766 <section id='migration-3.0-packaging-changes'>
6767 <title>Packaging Changes</title>
6768
6769 <para>
6770 The following packaging changes have occurred.
6771 <itemizedlist>
6772 <listitem><para>
6773 The
6774 <ulink url='https://en.wikipedia.org/wiki/GNOME_Web'>Epiphany</ulink>
6775 browser has been dropped from
6776 <filename>packagegroup-self-hosted</filename> as it has
6777 not been needed inside
6778 <filename>build-appliance-image</filename> for
6779 quite some time and was causing resource problems.
6780 </para></listitem>
6781 <listitem><para>
6782 <filename>libcap-ng</filename> Python support has been
6783 moved to a separate <filename>libcap-ng-python</filename>
6784 recipe to streamline the build process when the Python
6785 bindings are not needed.
6786 </para></listitem>
6787 <listitem><para>
6788 <filename>libdrm</filename> now packages the file
6789 <filename>amdgpu.ids</filename> into a separate
6790 <filename>libdrm-amdgpu</filename> package.
6791 </para></listitem>
6792 <listitem><para>
6793 <filename>python3</filename>: The
6794 <filename>runpy</filename> module is now in the
6795 <filename>python3-core</filename> package as it is
6796 required to support the common "python3 -m" command usage.
6797 </para></listitem>
6798 <listitem><para>
6799 <filename>distcc</filename> now provides separate
6800 <filename>distcc-client</filename> and
6801 <filename>distcc-server</filename> packages as typically
6802 one or the other are needed, rather than both.
6803 </para></listitem>
6804 <listitem><para>
6805 <filename>python*-setuptools</filename> recipes now
6806 separately package the <filename>pkg_resources</filename>
6807 module in a <filename>python-pkg-resources</filename> /
6808 <filename>python3-pkg-resources</filename> package as
6809 the module is useful independent of the rest of the
6810 setuptools package.
6811 The main <filename>python-setuptools</filename> /
6812 <filename>python3-setuptools</filename> package depends
6813 on this new package so you should only need to update
6814 dependencies unless you want to take advantage of the
6815 increased granularity.
6816 </para></listitem>
6817 </itemizedlist>
6818 </para>
6819 </section>
6820
6821 <section id='migration-3.0-cve-checking'>
6822 <title>CVE Checking</title>
6823
6824 <para>
6825 <filename>cve-check-tool</filename> has been functionally replaced
6826 by a new <filename>cve-update-db</filename> recipe and
6827 functionality built into the <filename>cve-check</filename> class.
6828 The result uses NVD JSON data feeds rather than the deprecated
6829 XML feeds that <filename>cve-check-tool</filename> was using,
6830 supports CVSSv3 scoring, and makes other improvements.
6831 </para>
6832
6833 <para>
6834 Additionally, the <filename>CVE_CHECK_CVE_WHITELIST</filename>
6835 variable has been replaced by
6836 <filename>CVE_CHECK_WHITELIST</filename>.
6837 </para>
6838 </section>
6839
6840 <section id='migration-3.0-bitbake-changes'>
6841 <title>Bitbake Changes</title>
6842
6843 <para>
6844 The following BitBake changes have occurred.
6845 <itemizedlist>
6846 <listitem><para>
6847 <filename>addtask</filename> statements now properly
6848 validate dependent tasks.
6849 Previously, an invalid task was silently ignored.
6850 With this change, the invalid task generates a warning.
6851 </para></listitem>
6852 <listitem><para>
6853 Other invalid <filename>addtask</filename> and
6854 <filename>deltask</filename> usages now trigger these
6855 warnings: "multiple target tasks arguments with
6856 addtask / deltask", and "multiple before/after clauses".
6857 </para></listitem>
6858 <listitem><para>
6859 The "multiconfig" prefix is now shortened to "mc".
6860 "multiconfig" will continue to work, however it may be
6861 removed in a future release.
6862 </para></listitem>
6863 <listitem><para>
6864 The <filename>bitbake -g</filename> command no longer
6865 generates a <filename>recipe-depends.dot</filename> file
6866 as the contents (i.e. a reprocessed version of
6867 <filename>task-depends.dot</filename>) were confusing.
6868 </para></listitem>
6869 <listitem><para>
6870 The <filename>bb.build.FuncFailed</filename> exception,
6871 previously raised by
6872 <filename>bb.build.exec_func()</filename> when certain
6873 other exceptions have occurred, has been removed.
6874 The real underlying exceptions will be raised instead.
6875 If you have calls to
6876 <filename>bb.build.exec_func()</filename> in custom classes
6877 or <filename>tinfoil-using</filename> scripts, any
6878 references to <filename>bb.build.FuncFailed</filename>
6879 should be cleaned up.
6880 </para></listitem>
6881 <listitem><para>
6882 Additionally, the
6883 <filename>bb.build.exec_func()</filename> no longer accepts
6884 the "pythonexception" parameter.
6885 The function now always raises exceptions.
6886 Remove this argument in any calls to
6887 <filename>bb.build.exec_func()</filename> in custom classes
6888 or scripts.
6889 </para></listitem>
6890 <listitem><para>
6891 The
6892 <ulink url='&YOCTO_DOCS_BB_URL;#var-bb-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink>
6893 is no longer used.
6894 In the unlikely event that you have any references to it,
6895 they should be removed.
6896 </para></listitem>
6897 <listitem><para>
6898 The <filename>RunQueueExecuteScenequeue</filename> and
6899 <filename>RunQueueExecuteTasks</filename> events have been
6900 removed since setscene tasks are now executed as part of
6901 the normal runqueue.
6902 Any event handling code in custom classes or scripts that
6903 handles these two events need to be updated.
6904 </para></listitem>
6905 <listitem><para>
6906 The arguments passed to functions used with
6907 <ulink url='&YOCTO_DOCS_BB_URL;#var-bb-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink>
6908 have changed.
6909 If you are using your own custom hash check function, see
6910 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=40a5e193c4ba45c928fccd899415ea56b5417725'></ulink>
6911 for details.
6912 </para></listitem>
6913 <listitem><para>
6914 Task specifications in <filename>BB_TASKDEPDATA</filename>
6915 and class implementations used in signature generator
6916 classes now use "&lt;fn&gt;:&lt;task&gt;" everywhere rather than
6917 the "." delimiter that was being used in some places.
6918 This change makes it consistent with all areas in the code.
6919 Custom signature generator classes and code that reads
6920 <filename>BB_TASKDEPDATA</filename> need to be updated to
6921 use ':' as a separator rather than '.'.
6922 </para></listitem>
6923 </itemizedlist>
6924 </para>
6925 </section>
6926
6927 <section id='migration-3.0-sanity-checks'>
6928 <title>Sanity Checks</title>
6929
6930 <para>
6931 The following sanity check changes occurred.
6932 <itemizedlist>
6933 <listitem><para>
6934 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
6935 is now checked for usage of two problematic items:
6936 <itemizedlist>
6937 <listitem><para>
6938 "${PN}" prefix/suffix use - Warnings always appear
6939 if ${PN} is used.
6940 You must fix the issue regardless of whether
6941 multiconfig or anything else that would cause
6942 prefixing/suffixing to happen.
6943 </para></listitem>
6944 <listitem><para>
6945 Github archive tarballs - these are not guaranteed
6946 to be stable.
6947 Consequently, it is likely that the tarballs will
6948 be refreshed and thus the SRC_URI checksums
6949 will fail to apply.
6950 It is recommended that you fetch either an official
6951 release tarball or a specific revision from the
6952 actual Git repository instead.
6953 </para></listitem>
6954 </itemizedlist>
6955 Either one of these items now trigger a warning by default.
6956 If you wish to disable this check, remove
6957 <filename>src-uri-bad</filename> from
6958 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>.
6959 </para></listitem>
6960 <listitem><para>
6961 The <filename>file-rdeps</filename> runtime dependency
6962 check no longer expands
6963 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
6964 recursively as there is no mechanism to ensure they can be
6965 fully computed, and thus races sometimes result in errors
6966 either showing up or not.
6967 Thus, you might now see errors for missing runtime
6968 dependencies that were previously satisfied recursively.
6969 Here is an example: package A contains a shell script
6970 starting with <filename>#!/bin/bash</filename> but has no
6971 dependency on bash.
6972 However, package A depends on package B, which does depend
6973 on bash.
6974 You need to add the missing dependency or dependencies to
6975 resolve the warning.
6976 </para></listitem>
6977 <listitem><para>
6978 Setting <filename>DEPENDS_${PN}</filename> anywhere
6979 (i.e. typically in a recipe) now triggers an error.
6980 The error is triggered because
6981 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
6982 is not a package-specific variable unlike RDEPENDS.
6983 You should set <filename>DEPENDS</filename> instead.
6984 </para></listitem>
6985 <listitem><para>
6986 systemd currently does not work well with the musl C
6987 library because only upstream officially supports linking
6988 the library with glibc.
6989 Thus, a warning is shown when building systemd in
6990 conjunction with musl.
6991 </para></listitem>
6992 </itemizedlist>
6993 </para>
6994 </section>
6995
6996 <section id='migration-3.0-miscellaneous-changes'>
6997 <title>Miscellaneous Changes</title>
6998
6999 <para>
7000 The following miscellaneous changes have occurred.
7001 <itemizedlist>
7002 <listitem><para>
7003 The <filename>gnome</filename>
7004 class has been removed because it now does very little.
7005 You should update recipes that previously inherited this
7006 class to do the following:
7007 <literallayout class='monospaced'>
7008 inherit gnomebase gtk-icon-cache gconf mime
7009 </literallayout>
7010 </para></listitem>
7011 <listitem><para>
7012 The
7013 <filename>meta/recipes-kernel/linux/linux-dtb.inc</filename>
7014 file has been removed.
7015 This file was previously deprecated in favor of setting
7016 <link linkend='var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></link>
7017 in any kernel recipe and only produced a warning.
7018 Remove any <filename>include</filename> or
7019 <filename>require</filename> statements pointing to this
7020 file.
7021 </para></listitem>
7022 <listitem><para>
7023 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>,
7024 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>,
7025 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>,
7026 and
7027 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
7028 are no longer exported to the external environment.
7029 This change did not require any changes to core recipes,
7030 which is a good indicator that no changes will be
7031 required.
7032 However, if for some reason the software being built by one
7033 of your recipes is expecting these variables to be set,
7034 then building the recipe will fail.
7035 In such cases, you must either export the variable or
7036 variables in the recipe or change the scripts so that
7037 exporting is not necessary.
7038 </para></listitem>
7039 <listitem><para>
7040 You must change the host distro identifier used in
7041 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
7042 to use all lowercase characters even if it does not contain
7043 a version number.
7044 This change is necessary only if you are not using
7045 <filename>uninative</filename> and
7046 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>.
7047 </para></listitem>
7048 <listitem><para>
7049 In the <filename>base-files</filename> recipe, writing the
7050 hostname into <filename>/etc/hosts</filename> and
7051 <filename>/etc/hostname</filename> is now done within the
7052 main
7053 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
7054 function rather than in the
7055 <filename>do_install_basefilesissue</filename> function.
7056 The reason for the change is because
7057 <filename>do_install_basefilesissue</filename> is more
7058 easily overridden without having to duplicate the hostname
7059 functionality.
7060 If you have done the latter (e.g. in a
7061 <filename>base-files</filename> bbappend), then you should
7062 remove it from your customized
7063 <filename>do_install_basefilesissue</filename> function.
7064 </para></listitem>
7065 <listitem><para>
7066 The <filename>wic --expand</filename> command now uses
7067 commas to separate "key:value" pairs rather than hyphens.
7068 <note>
7069 The wic command-line help is not updated.
7070 </note>
7071 You must update any scripts or commands where you use
7072 <filename>wic --expand</filename> with multiple
7073 "key:value" pairs.
7074 </para></listitem>
7075 <listitem><para>
7076 UEFI image variable settings have been moved from various
7077 places to a central
7078 <filename>conf/image-uefi.conf</filename>.
7079 This change should not influence any existing configuration
7080 as the <filename>meta/conf/image-uefi.conf</filename>
7081 in the core metadata sets defaults that can be overridden
7082 in the same manner as before.
7083 </para></listitem>
7084 <listitem><para>
7085 <filename>conf/distro/include/world-broken.inc</filename>
7086 has been removed.
7087 For cases where certain recipes need to be disabled when
7088 using the musl C library, these recipes now have
7089 <filename>COMPATIBLE_HOST_libc-musl</filename> set with a
7090 comment that explains why.
7091 </para></listitem>
7092 </itemizedlist>
7093 </para>
7094 </section>
7095</section>
7096
7097
7098<section id='moving-to-the-yocto-project-3.1-release'>
7099 <title>Moving to the Yocto Project 3.1 Release</title>
7100
7101 <para>
7102 This section provides migration information for moving to the
7103 Yocto Project 3.1 Release from the prior release.
7104 </para>
7105
7106 <section id='migration-3.1-minimum-system-requirements'>
7107 <title>Minimum system requirements</title>
7108
7109 <para>
7110 The following versions / requirements of build host components have been updated:
7111 <itemizedlist>
7112 <listitem><para>gcc 5.0</para></listitem>
7113 <listitem><para>python 3.5</para></listitem>
7114 <listitem><para>tar 1.28</para></listitem>
7115 <listitem><para><filename>rpcgen</filename> is now required on the host (part of the <filename>libc-dev-bin</filename> package on Ubuntu, Debian and related distributions, and the <filename>glibc</filename> package on RPM-based distributions).</para></listitem>
7116 </itemizedlist>
7117
7118 Additionally, the <filename>makeinfo</filename> and <filename>pod2man</filename>
7119 tools are <emphasis>no longer</emphasis> required on the host.
7120 </para>
7121 </section>
7122
7123 <section id='migration-3.1-mpc8315e-rdb-removed'>
7124 <title>mpc8315e-rdb machine removed</title>
7125
7126 <para>
7127 The MPC8315E-RDB machine is old/obsolete and unobtainable, thus given the maintenance burden
7128 the <filename>mpc8315e-rdb</filename> machine configuration that supported it has been removed
7129 in this release. The removal does leave a gap in official PowerPC reference hardware
7130 support; this may change in future if a suitable machine with accompanying support resources
7131 is found.
7132 </para>
7133 </section>
7134
7135 <section id='migration-3.1-python-2-removed'>
7136 <title>Python 2 removed</title>
7137
7138 <para>
7139 Due to the expiration of upstream support in January 2020, support for Python 2 has now been removed; it is recommended that you use Python 3 instead. If absolutely needed there is a meta-python2 community layer containing Python 2, related classes and various Python 2-based modules, however it should not be considered as supported.
7140 </para>
7141 </section>
7142
7143 <section id='migration-3.1-reproducible-builds'>
7144 <title>Reproducible builds now enabled by default</title>
7145
7146 <para>
7147 In order to avoid unnecessary differences in output files (aiding binary reproducibility), the Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) now inherits the <filename>reproducible_build</filename> class by default.
7148 </para>
7149 </section>
7150
7151 <section id='migration-3.1-ptest-feature-impact'>
7152 <title>Impact of ptest feature is now more significant</title>
7153
7154 <para>
7155 The Poky distribution configuration (<filename><link linkend='var-DISTRO'>DISTRO</link> = "poky"</filename>) enables ptests by default to enable runtime testing of various components. In this release, a dependency needed to be added that has resulted in a significant increase in the number of components that will be built just when building a simple image such as core-image-minimal. If you do not need runtime tests enabled for core components, then it is recommended that you remove "ptest" from <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> to save a significant amount of build time e.g. by adding the following in your configuration:
7156
7157 <literallayout class='monospaced'>
7158 DISTRO_FEATURES_remove = "ptest"
7159 </literallayout>
7160 </para>
7161 </section>
7162
7163 <section id='migration-3.1-removed-recipes'>
7164 <title>Removed recipes</title>
7165
7166 <para>
7167 The following recipes have been removed:
7168
7169 <itemizedlist>
7170 <listitem><para><filename>chkconfig</filename>: obsolete</para></listitem>
7171 <listitem><para><filename>console-tools</filename>: obsolete</para></listitem>
7172 <listitem><para><filename>enchant</filename>: replaced by <filename>enchant2</filename></para></listitem>
7173 <listitem><para><filename>foomatic-filters</filename>: obsolete</para></listitem>
7174 <listitem><para><filename>libidn</filename>: no longer needed, moved to meta-oe</para></listitem>
7175 <listitem><para><filename>libmodulemd</filename>: replaced by <filename>libmodulemd-v1</filename></para></listitem>
7176 <listitem><para><filename>linux-yocto</filename>: drop 4.19, 5.2 version recipes (5.4 now provided)</para></listitem>
7177 <listitem><para><filename>nspr</filename>: no longer needed, moved to meta-oe</para></listitem>
7178 <listitem><para><filename>nss</filename>: no longer needed, moved to meta-oe</para></listitem>
7179 <listitem><para><filename>python</filename>: Python 2 removed (Python 3 preferred)</para></listitem>
7180 <listitem><para><filename>python-setuptools</filename>: Python 2 version removed (python3-setuptools preferred)</para></listitem>
7181 <listitem><para><filename>sysprof</filename>: no longer needed, moved to meta-oe</para></listitem>
7182 <listitem><para><filename>texi2html</filename>: obsolete</para></listitem>
7183 <listitem><para><filename>u-boot-fw-utils</filename>: functionally replaced by <filename>libubootenv</filename></para></listitem>
7184 </itemizedlist>
7185 </para>
7186 </section>
7187
7188 <section id='migration-3.1-features-check'>
7189 <title>features_check class replaces distro_features_check</title>
7190
7191 <para>
7192 The <filename>distro_features_check</filename> class has had its functionality expanded, now supporting <filename>ANY_OF_MACHINE_FEATURES</filename>, <filename>REQUIRED_MACHINE_FEATURES</filename>, <filename>CONFLICT_MACHINE_FEATURES</filename>, <filename>ANY_OF_COMBINED_FEATURES</filename>, <filename>REQUIRED_COMBINED_FEATURES</filename>, <filename>CONFLICT_COMBINED_FEATURES</filename>. As a result the class has now been renamed to <filename>features_check</filename>; the <filename>distro_features_check</filename> class still exists but generates a warning and redirects to the new class. In preparation for a future removal of the old class it is recommended that you update recipes currently inheriting <filename>distro_features_check</filename> to inherit <filename>features_check</filename> instead.
7193 </para>
7194 </section>
7195
7196 <section id='migration-3.1-removed-classes'>
7197 <title>Removed classes</title>
7198
7199 <para>
7200 The following classes have been removed:
7201
7202 <itemizedlist>
7203 <listitem><para><filename>distutils-base</filename>: moved to meta-python2</para></listitem>
7204 <listitem><para><filename>distutils</filename>: moved to meta-python2</para></listitem>
7205 <listitem><para><filename>libc-common</filename>: merged into the glibc recipe as nothing else used it.</para></listitem>
7206 <listitem><para><filename>python-dir</filename>: moved to meta-python2</para></listitem>
7207 <listitem><para><filename>pythonnative</filename>: moved to meta-python2</para></listitem>
7208 <listitem><para><filename>setuptools</filename>: moved to meta-python2</para></listitem>
7209 <listitem><para><filename>tinderclient</filename>: dropped as it was obsolete.</para></listitem>
7210 </itemizedlist>
7211 </para>
7212 </section>
7213
7214 <section id='migration-3.1-src-uri-checksums'>
7215 <title>SRC_URI checksum behaviour</title>
7216
7217 <para>
7218 Previously, recipes by tradition included both SHA256 and MD5 checksums for remotely fetched files in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>, even though only one is actually mandated. However, the MD5 checksum does not add much given its inherent weakness; thus when a checksum fails only the SHA256 sum will now be printed. The md5sum will still be verified if it is specified.
7219 </para>
7220 </section>
7221
7222
7223 <section id='migration-3.1-npm'>
7224 <title>npm fetcher changes</title>
7225
7226 <para>
7227 The npm fetcher has been completely reworked in this release. The npm fetcher now only fetches the package source itself and no longer the dependencies; there is now also an npmsw fetcher which explicitly fetches the shrinkwrap file and the dependencies. This removes the slightly awkward <filename>NPM_LOCKDOWN</filename> and <filename>NPM_SHRINKWRAP</filename> variables which pointed to local files; the lockdown file is no longer needed at all. Additionally, the package name in <filename>npm://</filename> entries in <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> is now specified using a <filename>package</filename> parameter instead of the earlier <filename>name</filename> which overlapped with the generic <filename>name</filename> parameter. All recipes using the npm fetcher will need to be changed as a result.
7228 </para>
7229 <para>
7230 An example of the new scheme:
7231 <literallayout class='monospaced'>
7232SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
7233 npmsw://${THISDIR}/npm-shrinkwrap.json"
7234 </literallayout>
7235 Another example where the sources are fetched from git rather than an npm repository:
7236 <literallayout class='monospaced'>
7237SRC_URI = "git://github.com/foo/bar.git;protocol=https \
7238 npmsw://${THISDIR}/npm-shrinkwrap.json"
7239 </literallayout>
7240 </para>
7241 <para>
7242 devtool and recipetool have also been updated to match with the npm fetcher changes. Other than producing working and more complete recipes for npm sources, there is also a minor change to the command line for devtool: the <filename>--fetch-dev</filename> option has been renamed to <filename>--npm-dev</filename> as it is npm-specific.
7243 </para>
7244 </section>
7245
7246
7247 <section id='migration-3.1-packaging-changes'>
7248 <title>Packaging changes</title>
7249
7250 <para>
7251 <itemizedlist>
7252 <listitem><para><filename>intltool</filename> has been removed from <filename>packagegroup-core-sdk</filename> as it is rarely needed to build modern software - gettext can do most of the things it used to be needed for. <filename>intltool</filename> has also been removed from <filename>packagegroup-core-self-hosted</filename> as it is not needed to for standard builds.</para></listitem>
7253 <listitem><para>git: <filename>git-am</filename>, <filename>git-difftool</filename>, <filename>git-submodule</filename>, and <filename>git-request-pull</filename> are no longer perl-based, so are now installed with the main <filename>git</filename> package instead of within <filename>git-perltools</filename>.</para></listitem>
7254 <listitem><para>The <filename>ldconfig</filename> binary built as part of glibc has now been moved to its own <filename>ldconfig</filename> package (note no <filename>glibc-</filename> prefix). This package is in the <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link> of the main <filename>glibc</filename> package if <filename>ldconfig</filename> is present in <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.</para></listitem>
7255 <listitem><para><filename>libevent</filename> now splits each shared library into its own package (as Debian does). Since these are shared libraries and will be pulled in through the normal shared library dependency handling, there should be no impact to existing configurations other than less unnecessary libraries being installed in some cases.</para></listitem>
7256 <listitem><para>linux-firmware now has a new package for <filename>bcm4366c</filename> and includes available NVRAM config files into the <filename>bcm43340</filename>, <filename>bcm43362</filename>, <filename>bcm43430</filename> and <filename>bcm4356-pcie</filename> packages.</para></listitem>
7257 <listitem><para><filename>harfbuzz</filename> now splits the new <filename>libharfbuzz-subset.so</filename> library into its own package to reduce the main package size in cases where <filename>libharfbuzz-subset.so</filename> is not needed.</para></listitem>
7258 </itemizedlist>
7259 </para>
7260 </section>
7261
7262 <section id='migration-3.1-package-qa-warnings'>
7263 <title>Additional warnings</title>
7264
7265 <para>
7266 Warnings will now be shown at <filename>do_package_qa</filename> time in the following circumstances:
7267
7268 <itemizedlist>
7269 <listitem><para>A recipe installs <filename>.desktop</filename> files containing <filename>MimeType</filename> keys but does not inherit the new <filename>mime-xdg</filename> class</para></listitem>
7270 <listitem><para>A recipe installs <filename>.xml</filename> files into <filename>${datadir}/mime/packages</filename> but does not inherit the <filename>mime</filename> class</para></listitem>
7271 </itemizedlist>
7272 </para>
7273 </section>
7274
7275 <section id='migration-3.1-x86-live-wic'>
7276 <title><filename>wic</filename> image type now used instead of <filename>live</filename> by default for x86</title>
7277
7278 <para>
7279 <filename>conf/machine/include/x86-base.inc</filename> (inherited by most x86 machine configurations) now specifies <filename>wic</filename> instead of <filename>live</filename> by default in <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. The <filename>live</filename> image type will likely be removed in a future release so it is recommended that you use <filename>wic</filename> instead.
7280 </para>
7281 </section>
7282
7283 <section id='migration-3.1-misc'>
7284 <title>Miscellaneous changes</title>
7285
7286 <para>
7287 <itemizedlist>
7288 <listitem><para>The undocumented <filename>SRC_DISTRIBUTE_LICENSES</filename> variable has now been removed in favour of a new <filename>AVAILABLE_LICENSES</filename> variable which is dynamically set based upon license files found in <filename>${COMMON_LICENSE_DIR}</filename> and <filename>${LICENSE_PATH}</filename>.</para></listitem>
7289 <listitem><para>The tune definition for big-endian microblaze machines is now <filename>microblaze</filename> instead of <filename>microblazeeb</filename>.</para></listitem>
7290 <listitem><para><filename>newlib</filename> no longer has built-in syscalls. <filename>libgloss</filename> should then provide the syscalls, <filename>crt0.o</filename> and other functions that are no longer part of <filename>newlib</filename> itself. If you are using <filename>TCLIBC = "newlib"</filename> this now means that you must link applications with both <filename>newlib</filename> and <filename>libgloss</filename>, whereas before <filename>newlib</filename> would run in many configurations by itself.</para></listitem>
7291 </itemizedlist>
7292 </para>
7293 </section>
7294
7295</section>
7296
7297
7298</chapter>
7299<!--
7300vim: expandtab tw=80 ts=4
7301-->
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
deleted file mode 100644
index 1dcd5fdd03..0000000000
--- a/documentation/ref-manual/ref-classes.xml
+++ /dev/null
@@ -1,3974 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-classes'>
7<title>Classes</title>
8
9<para>
10 Class files are used to abstract common functionality and share it amongst
11 multiple recipe (<filename>.bb</filename>) files.
12 To use a class file, you simply make sure the recipe inherits the class.
13 In most cases, when a recipe inherits a class it is enough to enable its
14 features.
15 There are cases, however, where in the recipe you might need to set
16 variables or override some default behavior.
17</para>
18
19<para>
20 Any <link linkend='metadata'>Metadata</link> usually
21 found in a recipe can also be placed in a class file.
22 Class files are identified by the extension <filename>.bbclass</filename>
23 and are usually placed in a <filename>classes/</filename> directory beneath
24 the <filename>meta*/</filename> directory found in the
25 <link linkend='source-directory'>Source Directory</link>.
26 Class files can also be pointed to by
27 <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
28 (e.g. <filename>build/</filename>) in the same way as
29 <filename>.conf</filename> files in the <filename>conf</filename> directory.
30 Class files are searched for in
31 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
32 using the same method by which <filename>.conf</filename> files are
33 searched.
34</para>
35
36<para>
37 This chapter discusses only the most useful and important classes.
38 Other classes do exist within the <filename>meta/classes</filename>
39 directory in the Source Directory.
40 You can reference the <filename>.bbclass</filename> files directly
41 for more information.
42</para>
43
44<section id='ref-classes-allarch'>
45 <title><filename>allarch.bbclass</filename></title>
46
47 <para>
48 The <filename>allarch</filename> class is inherited
49 by recipes that do not produce architecture-specific output.
50 The class disables functionality that is normally needed for recipes
51 that produce executable binaries (such as building the cross-compiler
52 and a C library as pre-requisites, and splitting out of debug symbols
53 during packaging).
54 <note>
55 <para>Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes
56 that produce packages that depend on tunings through use of the
57 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
58 and
59 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
60 variables, should never be configured for all architectures
61 using <filename>allarch</filename>.
62 This is the case even if the recipes do not produce
63 architecture-specific output.</para>
64 <para>Configuring such recipes for all architectures causes the
65 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
66 tasks to have different signatures for the machines with different
67 tunings.
68 Additionally, unnecessary rebuilds occur every time an
69 image for a different <filename>MACHINE</filename> is built
70 even when the recipe never changes.</para>
71 </note>
72 </para>
73
74 <para>
75 By default, all recipes inherit the
76 <link linkend='ref-classes-base'><filename>base</filename></link> and
77 <link linkend='ref-classes-package'><filename>package</filename></link>
78 classes, which enable functionality
79 needed for recipes that produce executable output.
80 If your recipe, for example, only produces packages that contain
81 configuration files, media files, or scripts (e.g. Python and Perl),
82 then it should inherit the <filename>allarch</filename> class.
83 </para>
84</section>
85
86<section id='ref-classes-archiver'>
87 <title><filename>archiver.bbclass</filename></title>
88
89 <para>
90 The <filename>archiver</filename> class supports releasing
91 source code and other materials with the binaries.
92 </para>
93
94 <para>
95 For more details on the source archiver, see the
96 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
97 section in the Yocto Project Development Tasks Manual.
98 You can also see the
99 <link linkend='var-ARCHIVER_MODE'><filename>ARCHIVER_MODE</filename></link>
100 variable for information about the variable flags (varflags)
101 that help control archive creation.
102 </para>
103</section>
104
105<section id='ref-classes-autotools'>
106 <title><filename>autotools*.bbclass</filename></title>
107
108 <para>
109 The <filename>autotools*</filename> classes support Autotooled
110 packages.
111 </para>
112
113 <para>
114 The <filename>autoconf</filename>, <filename>automake</filename>,
115 and <filename>libtool</filename> packages bring standardization.
116 This class defines a set of tasks (e.g.
117 <filename>configure</filename>, <filename>compile</filename> and
118 so forth) that
119 work for all Autotooled packages.
120 It should usually be enough to define a few standard variables
121 and then simply <filename>inherit autotools</filename>.
122 These classes can also work with software that emulates Autotools.
123 For more information, see the
124 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
125 section in the Yocto Project Development Tasks Manual.
126 </para>
127
128 <para>
129 By default, the <filename>autotools*</filename> classes
130 use out-of-tree builds (i.e.
131 <filename>autotools.bbclass</filename> building with
132 <filename>B != S</filename>).
133 </para>
134
135 <para>
136 If the software being built by a recipe does not support
137 using out-of-tree builds, you should have the recipe inherit the
138 <filename>autotools-brokensep</filename> class.
139 The <filename>autotools-brokensep</filename> class behaves the same
140 as the <filename>autotools</filename> class but builds with
141 <link linkend='var-B'><filename>B</filename></link> ==
142 <link linkend='var-S'><filename>S</filename></link>.
143 This method is useful when out-of-tree build support is either not
144 present or is broken.
145 <note>
146 It is recommended that out-of-tree support be fixed and used
147 if at all possible.
148 </note>
149 </para>
150
151 <para>
152 It's useful to have some idea of how the tasks defined by
153 the <filename>autotools*</filename> classes work and what they do
154 behind the scenes.
155 <itemizedlist>
156 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
157 Regenerates the
158 configure script (using <filename>autoreconf</filename>) and
159 then launches it with a standard set of arguments used during
160 cross-compilation.
161 You can pass additional parameters to
162 <filename>configure</filename> through the
163 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename>
164 or
165 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
166 variables.
167 </para></listitem>
168 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
169 Runs <filename>make</filename> with arguments that specify the
170 compiler and linker.
171 You can pass additional arguments through
172 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename>
173 variable.
174 </para></listitem>
175 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
176 Runs <filename>make install</filename> and passes in
177 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
178 as <filename>DESTDIR</filename>.
179 </para></listitem>
180 </itemizedlist>
181 </para>
182</section>
183
184<section id='ref-classes-base'>
185 <title><filename>base.bbclass</filename></title>
186
187 <para>
188 The <filename>base</filename> class is special in that every
189 <filename>.bb</filename> file implicitly inherits the class.
190 This class contains definitions for standard basic
191 tasks such as fetching, unpacking, configuring (empty by default),
192 compiling (runs any <filename>Makefile</filename> present), installing
193 (empty by default) and packaging (empty by default).
194 These classes are often overridden or extended by other classes
195 such as the
196 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
197 class or the
198 <link linkend='ref-classes-package'><filename>package</filename></link>
199 class.
200 </para>
201
202 <para>
203 The class also contains some commonly used functions such as
204 <filename>oe_runmake</filename>, which runs
205 <filename>make</filename> with the arguments specified in
206 <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link>
207 variable as well as the arguments passed directly to
208 <filename>oe_runmake</filename>.
209 </para>
210</section>
211
212<section id='ref-classes-bash-completion'>
213 <title><filename>bash-completion.bbclass</filename></title>
214
215 <para>
216 Sets up packaging and dependencies appropriate for recipes that
217 build software that includes bash-completion data.
218 </para>
219</section>
220
221<section id='ref-classes-bin-package'>
222 <title><filename>bin_package.bbclass</filename></title>
223
224 <para>
225 The <filename>bin_package</filename> class is a
226 helper class for recipes that extract the contents of a binary package
227 (e.g. an RPM) and install those contents rather than building the
228 binary from source.
229 The binary package is extracted and new packages in the configured
230 output package format are created.
231 Extraction and installation of proprietary binaries is a good example
232 use for this class.
233 <note>
234 For RPMs and other packages that do not contain a subdirectory,
235 you should specify an appropriate fetcher parameter to point to
236 the subdirectory.
237 For example, if BitBake is using the Git fetcher
238 (<filename>git://</filename>), the "subpath" parameter limits
239 the checkout to a specific subpath of the tree.
240 Here is an example where <filename>${BP}</filename> is used so that
241 the files are extracted into the subdirectory expected by the
242 default value of
243 <link linkend='var-S'><filename>S</filename></link>:
244 <literallayout class='monospaced'>
245 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
246 </literallayout>
247 See the
248 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
249 section in the BitBake User Manual for more information on
250 supported BitBake Fetchers.
251 </note>
252 </para>
253</section>
254
255<section id='ref-classes-binconfig'>
256 <title><filename>binconfig.bbclass</filename></title>
257
258 <para>
259 The <filename>binconfig</filename> class helps to correct paths in
260 shell scripts.
261 </para>
262
263 <para>
264 Before <filename>pkg-config</filename> had become widespread, libraries
265 shipped shell scripts to give information about the libraries and
266 include paths needed to build software (usually named
267 <filename>LIBNAME-config</filename>).
268 This class assists any recipe using such scripts.
269 </para>
270
271 <para>
272 During staging, the OpenEmbedded build system installs such scripts
273 into the <filename>sysroots/</filename> directory.
274 Inheriting this class results in all paths in these scripts being
275 changed to point into the <filename>sysroots/</filename> directory so
276 that all builds that use the script use the correct directories
277 for the cross compiling layout.
278 See the
279 <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
280 variable for more information.
281 </para>
282</section>
283
284<section id='ref-classes-binconfig-disabled'>
285 <title><filename>binconfig-disabled.bbclass</filename></title>
286
287 <para>
288 An alternative version of the
289 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
290 class, which disables binary configuration scripts by making them
291 return an error in favor of using <filename>pkg-config</filename>
292 to query the information.
293 The scripts to be disabled should be specified using the
294 <link linkend='var-BINCONFIG'><filename>BINCONFIG</filename></link>
295 variable within the recipe inheriting the class.
296 </para>
297</section>
298
299<section id='ref-classes-blacklist'>
300 <title><filename>blacklist.bbclass</filename></title>
301
302 <para>
303 The <filename>blacklist</filename> class prevents
304 the OpenEmbedded build system from building specific recipes
305 (blacklists them).
306 To use this class, inherit the class globally and set
307 <link linkend='var-PNBLACKLIST'><filename>PNBLACKLIST</filename></link>
308 for each recipe you wish to blacklist.
309 Specify the <link linkend='var-PN'><filename>PN</filename></link>
310 value as a variable flag (varflag) and provide a reason, which is
311 reported, if the package is requested to be built as the value.
312 For example, if you want to blacklist a recipe called "exoticware",
313 you add the following to your <filename>local.conf</filename>
314 or distribution configuration:
315 <literallayout class='monospaced'>
316 INHERIT += "blacklist"
317 PNBLACKLIST[exoticware] = "Not supported by our organization."
318 </literallayout>
319 </para>
320</section>
321
322<section id='ref-classes-buildhistory'>
323 <title><filename>buildhistory.bbclass</filename></title>
324
325 <para>
326 The <filename>buildhistory</filename> class records a
327 history of build output metadata, which can be used to detect possible
328 regressions as well as used for analysis of the build output.
329 For more information on using Build History, see the
330 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
331 section in the Yocto Project Development Tasks Manual.
332 </para>
333</section>
334
335<section id='ref-classes-buildstats'>
336 <title><filename>buildstats.bbclass</filename></title>
337
338 <para>
339 The <filename>buildstats</filename> class records
340 performance statistics about each task executed during the build
341 (e.g. elapsed time, CPU usage, and I/O usage).
342 </para>
343
344 <para>
345 When you use this class, the output goes into the
346 <link linkend='var-BUILDSTATS_BASE'><filename>BUILDSTATS_BASE</filename></link>
347 directory, which defaults to <filename>${TMPDIR}/buildstats/</filename>.
348 You can analyze the elapsed time using
349 <filename>scripts/pybootchartgui/pybootchartgui.py</filename>, which
350 produces a cascading chart of the entire build process and can be
351 useful for highlighting bottlenecks.
352 </para>
353
354 <para>
355 Collecting build statistics is enabled by default through the
356 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
357 variable from your <filename>local.conf</filename> file.
358 Consequently, you do not have to do anything to enable the class.
359 However, if you want to disable the class, simply remove "buildstats"
360 from the <filename>USER_CLASSES</filename> list.
361 </para>
362</section>
363
364<section id='ref-classes-buildstats-summary'>
365 <title><filename>buildstats-summary.bbclass</filename></title>
366
367 <para>
368 When inherited globally, prints statistics at the end of the build
369 on sstate re-use.
370 In order to function, this class requires the
371 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
372 class be enabled.
373 </para>
374</section>
375
376<section id='ref-classes-ccache'>
377 <title><filename>ccache.bbclass</filename></title>
378
379 <para>
380 The <filename>ccache</filename> class enables the C/C++ Compiler Cache
381 for the build.
382 This class is used to give a minor performance boost during the build.
383 However, using the class can lead to unexpected side-effects.
384 Thus, it is recommended that you do not use this class.
385 See <ulink url='http://ccache.samba.org/'></ulink> for information on
386 the C/C++ Compiler Cache.
387 </para>
388</section>
389
390<section id='ref-classes-chrpath'>
391 <title><filename>chrpath.bbclass</filename></title>
392
393 <para>
394 The <filename>chrpath</filename> class
395 is a wrapper around the "chrpath" utility, which is used during the
396 build process for <filename>nativesdk</filename>,
397 <filename>cross</filename>, and
398 <filename>cross-canadian</filename> recipes to change
399 <filename>RPATH</filename> records within binaries in order to make
400 them relocatable.
401 </para>
402</section>
403
404<section id='ref-classes-clutter'>
405 <title><filename>clutter.bbclass</filename></title>
406
407 <para>
408 The <filename>clutter</filename> class consolidates the
409 major and minor version naming and other common items used by Clutter
410 and related recipes.
411 <note>
412 Unlike some other classes related to specific libraries, recipes
413 building other software that uses Clutter do not need to
414 inherit this class unless they use the same recipe versioning
415 scheme that the Clutter and related recipes do.
416 </note>
417 </para>
418</section>
419
420<section id='ref-classes-cmake'>
421 <title><filename>cmake.bbclass</filename></title>
422
423 <para>
424 The <filename>cmake</filename> class allows for recipes that need to
425 build software using the
426 <ulink url='https://cmake.org/overview/'>CMake</ulink> build system.
427 You can use the
428 <link linkend='var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></link>
429 variable to specify additional configuration options to be passed
430 using the <filename>cmake</filename> command line.
431 </para>
432
433 <para>
434 On the occasion that you would be installing custom CMake toolchain
435 files supplied by the application being built, you should install them
436 to the preferred CMake Module directory:
437 <filename>${D}${datadir}/cmake/</filename> Modules during
438 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>.
439 </para>
440</section>
441
442<section id='ref-classes-cml1'>
443 <title><filename>cml1.bbclass</filename></title>
444
445 <para>
446 The <filename>cml1</filename> class provides basic support for the
447 Linux kernel style build configuration system.
448 </para>
449</section>
450
451<section id='ref-classes-compress_doc'>
452 <title><filename>compress_doc.bbclass</filename></title>
453
454 <para>
455 Enables compression for man pages and info pages.
456 This class is intended to be inherited globally.
457 The default compression mechanism is gz (gzip) but you can
458 select an alternative mechanism by setting the
459 <link linkend='var-DOC_COMPRESS'><filename>DOC_COMPRESS</filename></link>
460 variable.
461 </para>
462</section>
463
464<section id='ref-classes-copyleft_compliance'>
465 <title><filename>copyleft_compliance.bbclass</filename></title>
466
467 <para>
468 The <filename>copyleft_compliance</filename> class
469 preserves source code for the purposes of license compliance.
470 This class is an alternative to the <filename>archiver</filename>
471 class and is still used by some users even though it has been
472 deprecated in favor of the
473 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
474 class.
475 </para>
476</section>
477
478<section id='ref-classes-copyleft_filter'>
479 <title><filename>copyleft_filter.bbclass</filename></title>
480
481 <para>
482 A class used by the
483 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
484 and
485 <link linkend='ref-classes-copyleft_compliance'><filename>copyleft_compliance</filename></link>
486 classes for filtering licenses.
487 The <filename>copyleft_filter</filename> class is an internal class
488 and is not intended to be used directly.
489 </para>
490</section>
491
492<section id='ref-classes-core-image'>
493 <title><filename>core-image.bbclass</filename></title>
494
495 <para>
496 The <filename>core-image</filename> class
497 provides common definitions for the
498 <filename>core-image-*</filename> image recipes, such as support for
499 additional
500 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
501 </para>
502</section>
503
504<section id='ref-classes-cpan'>
505 <title><filename>cpan*.bbclass</filename></title>
506
507 <para>
508 The <filename>cpan*</filename> classes support Perl modules.
509 </para>
510
511 <para>
512 Recipes for Perl modules are simple.
513 These recipes usually only need to point to the source's archive and
514 then inherit the proper class file.
515 Building is split into two methods depending on which method the module
516 authors used.
517 <itemizedlist>
518 <listitem><para>Modules that use old
519 <filename>Makefile.PL</filename>-based build system require
520 <filename>cpan.bbclass</filename> in their recipes.
521 </para></listitem>
522 <listitem><para>Modules that use
523 <filename>Build.PL</filename>-based build system require
524 using <filename>cpan_build.bbclass</filename> in their recipes.
525 </para></listitem>
526 </itemizedlist>
527 Both build methods inherit the <filename>cpan-base</filename> class
528 for basic Perl support.
529 </para>
530</section>
531
532<section id='ref-classes-cross'>
533 <title><filename>cross.bbclass</filename></title>
534
535 <para>
536 The <filename>cross</filename> class provides support for the recipes
537 that build the cross-compilation tools.
538 </para>
539</section>
540
541<section id='ref-classes-cross-canadian'>
542 <title><filename>cross-canadian.bbclass</filename></title>
543
544 <para>
545 The <filename>cross-canadian</filename> class
546 provides support for the recipes that build the Canadian
547 Cross-compilation tools for SDKs.
548 See the
549 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
550 section in the Yocto Project Overview and Concepts Manual for more
551 discussion on these cross-compilation tools.
552 </para>
553</section>
554
555<section id='ref-classes-crosssdk'>
556 <title><filename>crosssdk.bbclass</filename></title>
557
558 <para>
559 The <filename>crosssdk</filename> class
560 provides support for the recipes that build the cross-compilation
561 tools used for building SDKs.
562 See the
563 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
564 section in the Yocto Project Overview and Concepts Manual for more
565 discussion on these cross-compilation tools.
566 </para>
567</section>
568
569<section id='ref-classes-debian'>
570 <title><filename>debian.bbclass</filename></title>
571
572 <para>
573 The <filename>debian</filename> class renames output packages so that
574 they follow the Debian naming policy (i.e. <filename>glibc</filename>
575 becomes <filename>libc6</filename> and <filename>glibc-devel</filename>
576 becomes <filename>libc6-dev</filename>.)
577 Renaming includes the library name and version as part of the package
578 name.
579 </para>
580
581 <para>
582 If a recipe creates packages for multiple libraries
583 (shared object files of <filename>.so</filename> type), use the
584 <link linkend='var-LEAD_SONAME'><filename>LEAD_SONAME</filename></link>
585 variable in the recipe to specify the library on which to apply the
586 naming scheme.
587 </para>
588</section>
589
590<section id='ref-classes-deploy'>
591 <title><filename>deploy.bbclass</filename></title>
592
593 <para>
594 The <filename>deploy</filename> class handles deploying files
595 to the
596 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
597 directory.
598 The main function of this class is to allow the deploy step to be
599 accelerated by shared state.
600 Recipes that inherit this class should define their own
601 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
602 function to copy the files to be deployed to
603 <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>,
604 and use <filename>addtask</filename> to add the task at the appropriate
605 place, which is usually after
606 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
607 or
608 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
609 The class then takes care of staging the files from
610 <filename>DEPLOYDIR</filename> to
611 <filename>DEPLOY_DIR_IMAGE</filename>.
612 </para>
613</section>
614
615<section id='ref-classes-devshell'>
616 <title><filename>devshell.bbclass</filename></title>
617
618 <para>
619 The <filename>devshell</filename> class adds the
620 <filename>do_devshell</filename> task.
621 Distribution policy dictates whether to include this class.
622 See the
623 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
624 in the Yocto Project Development Tasks Manual for more information about
625 using <filename>devshell</filename>.
626 </para>
627</section>
628
629<section id='ref-classes-devupstream'>
630 <title><filename>devupstream.bbclass</filename></title>
631
632 <para>
633 The <filename>devupstream</filename> class uses
634 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
635 to add a variant of the recipe that fetches from an alternative URI
636 (e.g. Git) instead of a tarball.
637 Following is an example:
638 <literallayout class='monospaced'>
639 BBCLASSEXTEND = "devupstream:target"
640 SRC_URI_class-devupstream = "git://git.example.com/example"
641 SRCREV_class-devupstream = "abcd1234"
642 </literallayout>
643 Adding the above statements to your recipe creates a variant that has
644 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
645 set to "-1".
646 Consequently, you need to select the variant of the recipe to use it.
647 Any development-specific adjustments can be done by using the
648 <filename>class-devupstream</filename> override.
649 Here is an example:
650 <literallayout class='monospaced'>
651 DEPENDS_append_class-devupstream = " gperf-native"
652
653 do_configure_prepend_class-devupstream() {
654 touch ${S}/README
655 }
656 </literallayout>
657 The class currently only supports creating a development variant of
658 the target recipe, not <filename>native</filename> or
659 <filename>nativesdk</filename> variants.
660 </para>
661
662 <para>
663 The <filename>BBCLASSEXTEND</filename> syntax
664 (i.e. <filename>devupstream:target</filename>) provides support for
665 <filename>native</filename> and <filename>nativesdk</filename>
666 variants.
667 Consequently, this functionality can be added in a future release.
668 </para>
669
670 <para>
671 Support for other version control systems such as Subversion is
672 limited due to BitBake's automatic fetch dependencies (e.g.
673 <filename>subversion-native</filename>).
674 </para>
675</section>
676
677<section id='ref-classes-distro_features_check'>
678 <title><filename>distro_features_check.bbclass</filename></title>
679
680 <para>
681 The <filename>distro_features_check</filename> class
682 allows individual recipes to check for required and conflicting
683 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
684 </para>
685
686 <para>
687 This class provides support for the
688 <link linkend='var-REQUIRED_DISTRO_FEATURES'><filename>REQUIRED_DISTRO_FEATURES</filename></link>
689 and
690 <link linkend='var-CONFLICT_DISTRO_FEATURES'><filename>CONFLICT_DISTRO_FEATURES</filename></link>
691 variables.
692 If any conditions specified in the recipe using the above variables are
693 not met, the recipe will be skipped.
694 </para>
695</section>
696
697<section id='ref-classes-distutils'>
698 <title><filename>distutils*.bbclass</filename></title>
699
700 <para>
701 The <filename>distutils*</filename> classes support recipes for Python
702 version 2.x extensions, which are simple.
703 These recipes usually only need to point to the source's archive and
704 then inherit the proper class.
705 Building is split into two methods depending on which method the
706 module authors used.
707 <itemizedlist>
708 <listitem><para>Extensions that use an Autotools-based build system
709 require Autotools and the classes based on
710 <filename>distutils</filename> in their recipes.
711 </para></listitem>
712 <listitem><para>Extensions that use build systems based on
713 <filename>distutils</filename> require
714 the <filename>distutils</filename> class in their recipes.
715 </para></listitem>
716 <listitem><para>Extensions that use build systems based on
717 <filename>setuptools</filename> require the
718 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
719 class in their recipes.
720 </para></listitem>
721 </itemizedlist>
722 The <filename>distutils-common-base</filename> class is required by
723 some of the <filename>distutils*</filename> classes to provide common
724 Python2 support.
725 </para>
726</section>
727
728<section id='ref-classes-distutils3'>
729 <title><filename>distutils3*.bbclass</filename></title>
730
731 <para>
732 The <filename>distutils3*</filename> classes support recipes for Python
733 version 3.x extensions, which are simple.
734 These recipes usually only need to point to the source's archive and
735 then inherit the proper class.
736 Building is split into three methods depending on which method the
737 module authors used.
738 <itemizedlist>
739 <listitem><para>Extensions that use an Autotools-based build system
740 require Autotools and
741 <filename>distutils</filename>-based classes in their recipes.
742 </para></listitem>
743 <listitem><para>Extensions that use
744 <filename>distutils</filename>-based build systems require
745 the <filename>distutils</filename> class in their recipes.
746 </para></listitem>
747 <listitem><para>Extensions that use build systems based on
748 <filename>setuptools3</filename> require the
749 <link linkend='ref-classes-setuptools'><filename>setuptools3</filename></link>
750 class in their recipes.
751 </para></listitem>
752 </itemizedlist>
753 The <filename>distutils3*</filename> classes either inherit their
754 corresponding <filename>distutils*</filename> class or replicate them
755 using a Python3 version instead (e.g.
756 <filename>distutils3-base</filename> inherits
757 <filename>distutils-common-base</filename>, which is the same as
758 <filename>distutils-base</filename> but inherits
759 <filename>python3native</filename> instead of
760 <filename>pythonnative</filename>).
761 </para>
762</section>
763
764<section id='ref-classes-externalsrc'>
765 <title><filename>externalsrc.bbclass</filename></title>
766
767 <para>
768 The <filename>externalsrc</filename> class supports building software
769 from source code that is external to the OpenEmbedded build system.
770 Building software from an external source tree means that the build
771 system's normal fetch, unpack, and patch process is not used.
772 </para>
773
774 <para>
775 By default, the OpenEmbedded build system uses the
776 <link linkend='var-S'><filename>S</filename></link> and
777 <link linkend='var-B'><filename>B</filename></link> variables to
778 locate unpacked recipe source code and to build it, respectively.
779 When your recipe inherits the <filename>externalsrc</filename> class,
780 you use the
781 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
782 and
783 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
784 variables to ultimately define <filename>S</filename> and
785 <filename>B</filename>.
786 </para>
787
788 <para>
789 By default, this class expects the source code to support recipe builds
790 that use the <link linkend='var-B'><filename>B</filename></link>
791 variable to point to the directory in which the OpenEmbedded build
792 system places the generated objects built from the recipes.
793 By default, the <filename>B</filename> directory is set to the
794 following, which is separate from the source directory
795 (<filename>S</filename>):
796 <literallayout class='monospaced'>
797 ${WORKDIR}/${BPN}/{PV}/
798 </literallayout>
799 See these variables for more information:
800 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
801 <link linkend='var-BPN'><filename>BPN</filename></link>, and
802 <link linkend='var-PV'><filename>PV</filename></link>,
803 </para>
804
805 <para>
806 For more information on the
807 <filename>externalsrc</filename> class, see the comments in
808 <filename>meta/classes/externalsrc.bbclass</filename> in the
809 <link linkend='source-directory'>Source Directory</link>.
810 For information on how to use the <filename>externalsrc</filename>
811 class, see the
812 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
813 section in the Yocto Project Development Tasks Manual.
814 </para>
815</section>
816
817<section id='ref-classes-extrausers'>
818 <title><filename>extrausers.bbclass</filename></title>
819
820 <para>
821 The <filename>extrausers</filename> class allows
822 additional user and group configuration to be applied at the image
823 level.
824 Inheriting this class either globally or from an image recipe allows
825 additional user and group operations to be performed using the
826 <link linkend='var-EXTRA_USERS_PARAMS'><filename>EXTRA_USERS_PARAMS</filename></link>
827 variable.
828 <note>
829 The user and group operations added using the
830 <filename>extrausers</filename> class are not tied to a specific
831 recipe outside of the recipe for the image.
832 Thus, the operations can be performed across the image as a whole.
833 Use the
834 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
835 class to add user and group configuration to a specific recipe.
836 </note>
837 Here is an example that uses this class in an image recipe:
838 <literallayout class='monospaced'>
839 inherit extrausers
840 EXTRA_USERS_PARAMS = "\
841 useradd -p '' tester; \
842 groupadd developers; \
843 userdel nobody; \
844 groupdel -g video; \
845 groupmod -g 1020 developers; \
846 usermod -s /bin/sh tester; \
847 "
848 </literallayout>
849 Here is an example that adds two users named "tester-jim" and
850 "tester-sue" and assigns passwords:
851 <literallayout class='monospaced'>
852 inherit extrausers
853 EXTRA_USERS_PARAMS = "\
854 useradd -P tester01 tester-jim; \
855 useradd -P tester01 tester-sue; \
856 "
857 </literallayout>
858 Finally, here is an example that sets the root password to
859 "1876*18":
860 <literallayout class='monospaced'>
861 inherit extrausers
862 EXTRA_USERS_PARAMS = "\
863 usermod -P 1876*18 root; \
864 "
865 </literallayout>
866 </para>
867</section>
868
869<section id='ref-classes-fontcache'>
870 <title><filename>fontcache.bbclass</filename></title>
871
872 <para>
873 The <filename>fontcache</filename> class generates the
874 proper post-install and post-remove (postinst and postrm)
875 scriptlets for font packages.
876 These scriptlets call <filename>fc-cache</filename> (part of
877 <filename>Fontconfig</filename>) to add the fonts to the font
878 information cache.
879 Since the cache files are architecture-specific,
880 <filename>fc-cache</filename> runs using QEMU if the postinst
881 scriptlets need to be run on the build host during image creation.
882 </para>
883
884 <para>
885 If the fonts being installed are in packages other than the main
886 package, set
887 <link linkend='var-FONT_PACKAGES'><filename>FONT_PACKAGES</filename></link>
888 to specify the packages containing the fonts.
889 </para>
890</section>
891
892<section id='ref-classes-fs-uuid'>
893 <title><filename>fs-uuid.bbclass</filename></title>
894
895 <para>
896 The <filename>fs-uuid</filename> class extracts UUID from
897 <filename>${</filename><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link><filename>}</filename>,
898 which must have been built by the time that this function gets called.
899 The <filename>fs-uuid</filename> class only works on
900 <filename>ext</filename> file systems and depends on
901 <filename>tune2fs</filename>.
902 </para>
903</section>
904
905<section id='ref-classes-gconf'>
906 <title><filename>gconf.bbclass</filename></title>
907
908 <para>
909 The <filename>gconf</filename> class provides common
910 functionality for recipes that need to install GConf schemas.
911 The schemas will be put into a separate package
912 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-gconf</filename>)
913 that is created automatically when this class is inherited.
914 This package uses the appropriate post-install and post-remove
915 (postinst/postrm) scriptlets to register and unregister the schemas
916 in the target image.
917 </para>
918</section>
919
920<section id='ref-classes-gettext'>
921 <title><filename>gettext.bbclass</filename></title>
922
923 <para>
924 The <filename>gettext</filename> class provides support for
925 building software that uses the GNU <filename>gettext</filename>
926 internationalization and localization system.
927 All recipes building software that use
928 <filename>gettext</filename> should inherit this class.
929 </para>
930</section>
931
932<section id='ref-classes-gnomebase'>
933 <title><filename>gnomebase.bbclass</filename></title>
934
935 <para>
936 The <filename>gnomebase</filename> class is the base
937 class for recipes that build software from the GNOME stack.
938 This class sets
939 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> to
940 download the source from the GNOME mirrors as well as extending
941 <link linkend='var-FILES'><filename>FILES</filename></link>
942 with the typical GNOME installation paths.
943 </para>
944</section>
945
946<section id='ref-classes-gobject-introspection'>
947 <title><filename>gobject-introspection.bbclass</filename></title>
948
949 <para>
950 Provides support for recipes building software that
951 supports GObject introspection.
952 This functionality is only enabled if the
953 "gobject-introspection-data" feature is in
954 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
955 as well as "qemu-usermode" being in
956 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
957 <note>
958 This functionality is backfilled by default and,
959 if not applicable, should be disabled through
960 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
961 or
962 <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>,
963 respectively.
964 </note>
965 </para>
966</section>
967
968<section id='ref-classes-grub-efi'>
969 <title><filename>grub-efi.bbclass</filename></title>
970
971 <para>
972 The <filename>grub-efi</filename>
973 class provides <filename>grub-efi</filename>-specific functions for
974 building bootable images.
975 </para>
976
977 <para>
978 This class supports several variables:
979 <itemizedlist>
980 <listitem><para>
981 <link linkend='var-INITRD'><filename>INITRD</filename></link>:
982 Indicates list of filesystem images to concatenate and use
983 as an initial RAM disk (initrd) (optional).
984 </para></listitem>
985 <listitem><para>
986 <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
987 Indicates a filesystem image to include as the root filesystem
988 (optional).</para></listitem>
989 <listitem><para>
990 <link linkend='var-GRUB_GFXSERIAL'><filename>GRUB_GFXSERIAL</filename></link>:
991 Set this to "1" to have graphics and serial in the boot menu.
992 </para></listitem>
993 <listitem><para>
994 <link linkend='var-LABELS'><filename>LABELS</filename></link>:
995 A list of targets for the automatic configuration.
996 </para></listitem>
997 <listitem><para>
998 <link linkend='var-APPEND'><filename>APPEND</filename></link>:
999 An override list of append strings for each
1000 <filename>LABEL</filename>.
1001 </para></listitem>
1002 <listitem><para>
1003 <link linkend='var-GRUB_OPTS'><filename>GRUB_OPTS</filename></link>:
1004 Additional options to add to the configuration (optional).
1005 Options are delimited using semi-colon characters
1006 (<filename>;</filename>).</para></listitem>
1007 <listitem><para>
1008 <link linkend='var-GRUB_TIMEOUT'><filename>GRUB_TIMEOUT</filename></link>:
1009 Timeout before executing the default <filename>LABEL</filename>
1010 (optional).
1011 </para></listitem>
1012 </itemizedlist>
1013 </para>
1014</section>
1015
1016<section id='ref-classes-gsettings'>
1017 <title><filename>gsettings.bbclass</filename></title>
1018
1019 <para>
1020 The <filename>gsettings</filename> class
1021 provides common functionality for recipes that need to install
1022 GSettings (glib) schemas.
1023 The schemas are assumed to be part of the main package.
1024 Appropriate post-install and post-remove (postinst/postrm)
1025 scriptlets are added to register and unregister the schemas in the
1026 target image.
1027 </para>
1028</section>
1029
1030<section id='ref-classes-gtk-doc'>
1031 <title><filename>gtk-doc.bbclass</filename></title>
1032
1033 <para>
1034 The <filename>gtk-doc</filename> class
1035 is a helper class to pull in the appropriate
1036 <filename>gtk-doc</filename> dependencies and disable
1037 <filename>gtk-doc</filename>.
1038 </para>
1039</section>
1040
1041<section id='ref-classes-gtk-icon-cache'>
1042 <title><filename>gtk-icon-cache.bbclass</filename></title>
1043
1044 <para>
1045 The <filename>gtk-icon-cache</filename> class
1046 generates the proper post-install and post-remove (postinst/postrm)
1047 scriptlets for packages that use GTK+ and install icons.
1048 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
1049 the fonts to GTK+'s icon cache.
1050 Since the cache files are architecture-specific,
1051 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
1052 postinst scriptlets need to be run on the build host during image
1053 creation.
1054 </para>
1055</section>
1056
1057<section id='ref-classes-gtk-immodules-cache'>
1058 <title><filename>gtk-immodules-cache.bbclass</filename></title>
1059
1060 <para>
1061 The <filename>gtk-immodules-cache</filename> class
1062 generates the proper post-install and post-remove (postinst/postrm)
1063 scriptlets for packages that install GTK+ input method modules for
1064 virtual keyboards.
1065 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
1066 the input method modules to the cache.
1067 Since the cache files are architecture-specific,
1068 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
1069 postinst scriptlets need to be run on the build host during image
1070 creation.
1071 </para>
1072
1073 <para>
1074 If the input method modules being installed are in packages other than
1075 the main package, set
1076 <link linkend='var-GTKIMMODULES_PACKAGES'><filename>GTKIMMODULES_PACKAGES</filename></link>
1077 to specify the packages containing the modules.
1078 </para>
1079</section>
1080
1081<section id='ref-classes-gzipnative'>
1082 <title><filename>gzipnative.bbclass</filename></title>
1083
1084 <para>
1085 The <filename>gzipnative</filename> class enables the use of
1086 different native versions of <filename>gzip</filename>
1087 and <filename>pigz</filename> rather than the versions of these tools
1088 from the build host.
1089 </para>
1090</section>
1091
1092<section id='ref-classes-icecc'>
1093 <title><filename>icecc.bbclass</filename></title>
1094
1095 <para>
1096 The <filename>icecc</filename> class supports
1097 <ulink url='https://github.com/icecc/icecream'>Icecream</ulink>, which
1098 facilitates taking compile jobs and distributing them among remote
1099 machines.
1100 </para>
1101
1102 <para>
1103 The class stages directories with symlinks from <filename>gcc</filename>
1104 and <filename>g++</filename> to <filename>icecc</filename>, for both
1105 native and cross compilers.
1106 Depending on each configure or compile, the OpenEmbedded build system
1107 adds the directories at the head of the <filename>PATH</filename> list
1108 and then sets the <filename>ICECC_CXX</filename> and
1109 <filename>ICEC_CC</filename> variables, which are the paths to the
1110 <filename>g++</filename> and <filename>gcc</filename> compilers,
1111 respectively.
1112 </para>
1113
1114 <para>
1115 For the cross compiler, the class creates a <filename>tar.gz</filename>
1116 file that contains the Yocto Project toolchain and sets
1117 <filename>ICECC_VERSION</filename>, which is the version of the
1118 cross-compiler used in the cross-development toolchain, accordingly.
1119 </para>
1120
1121 <para>
1122 The class handles all three different compile stages
1123 (i.e native ,cross-kernel and target) and creates the necessary
1124 environment <filename>tar.gz</filename> file to be used by the remote
1125 machines.
1126 The class also supports SDK generation.
1127 </para>
1128
1129 <para>
1130 If <link linkend='var-ICECC_PATH'><filename>ICECC_PATH</filename></link>
1131 is not set in your <filename>local.conf</filename> file, then the
1132 class tries to locate the <filename>icecc</filename> binary
1133 using <filename>which</filename>.
1134
1135 If
1136 <link linkend='var-ICECC_ENV_EXEC'><filename>ICECC_ENV_EXEC</filename></link>
1137 is set in your <filename>local.conf</filename> file, the variable should
1138 point to the <filename>icecc-create-env</filename> script
1139 provided by the user.
1140 If you do not point to a user-provided script, the build system
1141 uses the default script provided by the recipe
1142 <filename>icecc-create-env-native.bb</filename>.
1143 <note>
1144 This script is a modified version and not the one that comes with
1145 <filename>icecc</filename>.
1146 </note>
1147 </para>
1148
1149 <para>
1150 If you do not want the Icecream distributed compile support to apply
1151 to specific recipes or classes, you can effectively "blacklist" them
1152 by listing the recipes and classes using the
1153 <link linkend='var-ICECC_USER_PACKAGE_BL'><filename>ICECC_USER_PACKAGE_BL</filename></link>
1154 and
1155 <link linkend='var-ICECC_USER_CLASS_BL'><filename>ICECC_USER_CLASS_BL</filename></link>,
1156 variables, respectively, in your <filename>local.conf</filename> file.
1157 Doing so causes the OpenEmbedded build system to handle these
1158 compilations locally.
1159 </para>
1160
1161 <para>
1162 Additionally, you can list recipes using the
1163 <link linkend='var-ICECC_USER_PACKAGE_WL'><filename>ICECC_USER_PACKAGE_WL</filename></link>
1164 variable in your <filename>local.conf</filename> file to force
1165 <filename>icecc</filename> to be enabled for recipes using an empty
1166 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
1167 variable.
1168 </para>
1169
1170 <para>
1171 Inheriting the <filename>icecc</filename> class changes all sstate
1172 signatures.
1173 Consequently, if a development team has a dedicated build system
1174 that populates
1175 <link linkend='var-SSTATE_MIRRORS'><filename>STATE_MIRRORS</filename></link>
1176 and they want to reuse sstate from
1177 <filename>STATE_MIRRORS</filename>, then all developers and the
1178 build system need to either inherit the <filename>icecc</filename>
1179 class or nobody should.
1180 </para>
1181
1182 <para>
1183 At the distribution level, you can inherit the
1184 <filename>icecc</filename> class to be sure that all builders start
1185 with the same sstate signatures.
1186 After inheriting the class, you can then disable the feature by setting
1187 the
1188 <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link>
1189 variable to "1" as follows:
1190 <literallayout class='monospaced'>
1191 INHERIT_DISTRO_append = " icecc"
1192 ICECC_DISABLED ??= "1"
1193 </literallayout>
1194 This practice makes sure everyone is using the same signatures but also
1195 requires individuals that do want to use Icecream to enable the feature
1196 individually as follows in your <filename>local.conf</filename> file:
1197 <literallayout class='monospaced'>
1198 ICECC_DISABLED = ""
1199 </literallayout>
1200 </para>
1201</section>
1202
1203<section id='ref-classes-image'>
1204 <title><filename>image.bbclass</filename></title>
1205
1206 <para>
1207 The <filename>image</filename> class helps support creating images
1208 in different formats.
1209 First, the root filesystem is created from packages using
1210 one of the <filename>rootfs*.bbclass</filename>
1211 files (depending on the package format used) and then one or more image
1212 files are created.
1213 <itemizedlist>
1214 <listitem><para>The
1215 <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
1216 variable controls the types of images to generate.
1217 </para></listitem>
1218 <listitem><para>The
1219 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
1220 variable controls the list of packages to install into the
1221 image.</para></listitem>
1222 </itemizedlist>
1223 For information on customizing images, see the
1224 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
1225 section in the Yocto Project Development Tasks Manual.
1226 For information on how images are created, see the
1227 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
1228 section in the Yocto Project Overview and Concpets Manual.
1229 </para>
1230</section>
1231
1232<section id='ref-classes-image-buildinfo'>
1233 <title><filename>image-buildinfo.bbclass</filename></title>
1234
1235 <para>
1236 The <filename>image-buildinfo</filename> class writes information
1237 to the target filesystem on <filename>/etc/build</filename>.
1238 </para>
1239</section>
1240
1241<section id='ref-classes-image_types'>
1242 <title><filename>image_types.bbclass</filename></title>
1243
1244 <para>
1245 The <filename>image_types</filename> class defines all of the
1246 standard image output types that you can enable through the
1247 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1248 variable.
1249 You can use this class as a reference on how to add support for
1250 custom image output types.
1251 </para>
1252
1253 <para>
1254 By default, the
1255 <link linkend='ref-classes-image'><filename>image</filename></link>
1256 class automatically enables the <filename>image_types</filename> class.
1257 The <filename>image</filename> class uses the
1258 <filename>IMGCLASSES</filename> variable as follows:
1259 <literallayout class='monospaced'>
1260 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
1261 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
1262 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
1263 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
1264 IMGCLASSES += "image_types_wic"
1265 IMGCLASSES += "rootfs-postcommands"
1266 IMGCLASSES += "image-postinst-intercepts"
1267 inherit ${IMGCLASSES}
1268 </literallayout>
1269 </para>
1270
1271 <para>
1272 The <filename>image_types</filename> class also handles conversion and
1273 compression of images.
1274 <note>
1275 To build a VMware VMDK image, you need to add "wic.vmdk" to
1276 <filename>IMAGE_FSTYPES</filename>.
1277 This would also be similar for Virtual Box Virtual Disk Image
1278 ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
1279 </note>
1280 </para>
1281</section>
1282
1283<section id='ref-classes-image-live'>
1284 <title><filename>image-live.bbclass</filename></title>
1285
1286 <para>
1287 This class controls building "live" (i.e. HDDIMG and ISO) images.
1288 Live images contain syslinux for legacy booting, as well as the
1289 bootloader specified by
1290 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
1291 if
1292 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1293 contains "efi".
1294 </para>
1295
1296 <para>
1297 Normally, you do not use this class directly.
1298 Instead, you add "live" to
1299 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
1300 </para>
1301</section>
1302
1303<section id='ref-classes-image-mklibs'>
1304 <title><filename>image-mklibs.bbclass</filename></title>
1305
1306 <para>
1307 The <filename>image-mklibs</filename> class
1308 enables the use of the <filename>mklibs</filename> utility during the
1309 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1310 task, which optimizes the size of
1311 libraries contained in the image.
1312 </para>
1313
1314 <para>
1315 By default, the class is enabled in the
1316 <filename>local.conf.template</filename> using the
1317 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1318 variable as follows:
1319 <literallayout class='monospaced'>
1320 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1321 </literallayout>
1322 </para>
1323</section>
1324
1325<section id='ref-classes-image-prelink'>
1326 <title><filename>image-prelink.bbclass</filename></title>
1327
1328 <para>
1329 The <filename>image-prelink</filename> class
1330 enables the use of the <filename>prelink</filename> utility during
1331 the
1332 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1333 task, which optimizes the dynamic
1334 linking of shared libraries to reduce executable startup time.
1335 </para>
1336
1337 <para>
1338 By default, the class is enabled in the
1339 <filename>local.conf.template</filename> using the
1340 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1341 variable as follows:
1342 <literallayout class='monospaced'>
1343 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1344 </literallayout>
1345 </para>
1346</section>
1347
1348<section id='ref-classes-insane'>
1349 <title><filename>insane.bbclass</filename></title>
1350
1351 <para>
1352 The <filename>insane</filename> class adds a step to the package
1353 generation process so that output quality assurance checks are
1354 generated by the OpenEmbedded build system.
1355 A range of checks are performed that check the build's output
1356 for common problems that show up during runtime.
1357 Distribution policy usually dictates whether to include this class.
1358 </para>
1359
1360 <para>
1361 You can configure the sanity checks so that specific test failures
1362 either raise a warning or an error message.
1363 Typically, failures for new tests generate a warning.
1364 Subsequent failures for the same test would then generate an error
1365 message once the metadata is in a known and good condition.
1366 See the
1367 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1368 Chapter for a list of all the warning and error messages
1369 you might encounter using a default configuration.
1370 </para>
1371
1372 <para>
1373 Use the
1374 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1375 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1376 variables to control the behavior of
1377 these checks at the global level (i.e. in your custom distro
1378 configuration).
1379 However, to skip one or more checks in recipes, you should use
1380 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1381 For example, to skip the check for symbolic link
1382 <filename>.so</filename> files in the main package of a recipe,
1383 add the following to the recipe.
1384 You need to realize that the package name override, in this example
1385 <filename>${PN}</filename>, must be used:
1386 <literallayout class='monospaced'>
1387 INSANE_SKIP_${PN} += "dev-so"
1388 </literallayout>
1389 Please keep in mind that the QA checks exist in order to detect real
1390 or potential problems in the packaged output.
1391 So exercise caution when disabling these checks.
1392 </para>
1393
1394 <para>
1395 The following list shows the tests you can list with the
1396 <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
1397 variables:
1398 <itemizedlist>
1399 <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
1400 Checks that produced binaries have not already been
1401 stripped prior to the build system extracting debug symbols.
1402 It is common for upstream software projects to default to
1403 stripping debug symbols for output binaries.
1404 In order for debugging to work on the target using
1405 <filename>-dbg</filename> packages, this stripping must be
1406 disabled.
1407 </para></listitem>
1408 <listitem><para><emphasis><filename>arch:</filename></emphasis>
1409 Checks the Executable and Linkable Format (ELF) type, bit size,
1410 and endianness of any binaries to ensure they match the target
1411 architecture.
1412 This test fails if any binaries do not match the type since
1413 there would be an incompatibility.
1414 The test could indicate that the
1415 wrong compiler or compiler options have been used.
1416 Sometimes software, like bootloaders, might need to bypass
1417 this check.
1418 </para></listitem>
1419 <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
1420 Checks for paths to locations on the build host inside the
1421 output files.
1422 Currently, this test triggers too many false positives and
1423 thus is not normally enabled.
1424 </para></listitem>
1425 <listitem><para><emphasis><filename>build-deps:</filename></emphasis>
1426 Determines if a build-time dependency that is specified through
1427 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
1428 explicit
1429 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1430 or task-level dependencies exists to match any runtime
1431 dependency.
1432 This determination is particularly useful to discover where
1433 runtime dependencies are detected and added during packaging.
1434 If no explicit dependency has been specified within the
1435 metadata, at the packaging stage it is too late to ensure that
1436 the dependency is built, and thus you can end up with an
1437 error when the package is installed into the image during the
1438 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1439 task because the auto-detected dependency was not satisfied.
1440 An example of this would be where the
1441 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
1442 class automatically adds a dependency on the
1443 <filename>initscripts-functions</filename> package to packages
1444 that install an initscript that refers to
1445 <filename>/etc/init.d/functions</filename>.
1446 The recipe should really have an explicit
1447 <filename>RDEPENDS</filename> for the package in question on
1448 <filename>initscripts-functions</filename> so that the
1449 OpenEmbedded build system is able to ensure that the
1450 <filename>initscripts</filename> recipe is actually built and
1451 thus the <filename>initscripts-functions</filename> package is
1452 made available.
1453 </para></listitem>
1454 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
1455 Checks the
1456 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1457 log for indications
1458 that paths to locations on the build host were used.
1459 Using such paths might result in host contamination of the
1460 build output.
1461 </para></listitem>
1462 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
1463 Checks that all packages except <filename>-dbg</filename>
1464 packages do not depend on <filename>-dbg</filename>
1465 packages, which would cause a packaging bug.
1466 </para></listitem>
1467 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
1468 Checks for <filename>.debug</filename> directories in anything but the
1469 <filename>-dbg</filename> package.
1470 The debug files should all be in the <filename>-dbg</filename> package.
1471 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
1472 <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
1473 Checks for invalid version comparison statements in runtime
1474 dependency relationships between packages (i.e. in
1475 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1476 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1477 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1478 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1479 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1480 and
1481 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
1482 variable values).
1483 Any invalid comparisons might trigger failures or undesirable
1484 behavior when passed to the package manager.
1485 </para></listitem>
1486 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
1487 Runs the <filename>desktop-file-validate</filename> program
1488 against any <filename>.desktop</filename> files to validate
1489 their contents against the specification for
1490 <filename>.desktop</filename> files.</para></listitem>
1491 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
1492 Checks that all packages except <filename>-dev</filename>
1493 or <filename>-staticdev</filename> packages do not depend on
1494 <filename>-dev</filename> packages, which would be a
1495 packaging bug.</para></listitem>
1496 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
1497 Checks that the <filename>.so</filename> symbolic links are in the
1498 <filename>-dev</filename> package and not in any of the other packages.
1499 In general, these symlinks are only useful for development purposes.
1500 Thus, the <filename>-dev</filename> package is the correct location for
1501 them.
1502 Some very rare cases do exist for dynamically loaded modules where
1503 these symlinks are needed instead in the main package.
1504 </para></listitem>
1505 <listitem><para><emphasis><filename>file-rdeps:</filename></emphasis>
1506 Checks that file-level dependencies identified by the
1507 OpenEmbedded build system at packaging time are satisfied.
1508 For example, a shell script might start with the line
1509 <filename>#!/bin/bash</filename>.
1510 This line would translate to a file dependency on
1511 <filename>/bin/bash</filename>.
1512 Of the three package managers that the OpenEmbedded build
1513 system supports, only RPM directly handles file-level
1514 dependencies, resolving them automatically to packages
1515 providing the files.
1516 However, the lack of that functionality in the other two
1517 package managers does not mean the dependencies do not still
1518 need resolving.
1519 This QA check attempts to ensure that explicitly declared
1520 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1521 exist to handle any file-level dependency detected in
1522 packaged files.
1523 </para></listitem>
1524 <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
1525 Checks for
1526 <link linkend='var-FILES'><filename>FILES</filename></link>
1527 variable values that contain "//", which is invalid.
1528 </para></listitem>
1529 <listitem><para id='insane-host-user-contaminated'>
1530 <emphasis><filename>host-user-contaminated:</filename></emphasis>
1531 Checks that no package produced by the recipe contains any
1532 files outside of <filename>/home</filename> with a user or
1533 group ID that matches the user running BitBake.
1534 A match usually indicates that the files are being installed
1535 with an incorrect UID/GID, since target IDs are independent
1536 from host IDs.
1537 For additional information, see the section describing the
1538 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1539 task.
1540 </para></listitem>
1541 <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
1542 Report when packages are excluded from being created due to
1543 being marked with a license that is in
1544 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
1545 </para></listitem>
1546 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
1547 Checks the
1548 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1549 log for indications
1550 that paths to locations on the build host were used.
1551 Using such paths might result in host contamination of the
1552 build output.
1553 </para></listitem>
1554 <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
1555 Reports when files have been installed within
1556 <filename>do_install</filename> but have not been included in
1557 any package by way of the
1558 <link linkend='var-FILES'><filename>FILES</filename></link>
1559 variable.
1560 Files that do not appear in any package cannot be present in
1561 an image later on in the build process.
1562 Ideally, all installed files should be packaged or not
1563 installed at all.
1564 These files can be deleted at the end of
1565 <filename>do_install</filename> if the files are not
1566 needed in any package.
1567 </para></listitem>
1568 <listitem><para><emphasis><filename>invalid-chars:</filename></emphasis>
1569 Checks that the recipe metadata variables
1570 <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>,
1571 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>,
1572 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>,
1573 and
1574 <link linkend='var-SECTION'><filename>SECTION</filename></link>
1575 do not contain non-UTF-8 characters.
1576 Some package managers do not support such characters.
1577 </para></listitem>
1578 <listitem><para><emphasis><filename>invalid-packageconfig:</filename></emphasis>
1579 Checks that no undefined features are being added to
1580 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>.
1581 For example, any name "foo" for which the following form
1582 does not exist:
1583 <literallayout class='monospaced'>
1584 PACKAGECONFIG[foo] = "..."
1585 </literallayout>
1586 </para></listitem>
1587 <listitem><para><emphasis><filename>la:</filename></emphasis>
1588 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
1589 paths.
1590 Any <filename>.la</filename> file containing these paths is incorrect since
1591 <filename>libtool</filename> adds the correct sysroot prefix when using the
1592 files automatically itself.</para></listitem>
1593 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
1594 Ensures that the binaries were linked with the
1595 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1596 options provided by the build system.
1597 If this test fails, check that the <filename>LDFLAGS</filename> variable
1598 is being passed to the linker command.</para></listitem>
1599 <listitem><para><emphasis><filename>libdir:</filename></emphasis>
1600 Checks for libraries being installed into incorrect
1601 (possibly hardcoded) installation paths.
1602 For example, this test will catch recipes that install
1603 <filename>/lib/bar.so</filename> when
1604 <filename>${base_libdir}</filename> is "lib32".
1605 Another example is when recipes install
1606 <filename>/usr/lib64/foo.so</filename> when
1607 <filename>${libdir}</filename> is "/usr/lib".
1608 </para></listitem>
1609 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
1610 Checks if a package contains files in
1611 <filename>/usr/libexec</filename>.
1612 This check is not performed if the
1613 <filename>libexecdir</filename> variable has been set
1614 explicitly to <filename>/usr/libexec</filename>.
1615 </para></listitem>
1616 <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
1617 Checks for the same package being listed multiple times through
1618 the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1619 variable value.
1620 Installing the package in this manner can cause errors during
1621 packaging.
1622 </para></listitem>
1623 <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
1624 Reports lines in <filename>fs-perms.txt</filename> that have
1625 an invalid format.
1626 </para></listitem>
1627 <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
1628 Reports lines in <filename>fs-perms.txt</filename> that have
1629 an invalid format.
1630 </para></listitem>
1631 <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
1632 Reports lines in <filename>fs-perms.txt</filename> that
1633 specify 'link' where the specified target already exists.
1634 </para></listitem>
1635 <listitem><para><emphasis><filename>perms:</filename></emphasis>
1636 Currently, this check is unused but reserved.
1637 </para></listitem>
1638 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
1639 Checks <filename>.pc</filename> files for any
1640 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
1641 paths.
1642 Any <filename>.pc</filename> file containing these paths is incorrect
1643 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
1644 when the files are accessed.</para></listitem>
1645 <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
1646 Checks that all packages in
1647 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1648 have names that do not contain invalid characters (i.e.
1649 characters other than 0-9, a-z, ., +, and -).
1650 </para></listitem>
1651 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
1652 Checks to see if the <filename>PKGV</filename> variable
1653 is undefined during
1654 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1655 </para></listitem>
1656 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
1657 Checks through the variables
1658 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1659 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1660 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1661 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
1662 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1663 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1664 <link linkend='var-FILES'><filename>FILES</filename></link>,
1665 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
1666 <filename>pkg_preinst</filename>,
1667 <filename>pkg_postinst</filename>,
1668 <filename>pkg_prerm</filename>
1669 and <filename>pkg_postrm</filename>, and reports if there are
1670 variable sets that are not package-specific.
1671 Using these variables without a package suffix is bad practice,
1672 and might unnecessarily complicate dependencies of other packages
1673 within the same recipe or have other unintended consequences.
1674 </para></listitem>
1675 <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
1676 Checks that a recipe does not have a name
1677 (<link linkend='var-PN'><filename>PN</filename></link>) value
1678 that appears in
1679 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
1680 If a recipe is named such that its <filename>PN</filename>
1681 value matches something already in
1682 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
1683 happens to be the same as
1684 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
1685 or
1686 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
1687 it can have unexpected consequences.
1688 For example, assignments such as
1689 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
1690 <filename>FILES = "xyz"</filename>.
1691 </para></listitem>
1692 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
1693 Checks for rpaths in the binaries that contain build system paths such
1694 as <filename>TMPDIR</filename>.
1695 If this test fails, bad <filename>-rpath</filename> options are being
1696 passed to the linker commands and your binaries have potential security
1697 issues.</para></listitem>
1698 <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
1699 Reports that splitting or stripping debug symbols from binaries
1700 has failed.
1701 </para></listitem>
1702 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
1703 Checks for static library files (<filename>*.a</filename>) in
1704 non-<filename>staticdev</filename> packages.
1705 </para></listitem>
1706 <listitem><para><emphasis><filename>symlink-to-sysroot:</filename></emphasis>
1707 Checks for symlinks in packages that point into
1708 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1709 on the host.
1710 Such symlinks will work on the host, but are clearly invalid
1711 when running on the target.
1712 </para></listitem>
1713 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
1714 Checks for ELF binaries that contain relocations in their
1715 <filename>.text</filename> sections, which can result in a
1716 performance impact at runtime.
1717 See the explanation for the
1718 <link linkend='qa-issue-textrel'><filename>ELF binary</filename></link>
1719 message for more information regarding runtime performance issues.
1720 </para></listitem>
1721<!--
1722This check was removed for YP 2.3 release
1723
1724 <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
1725 Reports when a binary installed in
1726 <filename>${base_libdir}</filename>,
1727 <filename>${base_bindir}</filename>, or
1728 <filename>${base_sbindir}</filename>, depends on another
1729 binary installed under <filename>${exec_prefix}</filename>.
1730 This dependency is a concern if you want the system to remain
1731 basically operable if <filename>/usr</filename> is mounted
1732 separately and is not mounted.
1733 <note>
1734 Defaults for binaries installed in
1735 <filename>${base_libdir}</filename>,
1736 <filename>${base_bindir}</filename>, and
1737 <filename>${base_sbindir}</filename> are
1738 <filename>/lib</filename>, <filename>/bin</filename>, and
1739 <filename>/sbin</filename>, respectively.
1740 The default for a binary installed
1741 under <filename>${exec_prefix}</filename> is
1742 <filename>/usr</filename>.
1743 </note>
1744 </para></listitem>
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>
1752 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
1753 Checks for dynamic library load paths (rpaths) in the binaries that
1754 by default on a standard system are searched by the linker (e.g.
1755 <filename>/lib</filename> and <filename>/usr/lib</filename>).
1756 While these paths will not cause any breakage, they do waste space and
1757 are unnecessary.</para></listitem>
1758 <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
1759 Reports when variables fundamental to packaging (i.e.
1760 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
1761 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
1762 <link linkend='var-D'><filename>D</filename></link>,
1763 <link linkend='var-PN'><filename>PN</filename></link>, and
1764 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
1765 undefined during
1766 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1767 </para></listitem>
1768 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
1769 If Build History is enabled, reports when a package
1770 being written out has a lower version than the previously
1771 written package under the same name.
1772 If you are placing output packages into a feed and
1773 upgrading packages on a target system using that feed, the
1774 version of a package going backwards can result in the target
1775 system not correctly upgrading to the "new" version of the
1776 package.
1777 <note>
1778 If you are not using runtime package management on your
1779 target system, then you do not need to worry about
1780 this situation.
1781 </note>
1782 </para></listitem>
1783 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
1784 Checks that all packages containing Xorg drivers have ABI
1785 dependencies.
1786 The <filename>xserver-xorg</filename> recipe provides driver
1787 ABI names.
1788 All drivers should depend on the ABI versions that they have
1789 been built against.
1790 Driver recipes that include
1791 <filename>xorg-driver-input.inc</filename>
1792 or <filename>xorg-driver-video.inc</filename> will
1793 automatically get these versions.
1794 Consequently, you should only need to explicitly add
1795 dependencies to binary driver recipes.
1796 </para></listitem>
1797 </itemizedlist>
1798 </para>
1799</section>
1800
1801<section id='ref-classes-insserv'>
1802 <title><filename>insserv.bbclass</filename></title>
1803
1804 <para>
1805 The <filename>insserv</filename> class
1806 uses the <filename>insserv</filename> utility to update the order of
1807 symbolic links in <filename>/etc/rc?.d/</filename> within an image
1808 based on dependencies specified by LSB headers in the
1809 <filename>init.d</filename> scripts themselves.
1810 </para>
1811</section>
1812
1813<section id='ref-classes-kernel'>
1814 <title><filename>kernel.bbclass</filename></title>
1815
1816 <para>
1817 The <filename>kernel</filename> class handles building Linux kernels.
1818 The class contains code to build all kernel trees.
1819 All needed headers are staged into the
1820 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
1821 directory to allow out-of-tree module builds using
1822 the
1823 <link linkend='ref-classes-module'><filename>module</filename></link>
1824 class.
1825 </para>
1826
1827 <para>
1828 This means that each built kernel module is packaged separately and
1829 inter-module dependencies are created by parsing the
1830 <filename>modinfo</filename> output.
1831 If all modules are required, then installing the
1832 <filename>kernel-modules</filename> package installs all packages with
1833 modules and various other kernel packages such as
1834 <filename>kernel-vmlinux</filename>.
1835 </para>
1836
1837 <para>
1838 The <filename>kernel</filename> class contains logic that allows
1839 you to embed an initial RAM filesystem (initramfs) image when
1840 you build the kernel image.
1841 For information on how to build an initramfs, see the
1842 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
1843 section in the Yocto Project Development Tasks Manual.
1844 </para>
1845
1846 <para>
1847 Various other classes are used by the <filename>kernel</filename>
1848 and <filename>module</filename> classes internally including the
1849 <link linkend='ref-classes-kernel-arch'><filename>kernel-arch</filename></link>,
1850 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>,
1851 and
1852 <link linkend='ref-classes-linux-kernel-base'><filename>linux-kernel-base</filename></link>
1853 classes.
1854 </para>
1855</section>
1856
1857<section id='ref-classes-kernel-arch'>
1858 <title><filename>kernel-arch.bbclass</filename></title>
1859
1860 <para>
1861 The <filename>kernel-arch</filename> class
1862 sets the <filename>ARCH</filename> environment variable for Linux
1863 kernel compilation (including modules).
1864 </para>
1865</section>
1866
1867<section id='ref-classes-kernel-devicetree'>
1868 <title><filename>kernel-devicetree.bbclass</filename></title>
1869
1870 <para>
1871 The <filename>kernel-devicetree</filename> class, which is inherited by
1872 the
1873 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
1874 class, supports device tree generation.
1875 </para>
1876</section>
1877
1878<section id='ref-classes-kernel-fitimage'>
1879 <title><filename>kernel-fitimage.bbclass</filename></title>
1880
1881 <para>
1882 The <filename>kernel-fitimage</filename> class provides support to
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.
1957 </para>
1958
1959</section>
1960
1961<section id='ref-classes-kernel-grub'>
1962 <title><filename>kernel-grub.bbclass</filename></title>
1963
1964 <para>
1965 The <filename>kernel-grub</filename> class updates the boot area and
1966 the boot menu with the kernel as the priority boot mechanism while
1967 installing a RPM to update the kernel on a deployed target.
1968 </para>
1969</section>
1970
1971<section id='ref-classes-kernel-module-split'>
1972 <title><filename>kernel-module-split.bbclass</filename></title>
1973
1974 <para>
1975 The <filename>kernel-module-split</filename> class
1976 provides common functionality for splitting Linux kernel modules into
1977 separate packages.
1978 </para>
1979</section>
1980
1981<section id='ref-classes-kernel-uboot'>
1982 <title><filename>kernel-uboot.bbclass</filename></title>
1983
1984 <para>
1985 The <filename>kernel-uboot</filename> class provides support for
1986 building from vmlinux-style kernel sources.
1987 </para>
1988</section>
1989
1990<section id='ref-classes-kernel-uimage'>
1991 <title><filename>kernel-uimage.bbclass</filename></title>
1992
1993 <para>
1994 The <filename>kernel-uimage</filename> class provides support to
1995 pack uImage.
1996 </para>
1997</section>
1998
1999<section id='ref-classes-kernel-yocto'>
2000 <title><filename>kernel-yocto.bbclass</filename></title>
2001
2002 <para>
2003 The <filename>kernel-yocto</filename> class
2004 provides common functionality for building from linux-yocto style
2005 kernel source repositories.
2006 </para>
2007</section>
2008
2009<section id='ref-classes-kernelsrc'>
2010 <title><filename>kernelsrc.bbclass</filename></title>
2011
2012 <para>
2013 The <filename>kernelsrc</filename> class sets the Linux kernel
2014 source and version.
2015 </para>
2016</section>
2017
2018<section id='ref-classes-lib_package'>
2019 <title><filename>lib_package.bbclass</filename></title>
2020
2021 <para>
2022 The <filename>lib_package</filename> class
2023 supports recipes that build libraries and produce executable
2024 binaries, where those binaries should not be installed by default
2025 along with the library.
2026 Instead, the binaries are added to a separate
2027 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-bin</filename>
2028 package to make their installation optional.
2029 </para>
2030</section>
2031
2032<section id='ref-classes-libc*'>
2033 <title><filename>libc*.bbclass</filename></title>
2034
2035 <para>
2036 The <filename>libc*</filename> classes support recipes that build
2037 packages with <filename>libc</filename>:
2038 <itemizedlist>
2039 <listitem><para>The <filename>libc-common</filename> class
2040 provides common support for building with
2041 <filename>libc</filename>.
2042 </para></listitem>
2043 <listitem><para>The <filename>libc-package</filename> class
2044 supports packaging up <filename>glibc</filename> and
2045 <filename>eglibc</filename>.
2046 </para></listitem>
2047 </itemizedlist>
2048 </para>
2049</section>
2050
2051<section id='ref-classes-license'>
2052 <title><filename>license.bbclass</filename></title>
2053
2054 <para>
2055 The <filename>license</filename> class provides license
2056 manifest creation and license exclusion.
2057 This class is enabled by default using the default value for the
2058 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
2059 variable.
2060 </para>
2061</section>
2062
2063<section id='ref-classes-linux-kernel-base'>
2064 <title><filename>linux-kernel-base.bbclass</filename></title>
2065
2066 <para>
2067 The <filename>linux-kernel-base</filename> class
2068 provides common functionality for recipes that build out of the Linux
2069 kernel source tree.
2070 These builds goes beyond the kernel itself.
2071 For example, the Perf recipe also inherits this class.
2072 </para>
2073</section>
2074
2075<section id='ref-classes-linuxloader'>
2076 <title><filename>linuxloader.bbclass</filename></title>
2077
2078 <para>
2079 Provides the function <filename>linuxloader()</filename>, which gives
2080 the value of the dynamic loader/linker provided on the platform.
2081 This value is used by a number of other classes.
2082 </para>
2083</section>
2084
2085<section id='ref-classes-logging'>
2086 <title><filename>logging.bbclass</filename></title>
2087
2088 <para>
2089 The <filename>logging</filename> class provides the standard
2090 shell functions used to log messages for various BitBake severity levels
2091 (i.e. <filename>bbplain</filename>, <filename>bbnote</filename>,
2092 <filename>bbwarn</filename>, <filename>bberror</filename>,
2093 <filename>bbfatal</filename>, and <filename>bbdebug</filename>).
2094 </para>
2095
2096 <para>
2097 This class is enabled by default since it is inherited by
2098 the <filename>base</filename> class.
2099 </para>
2100</section>
2101
2102<section id='ref-classes-meta'>
2103 <title><filename>meta.bbclass</filename></title>
2104
2105 <para>
2106 The <filename>meta</filename> class is inherited by recipes
2107 that do not build any output packages themselves, but act as a "meta"
2108 target for building other recipes.
2109 </para>
2110</section>
2111
2112<section id='ref-classes-metadata_scm'>
2113 <title><filename>metadata_scm.bbclass</filename></title>
2114
2115 <para>
2116 The <filename>metadata_scm</filename> class provides functionality for
2117 querying the branch and revision of a Source Code Manager (SCM)
2118 repository.
2119 </para>
2120
2121 <para>
2122 The <link linkend='ref-classes-base'><filename>base</filename></link>
2123 class uses this class to print the revisions of each layer before
2124 starting every build.
2125 The <filename>metadata_scm</filename> class is enabled by default
2126 because it is inherited by the <filename>base</filename> class.
2127 </para>
2128</section>
2129
2130<section id='ref-classes-migrate_localcount'>
2131 <title><filename>migrate_localcount.bbclass</filename></title>
2132
2133 <para>
2134 The <filename>migrate_localcount</filename> class verifies a recipe's
2135 localcount data and increments it appropriately.
2136 </para>
2137</section>
2138
2139<section id='ref-classes-mime'>
2140 <title><filename>mime.bbclass</filename></title>
2141
2142 <para>
2143 The <filename>mime</filename> class generates the proper
2144 post-install and post-remove (postinst/postrm) scriptlets for packages
2145 that install MIME type files.
2146 These scriptlets call <filename>update-mime-database</filename> to add
2147 the MIME types to the shared database.
2148 </para>
2149</section>
2150
2151<section id='ref-classes-mirrors'>
2152 <title><filename>mirrors.bbclass</filename></title>
2153
2154 <para>
2155 The <filename>mirrors</filename> class sets up some standard
2156 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> entries
2157 for source code mirrors.
2158 These mirrors provide a fall-back path in case the upstream source
2159 specified in
2160 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
2161 within recipes is unavailable.
2162 </para>
2163
2164 <para>
2165 This class is enabled by default since it is inherited by the
2166 <link linkend='ref-classes-base'><filename>base</filename></link> class.
2167 </para>
2168</section>
2169
2170<section id='ref-classes-module'>
2171 <title><filename>module.bbclass</filename></title>
2172
2173 <para>
2174 The <filename>module</filename> class provides support for building
2175 out-of-tree Linux kernel modules.
2176 The class inherits the
2177 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>
2178 and
2179 <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link>
2180 classes, and implements the
2181 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
2182 and
2183 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2184 tasks.
2185 The class provides everything needed to build and package a kernel
2186 module.
2187 </para>
2188
2189 <para>
2190 For general information on out-of-tree Linux kernel modules, see the
2191 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
2192 section in the Yocto Project Linux Kernel Development Manual.
2193 </para>
2194</section>
2195
2196<section id='ref-classes-module-base'>
2197 <title><filename>module-base.bbclass</filename></title>
2198
2199 <para>
2200 The <filename>module-base</filename> class provides the base
2201 functionality for building Linux kernel modules.
2202 Typically, a recipe that builds software that includes one or
2203 more kernel modules and has its own means of building
2204 the module inherits this class as opposed to inheriting the
2205 <link linkend='ref-classes-module'><filename>module</filename></link>
2206 class.
2207 </para>
2208</section>
2209
2210<section id='ref-classes-multilib*'>
2211 <title><filename>multilib*.bbclass</filename></title>
2212
2213 <para>
2214 The <filename>multilib*</filename> classes provide support
2215 for building libraries with different target optimizations or target
2216 architectures and installing them side-by-side in the same image.
2217 </para>
2218
2219 <para>
2220 For more information on using the Multilib feature, see the
2221 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
2222 section in the Yocto Project Development Tasks Manual.
2223 </para>
2224</section>
2225
2226<section id='ref-classes-native'>
2227 <title><filename>native.bbclass</filename></title>
2228
2229 <para>
2230 The <filename>native</filename> class provides common
2231 functionality for recipes that build tools to run on the
2232 <link linkend='hardware-build-system-term'>build host</link>
2233 (i.e. tools that use the compiler or other tools from the
2234 build host).
2235 </para>
2236
2237 <para>
2238 You can create a recipe that builds tools that run natively on the
2239 host a couple different ways:
2240 <itemizedlist>
2241 <listitem><para>
2242 Create a
2243 <replaceable>myrecipe</replaceable><filename>-native.bb</filename>
2244 recipe that inherits the <filename>native</filename> class.
2245 If you use this method, you must order the inherit statement
2246 in the recipe after all other inherit statements so that the
2247 <filename>native</filename> class is inherited last.
2248 <note><title>Warning</title>
2249 When creating a recipe this way, the recipe name must
2250 follow this naming convention:
2251 <literallayout class='monospaced'>
2252 <replaceable>myrecipe</replaceable>-native.bb
2253 </literallayout>
2254 Not using this naming convention can lead to subtle
2255 problems caused by existing code that depends on that
2256 naming convention.
2257 </note>
2258 </para></listitem>
2259 <listitem><para>
2260 Create or modify a target recipe that contains the following:
2261 <literallayout class='monospaced'>
2262 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native"
2263 </literallayout>
2264 Inside the recipe, use <filename>_class-native</filename> and
2265 <filename>_class-target</filename> overrides to specify any
2266 functionality specific to the respective native or target
2267 case.
2268 </para></listitem>
2269 </itemizedlist>
2270 </para>
2271
2272 <para>
2273 Although applied differently, the <filename>native</filename> class is
2274 used with both methods.
2275 The advantage of the second method is that you do not need to have two
2276 separate recipes (assuming you need both) for native and target.
2277 All common parts of the recipe are automatically shared.
2278 </para>
2279</section>
2280
2281<section id='ref-classes-nativesdk'>
2282 <title><filename>nativesdk.bbclass</filename></title>
2283
2284 <para>
2285 The <filename>nativesdk</filename> class provides common
2286 functionality for recipes that wish to build tools to run as part of
2287 an SDK (i.e. tools that run on
2288 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
2289 </para>
2290
2291 <para>
2292 You can create a recipe that builds tools that run on the SDK machine
2293 a couple different ways:
2294 <itemizedlist>
2295 <listitem><para>Create a
2296 <filename>nativesdk-</filename><replaceable>myrecipe</replaceable><filename>.bb</filename>
2297 recipe that inherits the <filename>nativesdk</filename> class.
2298 If you use this method, you must order the inherit statement
2299 in the recipe after all other inherit statements so that the
2300 <filename>nativesdk</filename> class is inherited last.
2301 </para></listitem>
2302 <listitem><para>Create a <filename>nativesdk</filename> variant
2303 of any recipe by adding the following:
2304 <literallayout class='monospaced'>
2305 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "nativesdk"
2306 </literallayout>
2307 Inside the recipe, use <filename>_class-nativesdk</filename> and
2308 <filename>_class-target</filename> overrides to specify any
2309 functionality specific to the respective SDK machine or target
2310 case.</para></listitem>
2311 </itemizedlist>
2312 <note><title>Warning</title>
2313 When creating a recipe, you must follow this naming convention:
2314 <literallayout class='monospaced'>
2315 nativesdk-<replaceable>myrecipe</replaceable>.bb
2316 </literallayout>
2317 Not doing so can lead to subtle problems because code exists
2318 that depends on the naming convention.
2319 </note>
2320 </para>
2321
2322 <para>
2323 Although applied differently, the <filename>nativesdk</filename> class
2324 is used with both methods.
2325 The advantage of the second method is that you do not need to have two
2326 separate recipes (assuming you need both) for the SDK machine and the
2327 target.
2328 All common parts of the recipe are automatically shared.
2329 </para>
2330</section>
2331
2332<section id='ref-classes-nopackages'>
2333 <title><filename>nopackages.bbclass</filename></title>
2334
2335 <para>
2336 Disables packaging tasks for those recipes and classes where
2337 packaging is not needed.
2338 </para>
2339</section>
2340
2341<section id='ref-classes-npm'>
2342 <title><filename>npm.bbclass</filename></title>
2343
2344 <para>
2345 Provides support for building Node.js software fetched using the
2346 <ulink url='https://en.wikipedia.org/wiki/Npm_(software)'>node package manager (NPM)</ulink>.
2347 <note>
2348 Currently, recipes inheriting this class must use the
2349 <filename>npm://</filename> fetcher to have dependencies fetched
2350 and packaged automatically.
2351 </note>
2352 For information on how to create NPM packages, see the
2353 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-node-package-manager-npm-packages'>Creating Node Package Manager (NPM) Packages</ulink>"
2354 section in the Yocto Project Development Tasks Manual.
2355 </para>
2356</section>
2357
2358<section id='ref-classes-oelint'>
2359 <title><filename>oelint.bbclass</filename></title>
2360
2361 <para>
2362 The <filename>oelint</filename> class is an
2363 obsolete lint checking tool that exists in
2364 <filename>meta/classes</filename> in the
2365 <link linkend='source-directory'>Source Directory</link>.
2366 </para>
2367
2368 <para>
2369 A number of classes exist that could be generally useful in
2370 OE-Core but are never actually used within OE-Core itself.
2371 The <filename>oelint</filename> class is one such example.
2372 However, being aware of this class can reduce the proliferation of
2373 different versions of similar classes across multiple layers.
2374 </para>
2375</section>
2376
2377<section id='ref-classes-own-mirrors'>
2378 <title><filename>own-mirrors.bbclass</filename></title>
2379
2380 <para>
2381 The <filename>own-mirrors</filename> class makes it
2382 easier to set up your own
2383 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
2384 from which to first fetch source before attempting to fetch it from the
2385 upstream specified in
2386 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
2387 within each recipe.
2388 </para>
2389
2390 <para>
2391 To use this class, inherit it globally and specify
2392 <link linkend='var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></link>.
2393 Here is an example:
2394 <literallayout class='monospaced'>
2395 INHERIT += "own-mirrors"
2396 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
2397 </literallayout>
2398 You can specify only a single URL in
2399 <filename>SOURCE_MIRROR_URL</filename>.
2400 </para>
2401</section>
2402
2403<section id='ref-classes-package'>
2404 <title><filename>package.bbclass</filename></title>
2405
2406 <para>
2407 The <filename>package</filename> class supports generating
2408 packages from a build's output.
2409 The core generic functionality is in
2410 <filename>package.bbclass</filename>.
2411 The code specific to particular package types resides in these
2412 package-specific classes:
2413 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
2414 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
2415 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
2416 and
2417 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
2418 <note><title>Warning</title>
2419 The <filename>package_tar</filename> class is broken and not
2420 supported.
2421 It is recommended that you do not use this class.
2422 </note>
2423 </para>
2424
2425 <para>
2426 You can control the list of resulting package formats by using the
2427 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
2428 variable defined in your <filename>conf/local.conf</filename>
2429 configuration file, which is located in the
2430 <link linkend='build-directory'>Build Directory</link>.
2431 When defining the variable, you can specify one or more package types.
2432 Since images are generated from packages, a packaging class is
2433 needed to enable image generation.
2434 The first class listed in this variable is used for image generation.
2435 </para>
2436
2437 <para>
2438 If you take the optional step to set up a repository (package feed)
2439 on the development host that can be used by DNF, you can
2440 install packages from the feed while you are running the image
2441 on the target (i.e. runtime installation of packages).
2442 For more information, see the
2443 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
2444 section in the Yocto Project Development Tasks Manual.
2445 </para>
2446
2447 <para>
2448 The package-specific class you choose can affect build-time performance
2449 and has space ramifications.
2450 In general, building a package with IPK takes about thirty percent less
2451 time as compared to using RPM to build the same or similar package.
2452 This comparison takes into account a complete build of the package with
2453 all dependencies previously built.
2454 The reason for this discrepancy is because the RPM package manager
2455 creates and processes more
2456 <link linkend='metadata'>Metadata</link> than the
2457 IPK package manager.
2458 Consequently, you might consider setting
2459 <filename>PACKAGE_CLASSES</filename> to "package_ipk" if you are
2460 building smaller systems.
2461 </para>
2462
2463 <para>
2464 Before making your package manager decision, however, you should
2465 consider some further things about using RPM:
2466 <itemizedlist>
2467 <listitem><para>
2468 RPM starts to provide more abilities than IPK due to
2469 the fact that it processes more Metadata.
2470 For example, this information includes individual file types,
2471 file checksum generation and evaluation on install, sparse file
2472 support, conflict detection and resolution for Multilib systems,
2473 ACID style upgrade, and repackaging abilities for rollbacks.
2474 </para></listitem>
2475 <listitem><para>
2476 For smaller systems, the extra space used for the Berkeley
2477 Database and the amount of metadata when using RPM can affect
2478 your ability to perform on-device upgrades.
2479 </para></listitem>
2480 </itemizedlist>
2481 </para>
2482
2483 <para>
2484 You can find additional information on the effects of the package
2485 class at these two Yocto Project mailing list links:
2486 <itemizedlist>
2487 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
2488 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
2489 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
2490 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
2491 </itemizedlist>
2492 </para>
2493</section>
2494
2495<section id='ref-classes-package_deb'>
2496 <title><filename>package_deb.bbclass</filename></title>
2497
2498 <para>
2499 The <filename>package_deb</filename> class
2500 provides support for creating packages that use the Debian
2501 (i.e. <filename>.deb</filename>) file format.
2502 The class ensures the packages are written out in a
2503 <filename>.deb</filename> file format to the
2504 <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
2505 directory.
2506 </para>
2507
2508 <para>
2509 This class inherits the
2510 <link linkend='ref-classes-package'><filename>package</filename></link>
2511 class and is enabled through the
2512 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2513 variable in the <filename>local.conf</filename> file.
2514 </para>
2515</section>
2516
2517<section id='ref-classes-package_ipk'>
2518 <title><filename>package_ipk.bbclass</filename></title>
2519
2520 <para>
2521 The <filename>package_ipk</filename> class
2522 provides support for creating packages that use the IPK
2523 (i.e. <filename>.ipk</filename>) file format.
2524 The class ensures the packages are written out in a
2525 <filename>.ipk</filename> file format to the
2526 <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
2527 directory.
2528 </para>
2529
2530 <para>
2531 This class inherits the
2532 <link linkend='ref-classes-package'><filename>package</filename></link>
2533 class and is enabled through the
2534 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2535 variable in the <filename>local.conf</filename> file.
2536 </para>
2537</section>
2538
2539<section id='ref-classes-package_rpm'>
2540 <title><filename>package_rpm.bbclass</filename></title>
2541
2542 <para>
2543 The <filename>package_rpm</filename> class
2544 provides support for creating packages that use the RPM
2545 (i.e. <filename>.rpm</filename>) file format.
2546 The class ensures the packages are written out in a
2547 <filename>.rpm</filename> file format to the
2548 <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
2549 directory.
2550 </para>
2551
2552 <para>
2553 This class inherits the
2554 <link linkend='ref-classes-package'><filename>package</filename></link>
2555 class and is enabled through the
2556 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2557 variable in the <filename>local.conf</filename> file.
2558 </para>
2559</section>
2560
2561<section id='ref-classes-package_tar'>
2562 <title><filename>package_tar.bbclass</filename></title>
2563
2564 <para>
2565 The <filename>package_tar</filename> class
2566 provides support for creating tarballs.
2567 The class ensures the packages are written out in a
2568 tarball format to the
2569 <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
2570 directory.
2571 </para>
2572
2573 <para>
2574 This class inherits the
2575 <link linkend='ref-classes-package'><filename>package</filename></link>
2576 class and is enabled through the
2577 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2578 variable in the <filename>local.conf</filename> file.
2579 <note>
2580 You cannot specify the <filename>package_tar</filename> class
2581 first using the <filename>PACKAGE_CLASSES</filename> variable.
2582 You must use <filename>.deb</filename>,
2583 <filename>.ipk</filename>, or <filename>.rpm</filename> file
2584 formats for your image or SDK.
2585 </note>
2586 </para>
2587</section>
2588
2589<section id='ref-classes-packagedata'>
2590 <title><filename>packagedata.bbclass</filename></title>
2591
2592 <para>
2593 The <filename>packagedata</filename> class provides
2594 common functionality for reading <filename>pkgdata</filename> files
2595 found in
2596 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
2597 These files contain information about each output package produced by
2598 the OpenEmbedded build system.
2599 </para>
2600
2601 <para>
2602 This class is enabled by default because it is inherited by the
2603 <link linkend='ref-classes-package'><filename>package</filename></link>
2604 class.
2605 </para>
2606</section>
2607
2608<section id='ref-classes-packagegroup'>
2609 <title><filename>packagegroup.bbclass</filename></title>
2610
2611 <para>
2612 The <filename>packagegroup</filename> class sets default values
2613 appropriate for package group recipes (e.g.
2614 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
2615 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
2616 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
2617 and so forth).
2618 It is highly recommended that all package group recipes inherit this class.
2619 </para>
2620
2621 <para>
2622 For information on how to use this class, see the
2623 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
2624 section in the Yocto Project Development Tasks Manual.
2625 </para>
2626
2627 <para>
2628 Previously, this class was called the <filename>task</filename> class.
2629 </para>
2630</section>
2631
2632<section id='ref-classes-patch'>
2633 <title><filename>patch.bbclass</filename></title>
2634
2635 <para>
2636 The <filename>patch</filename> class provides all functionality for
2637 applying patches during the
2638 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
2639 task.
2640 </para>
2641
2642 <para>
2643 This class is enabled by default because it is inherited by the
2644 <link linkend='ref-classes-base'><filename>base</filename></link>
2645 class.
2646 </para>
2647</section>
2648
2649<section id='ref-classes-perlnative'>
2650 <title><filename>perlnative.bbclass</filename></title>
2651
2652 <para>
2653 When inherited by a recipe, the <filename>perlnative</filename> class
2654 supports using the native version of Perl built by the build system
2655 rather than using the version provided by the build host.
2656 </para>
2657</section>
2658
2659<section id='ref-classes-pixbufcache'>
2660 <title><filename>pixbufcache.bbclass</filename></title>
2661
2662 <para>
2663 The <filename>pixbufcache</filename> class generates the proper
2664 post-install and post-remove (postinst/postrm) scriptlets for packages
2665 that install pixbuf loaders, which are used with
2666 <filename>gdk-pixbuf</filename>.
2667 These scriptlets call <filename>update_pixbuf_cache</filename>
2668 to add the pixbuf loaders to the cache.
2669 Since the cache files are architecture-specific,
2670 <filename>update_pixbuf_cache</filename> is run using QEMU if the
2671 postinst scriptlets need to be run on the build host during image
2672 creation.
2673 </para>
2674
2675 <para>
2676 If the pixbuf loaders being installed are in packages other
2677 than the recipe's main package, set
2678 <link linkend='var-PIXBUF_PACKAGES'><filename>PIXBUF_PACKAGES</filename></link>
2679 to specify the packages containing the loaders.
2680 </para>
2681</section>
2682
2683<section id='ref-classes-pkgconfig'>
2684 <title><filename>pkgconfig.bbclass</filename></title>
2685
2686 <para>
2687 The <filename>pkgconfig</filename> class provides a standard way to get
2688 header and library information by using <filename>pkg-config</filename>.
2689 This class aims to smooth integration of
2690 <filename>pkg-config</filename> into libraries that use it.
2691 </para>
2692
2693 <para>
2694 During staging, BitBake installs <filename>pkg-config</filename>
2695 data into the <filename>sysroots/</filename> directory.
2696 By making use of sysroot functionality within
2697 <filename>pkg-config</filename>, the <filename>pkgconfig</filename>
2698 class no longer has to manipulate the files.
2699 </para>
2700</section>
2701
2702<section id='ref-classes-populate-sdk'>
2703 <title><filename>populate_sdk.bbclass</filename></title>
2704
2705 <para>
2706 The <filename>populate_sdk</filename> class provides support for
2707 SDK-only recipes.
2708 For information on advantages gained when building a cross-development
2709 toolchain using the
2710 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2711 task, see the
2712 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
2713 section in the Yocto Project Application Development and the
2714 Extensible Software Development Kit (eSDK) manual.
2715 </para>
2716</section>
2717
2718<section id='ref-classes-populate-sdk-*'>
2719 <title><filename>populate_sdk_*.bbclass</filename></title>
2720
2721 <para>
2722 The <filename>populate_sdk_*</filename> classes support SDK creation
2723 and consist of the following classes:
2724 <itemizedlist>
2725 <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis>
2726 The base class supporting SDK creation under all package
2727 managers (i.e. DEB, RPM, and opkg).</para></listitem>
2728 <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis>
2729 Supports creation of the SDK given the Debian package manager.
2730 </para></listitem>
2731 <listitem><para><emphasis><filename>populate_sdk_rpm</filename>:</emphasis>
2732 Supports creation of the SDK given the RPM package manager.
2733 </para></listitem>
2734 <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis>
2735 Supports creation of the SDK given the opkg (IPK format)
2736 package manager.
2737 </para></listitem>
2738 <listitem><para><emphasis><filename>populate_sdk_ext</filename>:</emphasis>
2739 Supports extensible SDK creation under all package managers.
2740 </para></listitem>
2741 </itemizedlist>
2742 </para>
2743
2744 <para>
2745 The <filename>populate_sdk_base</filename> class inherits the
2746 appropriate <filename>populate_sdk_*</filename> (i.e.
2747 <filename>deb</filename>, <filename>rpm</filename>, and
2748 <filename>ipk</filename>) based on
2749 <link linkend='var-IMAGE_PKGTYPE'><filename>IMAGE_PKGTYPE</filename></link>.
2750 </para>
2751
2752 <para>
2753 The base class ensures all source and destination directories are
2754 established and then populates the SDK.
2755 After populating the SDK, the <filename>populate_sdk_base</filename>
2756 class constructs two sysroots:
2757 <filename>${</filename><link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>}-nativesdk</filename>,
2758 which contains the cross-compiler and associated tooling, and the
2759 target, which contains a target root filesystem that is configured for
2760 the SDK usage.
2761 These two images reside in
2762 <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>,
2763 which consists of the following:
2764 <literallayout class='monospaced'>
2765 ${SDK_OUTPUT}/${SDK_ARCH}<replaceable>-nativesdk-pkgs</replaceable>
2766 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/<replaceable>target-pkgs</replaceable>
2767 </literallayout>
2768 </para>
2769
2770 <para>
2771 Finally, the base populate SDK class creates the toolchain
2772 environment setup script, the tarball of the SDK, and the installer.
2773 </para>
2774
2775 <para>
2776 The respective <filename>populate_sdk_deb</filename>,
2777 <filename>populate_sdk_rpm</filename>, and
2778 <filename>populate_sdk_ipk</filename> classes each support the
2779 specific type of SDK.
2780 These classes are inherited by and used with the
2781 <filename>populate_sdk_base</filename> class.
2782 </para>
2783
2784 <para>
2785 For more information on the cross-development toolchain
2786 generation, see the
2787 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
2788 section in the Yocto Project Overview and Concepts Manual.
2789 For information on advantages gained when building a
2790 cross-development toolchain using the
2791 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2792 task, see the
2793 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
2794 section in the Yocto Project Application Development and the
2795 Extensible Software Development Kit (eSDK) manual.
2796 </para>
2797</section>
2798
2799<section id='ref-classes-prexport'>
2800 <title><filename>prexport.bbclass</filename></title>
2801
2802 <para>
2803 The <filename>prexport</filename> class provides functionality for
2804 exporting
2805 <link linkend='var-PR'><filename>PR</filename></link> values.
2806 <note>
2807 This class is not intended to be used directly.
2808 Rather, it is enabled when using
2809 "<filename>bitbake-prserv-tool export</filename>".
2810 </note>
2811 </para>
2812</section>
2813
2814<section id='ref-classes-primport'>
2815 <title><filename>primport.bbclass</filename></title>
2816
2817 <para>
2818 The <filename>primport</filename> class provides functionality for
2819 importing
2820 <link linkend='var-PR'><filename>PR</filename></link> values.
2821 <note>
2822 This class is not intended to be used directly.
2823 Rather, it is enabled when using
2824 "<filename>bitbake-prserv-tool import</filename>".
2825 </note>
2826 </para>
2827</section>
2828
2829<section id='ref-classes-prserv'>
2830 <title><filename>prserv.bbclass</filename></title>
2831
2832 <para>
2833 The <filename>prserv</filename> class provides functionality for
2834 using a
2835 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>
2836 in order to automatically manage the incrementing of the
2837 <link linkend='var-PR'><filename>PR</filename></link> variable for
2838 each recipe.
2839 </para>
2840
2841 <para>
2842 This class is enabled by default because it is inherited by the
2843 <link linkend='ref-classes-package'><filename>package</filename></link>
2844 class.
2845 However, the OpenEmbedded build system will not enable the
2846 functionality of this class unless
2847 <link linkend='var-PRSERV_HOST'><filename>PRSERV_HOST</filename></link>
2848 has been set.
2849 </para>
2850</section>
2851
2852<section id='ref-classes-ptest'>
2853 <title><filename>ptest.bbclass</filename></title>
2854
2855 <para>
2856 The <filename>ptest</filename> class provides functionality for
2857 packaging and installing runtime tests for recipes that build software
2858 that provides these tests.
2859 </para>
2860
2861 <para>
2862 This class is intended to be inherited by individual recipes.
2863 However, the class' functionality is largely disabled unless "ptest"
2864 appears in
2865 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2866 See the
2867 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
2868 section in the Yocto Project Development Tasks Manual for more
2869 information on ptest.
2870 </para>
2871</section>
2872
2873<section id='ref-classes-ptest-gnome'>
2874 <title><filename>ptest-gnome.bbclass</filename></title>
2875
2876 <para>
2877 Enables package tests (ptests) specifically for GNOME packages,
2878 which have tests intended to be executed with
2879 <filename>gnome-desktop-testing</filename>.
2880 </para>
2881
2882 <para>
2883 For information on setting up and running ptests, see the
2884 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
2885 section in the Yocto Project Development Tasks Manual.
2886 </para>
2887</section>
2888
2889<section id='ref-classes-python-dir'>
2890 <title><filename>python-dir.bbclass</filename></title>
2891
2892 <para>
2893 The <filename>python-dir</filename> class provides the base version,
2894 location, and site package location for Python.
2895 </para>
2896</section>
2897
2898<section id='ref-classes-python3native'>
2899 <title><filename>python3native.bbclass</filename></title>
2900
2901 <para>
2902 The <filename>python3native</filename> class supports using the
2903 native version of Python 3 built by the build system rather than
2904 support of the version provided by the build host.
2905 </para>
2906</section>
2907
2908<section id='ref-classes-pythonnative'>
2909 <title><filename>pythonnative.bbclass</filename></title>
2910
2911 <para>
2912 When inherited by a recipe, the <filename>pythonnative</filename> class
2913 supports using the native version of Python built by the build system
2914 rather than using the version provided by the build host.
2915 </para>
2916</section>
2917
2918<section id='ref-classes-qemu'>
2919 <title><filename>qemu.bbclass</filename></title>
2920
2921 <para>
2922 The <filename>qemu</filename> class provides functionality for recipes
2923 that either need QEMU or test for the existence of QEMU.
2924 Typically, this class is used to run programs for a target system on
2925 the build host using QEMU's application emulation mode.
2926 </para>
2927</section>
2928
2929<section id='ref-classes-recipe_sanity'>
2930 <title><filename>recipe_sanity.bbclass</filename></title>
2931
2932 <para>
2933 The <filename>recipe_sanity</filename> class checks for the presence
2934 of any host system recipe prerequisites that might affect the
2935 build (e.g. variables that are set or software that is present).
2936 </para>
2937</section>
2938
2939<section id='ref-classes-relocatable'>
2940 <title><filename>relocatable.bbclass</filename></title>
2941
2942 <para>
2943 The <filename>relocatable</filename> class enables relocation of
2944 binaries when they are installed into the sysroot.
2945 </para>
2946
2947 <para>
2948 This class makes use of the
2949 <link linkend='ref-classes-chrpath'><filename>chrpath</filename></link>
2950 class and is used by both the
2951 <link linkend='ref-classes-cross'><filename>cross</filename></link>
2952 and
2953 <link linkend='ref-classes-native'><filename>native</filename></link>
2954 classes.
2955 </para>
2956</section>
2957
2958<section id='ref-classes-remove-libtool'>
2959 <title><filename>remove-libtool.bbclass</filename></title>
2960
2961 <para>
2962 The <filename>remove-libtool</filename> class adds a post function
2963 to the
2964 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2965 task to remove all <filename>.la</filename> files installed by
2966 <filename>libtool</filename>.
2967 Removing these files results in them being absent from both the
2968 sysroot and target packages.
2969 </para>
2970
2971 <para>
2972 If a recipe needs the <filename>.la</filename> files to be installed,
2973 then the recipe can override the removal by setting
2974 <filename>REMOVE_LIBTOOL_LA</filename> to "0" as follows:
2975 <literallayout class='monospaced'>
2976 REMOVE_LIBTOOL_LA = "0"
2977 </literallayout>
2978 <note>
2979 The <filename>remove-libtool</filename> class is not enabled by
2980 default.
2981 </note>
2982 </para>
2983</section>
2984
2985<section id='ref-classes-report-error'>
2986 <title><filename>report-error.bbclass</filename></title>
2987
2988 <para>
2989 The <filename>report-error</filename> class supports enabling the
2990 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
2991 which allows you to submit build error information to a central
2992 database.
2993 </para>
2994
2995 <para>
2996 The class collects debug information for recipe, recipe version, task,
2997 machine, distro, build system, target system, host distro, branch,
2998 commit, and log.
2999 From the information, report files using a JSON format are created and
3000 stored in
3001 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
3002 </para>
3003</section>
3004
3005<section id='ref-classes-rm-work'>
3006 <title><filename>rm_work.bbclass</filename></title>
3007
3008 <para>
3009 The <filename>rm_work</filename> class supports deletion of temporary
3010 workspace, which can ease your hard drive demands during builds.
3011 </para>
3012
3013 <para>
3014 The OpenEmbedded build system can use a substantial amount of disk
3015 space during the build process.
3016 A portion of this space is the work files under the
3017 <filename>${TMPDIR}/work</filename> directory for each recipe.
3018 Once the build system generates the packages for a recipe, the work
3019 files for that recipe are no longer needed.
3020 However, by default, the build system preserves these files
3021 for inspection and possible debugging purposes.
3022 If you would rather have these files deleted to save disk space
3023 as the build progresses, you can enable <filename>rm_work</filename>
3024 by adding the following to your <filename>local.conf</filename> file,
3025 which is found in the
3026 <link linkend='build-directory'>Build Directory</link>.
3027 <literallayout class='monospaced'>
3028 INHERIT += "rm_work"
3029 </literallayout>
3030 If you are modifying and building source code out of the work directory
3031 for a recipe, enabling <filename>rm_work</filename> will potentially
3032 result in your changes to the source being lost.
3033 To exclude some recipes from having their work directories deleted by
3034 <filename>rm_work</filename>, you can add the names of the recipe or
3035 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
3036 variable, which can also be set in your <filename>local.conf</filename>
3037 file.
3038 Here is an example:
3039 <literallayout class='monospaced'>
3040 RM_WORK_EXCLUDE += "busybox glibc"
3041 </literallayout>
3042 </para>
3043</section>
3044
3045<section id='ref-classes-rootfs*'>
3046 <title><filename>rootfs*.bbclass</filename></title>
3047
3048 <para>
3049 The <filename>rootfs*</filename> classes support creating
3050 the root filesystem for an image and consist of the following classes:
3051 <itemizedlist>
3052 <listitem><para>
3053 The <filename>rootfs-postcommands</filename> class, which
3054 defines filesystem post-processing functions for image recipes.
3055 </para></listitem>
3056 <listitem><para>
3057 The <filename>rootfs_deb</filename> class, which supports
3058 creation of root filesystems for images built using
3059 <filename>.deb</filename> packages.</para></listitem>
3060 <listitem><para>
3061 The <filename>rootfs_rpm</filename> class, which supports
3062 creation of root filesystems for images built using
3063 <filename>.rpm</filename> packages.</para></listitem>
3064 <listitem><para>
3065 The <filename>rootfs_ipk</filename> class, which supports
3066 creation of root filesystems for images built using
3067 <filename>.ipk</filename> packages.</para></listitem>
3068 <listitem><para>
3069 The <filename>rootfsdebugfiles</filename> class, which installs
3070 additional files found on the build host directly into the
3071 root filesystem.
3072 </para></listitem>
3073 </itemizedlist>
3074 </para>
3075
3076 <para>
3077 The root filesystem is created from packages using one of the
3078 <filename>rootfs*.bbclass</filename> files as determined by the
3079 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3080 variable.
3081 </para>
3082
3083 <para>
3084 For information on how root filesystem images are created, see the
3085 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
3086 section in the Yocto Project Overview and Concepts Manual.
3087 </para>
3088</section>
3089
3090<section id='ref-classes-sanity'>
3091 <title><filename>sanity.bbclass</filename></title>
3092
3093 <para>
3094 The <filename>sanity</filename> class checks to see if prerequisite
3095 software is present on the host system so that users can be notified
3096 of potential problems that might affect their build.
3097 The class also performs basic user configuration checks from
3098 the <filename>local.conf</filename> configuration file to
3099 prevent common mistakes that cause build failures.
3100 Distribution policy usually determines whether to include this class.
3101 </para>
3102</section>
3103
3104<section id='ref-classes-scons'>
3105 <title><filename>scons.bbclass</filename></title>
3106
3107 <para>
3108 The <filename>scons</filename> class supports recipes that need to
3109 build software that uses the SCons build system.
3110 You can use the
3111 <link linkend='var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></link>
3112 variable to specify additional configuration options you want to pass
3113 SCons command line.
3114 </para>
3115</section>
3116
3117<section id='ref-classes-sdl'>
3118 <title><filename>sdl.bbclass</filename></title>
3119
3120 <para>
3121 The <filename>sdl</filename> class supports recipes that need to build
3122 software that uses the Simple DirectMedia Layer (SDL) library.
3123 </para>
3124</section>
3125
3126<section id='ref-classes-setuptools'>
3127 <title><filename>setuptools.bbclass</filename></title>
3128
3129 <para>
3130 The <filename>setuptools</filename> class supports Python
3131 version 2.x extensions that use build systems based on
3132 <filename>setuptools</filename>.
3133 If your recipe uses these build systems, the recipe needs to
3134 inherit the <filename>setuptools</filename> class.
3135 </para>
3136</section>
3137
3138<section id='ref-classes-setuptools3'>
3139 <title><filename>setuptools3.bbclass</filename></title>
3140
3141 <para>
3142 The <filename>setuptools3</filename> class supports Python
3143 version 3.x extensions that use build systems based on
3144 <filename>setuptools3</filename>.
3145 If your recipe uses these build systems, the recipe needs to
3146 inherit the <filename>setuptools3</filename> class.
3147 </para>
3148</section>
3149
3150<section id='ref-classes-sign_rpm'>
3151 <title><filename>sign_rpm.bbclass</filename></title>
3152
3153 <para>
3154 The <filename>sign_rpm</filename> class supports generating signed
3155 RPM packages.
3156 </para>
3157</section>
3158
3159<section id='ref-classes-sip'>
3160 <title><filename>sip.bbclass</filename></title>
3161
3162 <para>
3163 The <filename>sip</filename> class
3164 supports recipes that build or package SIP-based Python bindings.
3165 </para>
3166</section>
3167
3168<section id='ref-classes-siteconfig'>
3169 <title><filename>siteconfig.bbclass</filename></title>
3170
3171 <para>
3172 The <filename>siteconfig</filename> class
3173 provides functionality for handling site configuration.
3174 The class is used by the
3175 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
3176 class to accelerate the
3177 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3178 task.
3179 </para>
3180</section>
3181
3182<section id='ref-classes-siteinfo'>
3183 <title><filename>siteinfo.bbclass</filename></title>
3184
3185 <para>
3186 The <filename>siteinfo</filename> class provides information about
3187 the targets that might be needed by other classes or recipes.
3188 </para>
3189
3190 <para>
3191 As an example, consider Autotools, which can require tests that must
3192 execute on the target hardware.
3193 Since this is not possible in general when cross compiling, site
3194 information is used to provide cached test results so these tests can
3195 be skipped over but still make the correct values available.
3196 The
3197 <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
3198 contains test results sorted into different categories such as
3199 architecture, endianness, and the <filename>libc</filename> used.
3200 Site information provides a list of files containing data relevant to
3201 the current build in the
3202 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
3203 that Autotools automatically picks up.
3204 </para>
3205
3206 <para>
3207 The class also provides variables like
3208 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
3209 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
3210 that can be used elsewhere in the metadata.
3211 </para>
3212</section>
3213
3214<section id='ref-classes-spdx'>
3215 <title><filename>spdx.bbclass</filename></title>
3216
3217 <para>
3218 The <filename>spdx</filename> class integrates real-time license
3219 scanning, generation of SPDX standard output, and verification
3220 of license information during the build.
3221 <note>
3222 This class is currently at the prototype stage in the 1.6
3223 release.
3224 </note>
3225 </para>
3226</section>
3227
3228<section id='ref-classes-sstate'>
3229 <title><filename>sstate.bbclass</filename></title>
3230
3231 <para>
3232 The <filename>sstate</filename> class provides support for Shared
3233 State (sstate).
3234 By default, the class is enabled through the
3235 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
3236 variable's default value.
3237 </para>
3238
3239 <para>
3240 For more information on sstate, see the
3241 "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>"
3242 section in the Yocto Project Overview and Concepts Manual.
3243 </para>
3244</section>
3245
3246<section id='ref-classes-staging'>
3247 <title><filename>staging.bbclass</filename></title>
3248
3249 <para>
3250 The <filename>staging</filename> class installs files into individual
3251 recipe work directories for sysroots.
3252 The class contains the following key tasks:
3253 <itemizedlist>
3254 <listitem><para>
3255 The
3256 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
3257 task, which is responsible for handing the files that end up
3258 in the recipe sysroots.
3259 </para></listitem>
3260 <listitem><para>
3261 The
3262 <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
3263 task (a "partner" task to the
3264 <filename>populate_sysroot</filename> task), which installs
3265 the files into the individual recipe work directories (i.e.
3266 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
3267 </para></listitem>
3268 </itemizedlist>
3269 </para>
3270
3271 <para>
3272 The code in the <filename>staging</filename> class is complex and
3273 basically works in two stages:
3274 <itemizedlist>
3275 <listitem><para>
3276 <emphasis>Stage One:</emphasis>
3277 The first stage addresses recipes that have files they want
3278 to share with other recipes that have dependencies on the
3279 originating recipe.
3280 Normally these dependencies are installed through the
3281 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
3282 task into
3283 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
3284 The <filename>do_populate_sysroot</filename> task copies
3285 a subset of these files into
3286 <filename>${SYSROOT_DESTDIR}</filename>.
3287 This subset of files is controlled by the
3288 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
3289 <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
3290 and
3291 <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>
3292 variables.
3293 <note>
3294 Additionally, a recipe can customize the files further by
3295 declaring a processing function in the
3296 <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>
3297 variable.
3298 </note>
3299 </para>
3300
3301 <para>
3302 A shared state (sstate) object is built from these files
3303 and the files are placed into a subdirectory of
3304 <link linkend='structure-build-tmp-sysroots-components'><filename>tmp/sysroots-components/</filename></link>.
3305 The files are scanned for hardcoded paths to the original
3306 installation location.
3307 If the location is found in text files, the hardcoded
3308 locations are replaced by tokens and a list of the files
3309 needing such replacements is created.
3310 These adjustments are referred to as "FIXMEs".
3311 The list of files that are scanned for paths is controlled by
3312 the
3313 <link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link>
3314 variable.
3315 </para></listitem>
3316 <listitem><para>
3317 <emphasis>Stage Two:</emphasis>
3318 The second stage addresses recipes that want to use something
3319 from another recipe and declare a dependency on that recipe
3320 through the
3321 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
3322 variable.
3323 The recipe will have a
3324 <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
3325 task and when
3326 this task executes, it creates the
3327 <filename>recipe-sysroot</filename> and
3328 <filename>recipe-sysroot-native</filename> in the recipe
3329 work directory (i.e.
3330 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
3331 The OpenEmbedded build system creates hard links to copies of the
3332 relevant files from <filename>sysroots-components</filename>
3333 into the recipe work directory.
3334 <note>
3335 If hard links are not possible, the build system uses
3336 actual copies.
3337 </note>
3338 The build system then addresses any "FIXMEs" to paths as
3339 defined from the list created in the first stage.
3340 </para>
3341
3342 <para>
3343 Finally, any files in <filename>${bindir}</filename>
3344 within the sysroot that have the prefix
3345 "<filename>postinst-</filename>" are executed.
3346 <note>
3347 Although such sysroot post installation scripts are not
3348 recommended for general use, the files do allow some issues
3349 such as user creation and module indexes to be addressed.
3350 </note>
3351 </para>
3352
3353 <para>
3354 Because recipes can have other dependencies outside of
3355 <filename>DEPENDS</filename> (e.g.
3356 <filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>),
3357 the sysroot creation function
3358 <filename>extend_recipe_sysroot</filename> is also added as
3359 a pre-function for those tasks whose dependencies are not
3360 through <filename>DEPENDS</filename> but operate similarly.
3361 </para>
3362
3363 <para>
3364 When installing dependencies into the sysroot, the code
3365 traverses the dependency graph and processes dependencies
3366 in exactly the same way as the dependencies would or would not
3367 be when installed from sstate.
3368 This processing means, for example, a native tool would have
3369 its native dependencies added but a target library would not
3370 have its dependencies traversed or installed.
3371 The same sstate dependency code is used so that
3372 builds should be identical regardless of whether sstate
3373 was used or not.
3374 For a closer look, see the
3375 <filename>setscene_depvalid()</filename> function in the
3376 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
3377 class.
3378 </para>
3379
3380 <para>
3381 The build system is careful to maintain manifests of the files
3382 it installs so that any given dependency can be installed as
3383 needed.
3384 The sstate hash of the installed item is also stored so that
3385 if it changes, the build system can reinstall it.
3386 </para></listitem>
3387 </itemizedlist>
3388 </para>
3389</section>
3390
3391<section id='ref-classes-syslinux'>
3392 <title><filename>syslinux.bbclass</filename></title>
3393
3394 <para>
3395 The <filename>syslinux</filename> class provides syslinux-specific
3396 functions for building bootable images.
3397 </para>
3398
3399 <para>
3400 The class supports the following variables:
3401 <itemizedlist>
3402 <listitem><para><link linkend='var-INITRD'><filename>INITRD</filename></link>:
3403 Indicates list of filesystem images to concatenate and use as
3404 an initial RAM disk (initrd).
3405 This variable is optional.</para></listitem>
3406 <listitem><para><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
3407 Indicates a filesystem image to include as the root filesystem.
3408 This variable is optional.</para></listitem>
3409 <listitem><para><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>:
3410 Enables creating an automatic menu when set to "1".
3411 </para></listitem>
3412 <listitem><para><link linkend='var-LABELS'><filename>LABELS</filename></link>:
3413 Lists targets for automatic configuration.
3414 </para></listitem>
3415 <listitem><para><link linkend='var-APPEND'><filename>APPEND</filename></link>:
3416 Lists append string overrides for each label.
3417 </para></listitem>
3418 <listitem><para><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>:
3419 Lists additional options to add to the syslinux file.
3420 Semicolon characters separate multiple options.
3421 </para></listitem>
3422 <listitem><para><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>:
3423 Lists a background for the VGA boot menu when you are using the
3424 boot menu.</para></listitem>
3425 <listitem><para><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>:
3426 Set to "console=ttyX" to change kernel boot default console.
3427 </para></listitem>
3428 <listitem><para><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>:
3429 Sets an alternate serial port.
3430 Or, turns off serial when the variable is set with an
3431 empty string.</para></listitem>
3432 <listitem><para><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>:
3433 Sets an alternate "console=tty..." kernel boot argument.
3434 </para></listitem>
3435 </itemizedlist>
3436 </para>
3437</section>
3438
3439<section id='ref-classes-systemd'>
3440 <title><filename>systemd.bbclass</filename></title>
3441
3442 <para>
3443 The <filename>systemd</filename> class provides support for recipes
3444 that install systemd unit files.
3445 </para>
3446
3447 <para>
3448 The functionality for this class is disabled unless you have "systemd"
3449 in
3450 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
3451 </para>
3452
3453 <para>
3454 Under this class, the recipe or Makefile (i.e. whatever the recipe is
3455 calling during the
3456 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
3457 task) installs unit files into
3458 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>.
3459 If the unit files being installed go into packages other than the
3460 main package, you need to set
3461 <link linkend='var-SYSTEMD_PACKAGES'><filename>SYSTEMD_PACKAGES</filename></link>
3462 in your recipe to identify the packages in which the files will be
3463 installed.
3464 </para>
3465
3466 <para>
3467 You should set
3468 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
3469 to the name of the service file.
3470 You should also use a package name override to indicate the package
3471 to which the value applies.
3472 If the value applies to the recipe's main package, use
3473 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>.
3474 Here is an example from the connman recipe:
3475 <literallayout class='monospaced'>
3476 SYSTEMD_SERVICE_${PN} = "connman.service"
3477 </literallayout>
3478 Services are set up to start on boot automatically unless
3479 you have set
3480 <link linkend='var-SYSTEMD_AUTO_ENABLE'><filename>SYSTEMD_AUTO_ENABLE</filename></link>
3481 to "disable".
3482 </para>
3483
3484 <para>
3485 For more information on <filename>systemd</filename>, see the
3486 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager'>Selecting an Initialization Manager</ulink>"
3487 section in the Yocto Project Development Tasks Manual.
3488 </para>
3489</section>
3490
3491<section id='ref-classes-systemd-boot'>
3492 <title><filename>systemd-boot.bbclass</filename></title>
3493
3494 <para>
3495 The <filename>systemd-boot</filename> class provides functions specific
3496 to the systemd-boot bootloader for building bootable images.
3497 This is an internal class and is not intended to be used directly.
3498 <note>
3499 The <filename>systemd-boot</filename> class is a result from
3500 merging the <filename>gummiboot</filename> class used in previous
3501 Yocto Project releases with the <filename>systemd</filename>
3502 project.
3503 </note>
3504 Set the
3505 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
3506 variable to "systemd-boot" to use this class.
3507 Doing so creates a standalone EFI bootloader that is not dependent
3508 on systemd.
3509 </para>
3510
3511 <para>
3512 For information on more variables used and supported in this class,
3513 see the
3514 <link linkend='var-SYSTEMD_BOOT_CFG'><filename>SYSTEMD_BOOT_CFG</filename></link>,
3515 <link linkend='var-SYSTEMD_BOOT_ENTRIES'><filename>SYSTEMD_BOOT_ENTRIES</filename></link>,
3516 and
3517 <link linkend='var-SYSTEMD_BOOT_TIMEOUT'><filename>SYSTEMD_BOOT_TIMEOUT</filename></link>
3518 variables.
3519 </para>
3520
3521 <para>
3522 You can also see the
3523 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>
3524 for more information.
3525 </para>
3526</section>
3527
3528<section id='ref-classes-terminal'>
3529 <title><filename>terminal.bbclass</filename></title>
3530
3531 <para>
3532 The <filename>terminal</filename> class provides support for starting
3533 a terminal session.
3534 The
3535 <link linkend='var-OE_TERMINAL'><filename>OE_TERMINAL</filename></link>
3536 variable controls which terminal emulator is used for the session.
3537 </para>
3538
3539 <para>
3540 Other classes use the <filename>terminal</filename> class anywhere a
3541 separate terminal session needs to be started.
3542 For example, the
3543 <link linkend='ref-classes-patch'><filename>patch</filename></link>
3544 class assuming
3545 <link linkend='var-PATCHRESOLVE'><filename>PATCHRESOLVE</filename></link>
3546 is set to "user", the
3547 <link linkend='ref-classes-cml1'><filename>cml1</filename></link>
3548 class, and the
3549 <link linkend='ref-classes-devshell'><filename>devshell</filename></link>
3550 class all use the <filename>terminal</filename> class.
3551 </para>
3552</section>
3553
3554<section id='ref-classes-testimage*'>
3555 <title><filename>testimage*.bbclass</filename></title>
3556
3557 <para>
3558 The <filename>testimage*</filename> classes support running
3559 automated tests against images using QEMU and on actual hardware.
3560 The classes handle loading the tests and starting the image.
3561 To use the classes, you need to perform steps to set up the
3562 environment.
3563 <note><title>Tip</title>
3564 Best practices include using
3565 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3566 rather than
3567 <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to
3568 inherit the <filename>testimage</filename> class for automated
3569 image testing.
3570 </note>
3571 </para>
3572
3573 <para>
3574 The tests are commands that run on the target system over
3575 <filename>ssh</filename>.
3576 Each test is written in Python and makes use of the
3577 <filename>unittest</filename> module.
3578 </para>
3579
3580 <para>
3581 The <filename>testimage.bbclass</filename> runs tests on an image
3582 when called using the following:
3583 <literallayout class='monospaced'>
3584 $ bitbake -c testimage <replaceable>image</replaceable>
3585 </literallayout>
3586 The <filename>testimage-auto</filename> class runs tests on an image
3587 after the image is constructed (i.e.
3588 <link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
3589 must be set to "1").
3590 </para>
3591
3592 <para>
3593 For information on how to enable, run, and create new tests, see the
3594 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
3595 section in the Yocto Project Development Tasks Manual.
3596 </para>
3597</section>
3598
3599<section id='ref-classes-testsdk'>
3600 <title><filename>testsdk.bbclass</filename></title>
3601
3602 <para>
3603 This class supports running automated tests against
3604 software development kits (SDKs).
3605 The <filename>testsdk</filename> class runs tests on an SDK when
3606 called using the following:
3607 <literallayout class='monospaced'>
3608 $ bitbake -c testsdk image
3609 </literallayout>
3610 <note><title>Tip</title>
3611 Best practices include using
3612 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3613 rather than
3614 <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to
3615 inherit the <filename>testsdk</filename> class for automated
3616 SDK testing.
3617 </note>
3618 </para>
3619</section>
3620
3621<section id='ref-classes-texinfo'>
3622 <title><filename>texinfo.bbclass</filename></title>
3623
3624 <para>
3625 This class should be inherited by recipes whose upstream packages
3626 invoke the <filename>texinfo</filename> utilities at build-time.
3627 Native and cross recipes are made to use the dummy scripts provided
3628 by <filename>texinfo-dummy-native</filename>, for improved performance.
3629 Target architecture recipes use the genuine
3630 Texinfo utilities.
3631 By default, they use the Texinfo utilities on the host system.
3632 <note>
3633 If you want to use the Texinfo recipe shipped with the build
3634 system, you can remove "texinfo-native" from
3635 <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
3636 and makeinfo from
3637 <link linkend='var-SANITY_REQUIRED_UTILITIES'><filename>SANITY_REQUIRED_UTILITIES</filename></link>.
3638 </note>
3639 </para>
3640</section>
3641
3642<section id='ref-classes-tinderclient'>
3643 <title><filename>tinderclient.bbclass</filename></title>
3644
3645 <para>
3646 The <filename>tinderclient</filename> class submits build results to
3647 an external Tinderbox instance.
3648 <note>
3649 This class is currently unmaintained.
3650 </note>
3651 </para>
3652</section>
3653
3654<section id='ref-classes-toaster'>
3655 <title><filename>toaster.bbclass</filename></title>
3656
3657 <para>
3658 The <filename>toaster</filename> class collects information about
3659 packages and images and sends them as events that the BitBake
3660 user interface can receive.
3661 The class is enabled when the Toaster user interface is running.
3662 </para>
3663
3664 <para>
3665 This class is not intended to be used directly.
3666 </para>
3667</section>
3668
3669<section id='ref-classes-toolchain-scripts'>
3670 <title><filename>toolchain-scripts.bbclass</filename></title>
3671
3672 <para>
3673 The <filename>toolchain-scripts</filename> class provides the scripts
3674 used for setting up the environment for installed SDKs.
3675 </para>
3676</section>
3677
3678<section id='ref-classes-typecheck'>
3679 <title><filename>typecheck.bbclass</filename></title>
3680
3681 <para>
3682 The <filename>typecheck</filename> class provides support for
3683 validating the values of variables set at the configuration level
3684 against their defined types.
3685 The OpenEmbedded build system allows you to define the type of a
3686 variable using the "type" varflag.
3687 Here is an example:
3688 <literallayout class='monospaced'>
3689 IMAGE_FEATURES[type] = "list"
3690 </literallayout>
3691 </para>
3692</section>
3693
3694<section id='ref-classes-uboot-config'>
3695 <title><filename>uboot-config.bbclass</filename></title>
3696
3697 <para>
3698 The <filename>uboot-config</filename> class provides support for
3699 U-Boot configuration for a machine.
3700 Specify the machine in your recipe as follows:
3701 <literallayout class='monospaced'>
3702 UBOOT_CONFIG ??= &lt;default&gt;
3703 UBOOT_CONFIG[foo] = "config,images"
3704 </literallayout>
3705 You can also specify the machine using this method:
3706 <literallayout class='monospaced'>
3707 UBOOT_MACHINE = "config"
3708 </literallayout>
3709 See the
3710 <link linkend='var-UBOOT_CONFIG'><filename>UBOOT_CONFIG</filename></link>
3711 and
3712 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
3713 variables for additional information.
3714 </para>
3715</section>
3716
3717<section id='ref-classes-uninative'>
3718 <title><filename>uninative.bbclass</filename></title>
3719
3720 <para>
3721 Attempts to isolate the build system from the host
3722 distribution's C library in order to make re-use of native shared state
3723 artifacts across different host distributions practical.
3724 With this class enabled, a tarball containing a pre-built C library
3725 is downloaded at the start of the build.
3726 In the Poky reference distribution this is enabled by default
3727 through
3728 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>.
3729 Other distributions that do not derive from poky can also
3730 "<filename>require conf/distro/include/yocto-uninative.inc</filename>"
3731 to use this.
3732 Alternatively if you prefer, you can build the uninative-tarball recipe
3733 yourself, publish the resulting tarball (e.g. via HTTP) and set
3734 <filename>UNINATIVE_URL</filename> and
3735 <filename>UNINATIVE_CHECKSUM</filename> appropriately.
3736 For an example, see the
3737 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>.
3738 </para>
3739
3740 <para>
3741 The <filename>uninative</filename> class is also used unconditionally
3742 by the extensible SDK.
3743 When building the extensible SDK,
3744 <filename>uninative-tarball</filename> is built and the resulting
3745 tarball is included within the SDK.
3746 </para>
3747</section>
3748
3749<section id='ref-classes-update-alternatives'>
3750 <title><filename>update-alternatives.bbclass</filename></title>
3751
3752 <para>
3753 The <filename>update-alternatives</filename> class helps the
3754 alternatives system when multiple sources provide the same command.
3755 This situation occurs when several programs that have the same or
3756 similar function are installed with the same name.
3757 For example, the <filename>ar</filename> command is available from the
3758 <filename>busybox</filename>, <filename>binutils</filename> and
3759 <filename>elfutils</filename> packages.
3760 The <filename>update-alternatives</filename> class handles
3761 renaming the binaries so that multiple packages can be installed
3762 without conflicts.
3763 The <filename>ar</filename> command still works regardless of which
3764 packages are installed or subsequently removed.
3765 The class renames the conflicting binary in each package and symlinks
3766 the highest priority binary during installation or removal of packages.
3767 </para>
3768
3769 <para>
3770 To use this class, you need to define a number of variables:
3771 <itemizedlist>
3772 <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
3773 </para></listitem>
3774 <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
3775 </para></listitem>
3776 <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
3777 </para></listitem>
3778 <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
3779 </para></listitem>
3780 </itemizedlist>
3781 These variables list alternative commands needed by a package,
3782 provide pathnames for links, default links for targets, and
3783 so forth.
3784 For details on how to use this class, see the comments in the
3785 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>
3786 file.
3787 </para>
3788
3789 <note>
3790 You can use the <filename>update-alternatives</filename> command
3791 directly in your recipes.
3792 However, this class simplifies things in most cases.
3793 </note>
3794</section>
3795
3796<section id='ref-classes-update-rc.d'>
3797 <title><filename>update-rc.d.bbclass</filename></title>
3798
3799 <para>
3800 The <filename>update-rc.d</filename> class uses
3801 <filename>update-rc.d</filename> to safely install an
3802 initialization script on behalf of the package.
3803 The OpenEmbedded build system takes care of details such as making
3804 sure the script is stopped before a package is removed and started when
3805 the package is installed.
3806 </para>
3807
3808 <para>
3809 Three variables control this class:
3810 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
3811 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
3812 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
3813 See the variable links for details.
3814 </para>
3815</section>
3816
3817<section id='ref-classes-useradd'>
3818 <title><filename>useradd*.bbclass</filename></title>
3819
3820 <para>
3821 The <filename>useradd*</filename> classes support the addition of users
3822 or groups for usage by the package on the target.
3823 For example, if you have packages that contain system services that
3824 should be run under their own user or group, you can use these classes
3825 to enable creation of the user or group.
3826 The
3827 <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
3828 recipe in the <link linkend='source-directory'>Source Directory</link>
3829 provides a simple example that shows how to add three
3830 users and groups to two packages.
3831 See the <filename>useradd-example.bb</filename> recipe for more
3832 information on how to use these classes.
3833 </para>
3834
3835 <para>
3836 The <filename>useradd_base</filename> class provides basic
3837 functionality for user or groups settings.
3838 </para>
3839
3840 <para>
3841 The <filename>useradd*</filename> classes support the
3842 <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>,
3843 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
3844 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
3845 and
3846 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
3847 variables.
3848 </para>
3849
3850 <para>
3851 The <filename>useradd-staticids</filename> class supports the addition
3852 of users or groups that have static user identification
3853 (<filename>uid</filename>) and group identification
3854 (<filename>gid</filename>) values.
3855 </para>
3856
3857 <para>
3858 The default behavior of the OpenEmbedded build system for assigning
3859 <filename>uid</filename> and <filename>gid</filename> values when
3860 packages add users and groups during package install time is to
3861 add them dynamically.
3862 This works fine for programs that do not care what the values of the
3863 resulting users and groups become.
3864 In these cases, the order of the installation determines the final
3865 <filename>uid</filename> and <filename>gid</filename> values.
3866 However, if non-deterministic
3867 <filename>uid</filename> and <filename>gid</filename> values are a
3868 problem, you can override the default, dynamic application of these
3869 values by setting static values.
3870 When you set static values, the OpenEmbedded build system looks in
3871 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
3872 <filename>files/passwd</filename> and <filename>files/group</filename>
3873 files for the values.
3874 </para>
3875
3876 <para>
3877 To use static <filename>uid</filename> and <filename>gid</filename>
3878 values, you need to set some variables.
3879 See the
3880 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
3881 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
3882 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
3883 and
3884 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
3885 variables.
3886 You can also see the
3887 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
3888 class for additional information.
3889 </para>
3890
3891 <note><title>Notes</title>
3892 You do not use the <filename>useradd-staticids</filename>
3893 class directly.
3894 You either enable or disable the class by setting the
3895 <filename>USERADDEXTENSION</filename> variable.
3896 If you enable or disable the class in a configured system,
3897 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
3898 might contain incorrect <filename>uid</filename> and
3899 <filename>gid</filename> values.
3900 Deleting the <filename>TMPDIR</filename> directory
3901 will correct this condition.
3902 </note>
3903</section>
3904
3905<section id='ref-classes-utility-tasks'>
3906 <title><filename>utility-tasks.bbclass</filename></title>
3907
3908 <para>
3909 The <filename>utility-tasks</filename> class provides support for
3910 various "utility" type tasks that are applicable to all recipes,
3911 such as
3912 <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and
3913 <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>.
3914 </para>
3915
3916 <para>
3917 This class is enabled by default because it is inherited by
3918 the
3919 <link linkend='ref-classes-base'><filename>base</filename></link>
3920 class.
3921 </para>
3922</section>
3923
3924<section id='ref-classes-utils'>
3925 <title><filename>utils.bbclass</filename></title>
3926
3927 <para>
3928 The <filename>utils</filename> class provides some useful Python
3929 functions that are typically used in inline Python expressions
3930 (e.g. <filename>${@...}</filename>).
3931 One example use is for <filename>bb.utils.contains()</filename>.
3932 </para>
3933
3934 <para>
3935 This class is enabled by default because it is inherited by the
3936 <link linkend='ref-classes-base'><filename>base</filename></link>
3937 class.
3938 </para>
3939</section>
3940
3941<section id='ref-classes-vala'>
3942 <title><filename>vala.bbclass</filename></title>
3943
3944 <para>
3945 The <filename>vala</filename> class supports recipes that need to
3946 build software written using the Vala programming language.
3947 </para>
3948</section>
3949
3950<section id='ref-classes-waf'>
3951 <title><filename>waf.bbclass</filename></title>
3952
3953 <para>
3954 The <filename>waf</filename> class supports recipes that need to build
3955 software that uses the Waf build system.
3956 You can use the
3957 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
3958 or
3959 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
3960 variables to specify additional configuration options to be passed on
3961 the Waf command line.
3962 </para>
3963</section>
3964
3965<!-- Undocumented classes are:
3966 image-empty.bbclass (possibly being dropped)
3967 migrate_localcount.bbclass (still need a description)
3968-->
3969
3970
3971</chapter>
3972<!--
3973vim: expandtab tw=80 ts=4
3974-->
diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml
deleted file mode 100644
index 6c3ccc3034..0000000000
--- a/documentation/ref-manual/ref-devtool-reference.xml
+++ /dev/null
@@ -1,842 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-devtool-reference'>
7 <title><filename>devtool</filename> Quick Reference</title>
8
9 <para>
10 The <filename>devtool</filename> command-line tool provides a number
11 of features that help you build, test, and package software.
12 This command is available alongside the <filename>bitbake</filename>
13 command.
14 Additionally, the <filename>devtool</filename> command is a key
15 part of the extensible SDK.
16 </para>
17
18 <para>
19 This chapter provides a Quick Reference for the
20 <filename>devtool</filename> command.
21 For more information on how to apply the command when using the
22 extensible SDK, see the
23 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>"
24 chapter in the Yocto Project Application Development and the
25 Extensible Software Development Kit (eSDK) manual.
26 </para>
27
28 <section id='devtool-getting-help'>
29 <title>Getting Help</title>
30
31 <para>
32 The <filename>devtool</filename> command line is organized
33 similarly to Git in that it has a number of sub-commands for
34 each function.
35 You can run <filename>devtool --help</filename> to see all
36 the commands:
37 <literallayout class='monospaced'>
38 $ devtool -h
39 NOTE: Starting bitbake server...
40 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
41 [--color COLOR] [-h]
42 &lt;subcommand&gt; ...
43
44 OpenEmbedded development tool
45
46 options:
47 --basepath BASEPATH Base directory of SDK / build directory
48 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
49 from the metadata
50 -d, --debug Enable debug output
51 -q, --quiet Print only errors
52 --color COLOR Colorize output (where COLOR is auto, always, never)
53 -h, --help show this help message and exit
54
55 subcommands:
56 Beginning work on a recipe:
57 add Add a new recipe
58 modify Modify the source for an existing recipe
59 upgrade Upgrade an existing recipe
60 Getting information:
61 status Show workspace status
62 search Search available recipes
63 latest-version Report the latest version of an existing recipe
64 check-upgrade-status Report upgradability for multiple (or all) recipes
65 Working on a recipe in the workspace:
66 build Build a recipe
67 rename Rename a recipe file in the workspace
68 edit-recipe Edit a recipe file
69 find-recipe Find a recipe file
70 configure-help Get help on configure script options
71 update-recipe Apply changes from external source tree to recipe
72 reset Remove a recipe from your workspace
73 finish Finish working on a recipe in your workspace
74 Testing changes on target:
75 deploy-target Deploy recipe output files to live target machine
76 undeploy-target Undeploy recipe output files in live target machine
77 build-image Build image including workspace recipe packages
78 Advanced:
79 create-workspace Set up workspace in an alternative location
80 export Export workspace into a tar archive
81 import Import exported tar archive into workspace
82 extract Extract the source for an existing recipe
83 sync Synchronize the source tree for an existing recipe
84 Use devtool &lt;subcommand&gt; --help to get help on a specific command
85 </literallayout>
86 As directed in the general help output, you can get more syntax
87 on a specific command by providing the command name and using
88 "--help":
89 <literallayout class='monospaced'>
90 $ devtool add --help
91 NOTE: Starting bitbake server...
92 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
93 [--fetch-dev] [--version VERSION] [--no-git]
94 [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH]
95 [--binary] [--also-native] [--src-subdir SUBDIR]
96 [--mirrors] [--provides PROVIDES]
97 [recipename] [srctree] [fetchuri]
98
99 Adds a new recipe to the workspace to build a specified source tree. Can
100 optionally fetch a remote URI and unpack it to create the source tree.
101
102 arguments:
103 recipename Name for new recipe to add (just name - no version,
104 path or extension). If not specified, will attempt to
105 auto-detect it.
106 srctree Path to external source tree. If not specified, a
107 subdirectory of
108 /home/scottrif/poky/build/workspace/sources will be
109 used.
110 fetchuri Fetch the specified URI and extract it to create the
111 source tree
112
113 options:
114 -h, --help show this help message and exit
115 --same-dir, -s Build in same directory as source
116 --no-same-dir Force build in a separate build directory
117 --fetch URI, -f URI Fetch the specified URI and extract it to create the
118 source tree (deprecated - pass as positional argument
119 instead)
120 --fetch-dev For npm, also fetch devDependencies
121 --version VERSION, -V VERSION
122 Version to use within recipe (PV)
123 --no-git, -g If fetching source, do not set up source tree as a git
124 repository
125 --srcrev SRCREV, -S SRCREV
126 Source revision to fetch if fetching from an SCM such
127 as git (default latest)
128 --autorev, -a When fetching from a git repository, set SRCREV in the
129 recipe to a floating revision instead of fixed
130 --srcbranch SRCBRANCH, -B SRCBRANCH
131 Branch in source repository if fetching from an SCM
132 such as git (default master)
133 --binary, -b Treat the source tree as something that should be
134 installed verbatim (no compilation, same directory
135 structure). Useful with binary packages e.g. RPMs.
136 --also-native Also add native variant (i.e. support building recipe
137 for the build host as well as the target machine)
138 --src-subdir SUBDIR Specify subdirectory within source tree to use
139 --mirrors Enable PREMIRRORS and MIRRORS for source tree fetching
140 (disable by default).
141 --provides PROVIDES, -p PROVIDES
142 Specify an alias for the item provided by the recipe.
143 E.g. virtual/libgl
144 </literallayout>
145 </para>
146 </section>
147
148 <section id='devtool-the-workspace-layer-structure'>
149 <title>The Workspace Layer Structure</title>
150
151 <para>
152 <filename>devtool</filename> uses a "Workspace" layer
153 in which to accomplish builds.
154 This layer is not specific to any single
155 <filename>devtool</filename> command but is rather a common
156 working area used across the tool.
157 </para>
158
159 <para>
160 The following figure shows the workspace structure:
161 </para>
162
163 <para>
164 <imagedata fileref="figures/build-workspace-directory.png"
165 width="6in" depth="5in" align="left" scale="70" />
166 </para>
167
168 <para>
169 <literallayout class='monospaced'>
170 attic - A directory created if devtool believes it must preserve
171 anything when you run "devtool reset". For example, if you
172 run "devtool add", make changes to the recipe, and then
173 run "devtool reset", devtool takes notice that the file has
174 been changed and moves it into the attic should you still
175 want the recipe.
176
177 README - Provides information on what is in workspace layer and how to
178 manage it.
179
180 .devtool_md5 - A checksum file used by devtool.
181
182 appends - A directory that contains *.bbappend files, which point to
183 external source.
184
185 conf - A configuration directory that contains the layer.conf file.
186
187 recipes - A directory containing recipes. This directory contains a
188 folder for each directory added whose name matches that of the
189 added recipe. devtool places the <replaceable>recipe</replaceable>.bb file
190 within that sub-directory.
191
192 sources - A directory containing a working copy of the source files used
193 when building the recipe. This is the default directory used
194 as the location of the source tree when you do not provide a
195 source tree path. This directory contains a folder for each
196 set of source files matched to a corresponding recipe.
197 </literallayout>
198 </para>
199 </section>
200
201 <section id='devtool-adding-a-new-recipe-to-the-workspace'>
202 <title>Adding a New Recipe to the Workspace Layer</title>
203
204 <para>
205 Use the <filename>devtool add</filename> command to add a new recipe
206 to the workspace layer.
207 The recipe you add should not exist -
208 <filename>devtool</filename> creates it for you.
209 The source files the recipe uses should exist in an external
210 area.
211 </para>
212
213 <para>
214 The following example creates and adds a new recipe named
215 <filename>jackson</filename> to a workspace layer the tool creates.
216 The source code built by the recipes resides in
217 <filename>/home/<replaceable>user</replaceable>/sources/jackson</filename>:
218 <literallayout class='monospaced'>
219 $ devtool add jackson /home/<replaceable>user</replaceable>/sources/jackson
220 </literallayout>
221 </para>
222
223 <para>
224 If you add a recipe and the workspace layer does not exist,
225 the command creates the layer and populates it as
226 described in
227 "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
228 section.
229 </para>
230
231 <para>
232 Running <filename>devtool add</filename> when the
233 workspace layer exists causes the tool to add the recipe,
234 append files, and source files into the existing workspace layer.
235 The <filename>.bbappend</filename> file is created to point
236 to the external source tree.
237 <note>
238 If your recipe has runtime dependencies defined, you must be sure
239 that these packages exist on the target hardware before attempting
240 to run your application.
241 If dependent packages (e.g. libraries) do not exist on the target,
242 your application, when run, will fail to find those functions.
243 For more information, see the
244 "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software on the Target Machine</link>"
245 section.
246 </note>
247 </para>
248
249 <para>
250 By default, <filename>devtool add</filename> uses the latest
251 revision (i.e. master) when unpacking files from a remote URI.
252 In some cases, you might want to specify a source revision by
253 branch, tag, or commit hash. You can specify these options when
254 using the <filename>devtool add</filename> command:
255 <itemizedlist>
256 <listitem><para>
257 To specify a source branch, use the
258 <filename>--srcbranch</filename> option:
259 <literallayout class='monospaced'>
260 $ devtool add --srcbranch &DISTRO_NAME_NO_CAP; jackson /home/<replaceable>user</replaceable>/sources/jackson
261 </literallayout>
262 In the previous example, you are checking out the
263 &DISTRO_NAME_NO_CAP; branch.
264 </para></listitem>
265 <listitem><para>
266 To specify a specific tag or commit hash, use the
267 <filename>--srcrev</filename> option:
268 <literallayout class='monospaced'>
269 $ devtool add --srcrev &DISTRO_REL_TAG; jackson /home/<replaceable>user</replaceable>/sources/jackson
270 $ devtool add --srcrev <replaceable>some_commit_hash</replaceable> /home/<replaceable>user</replaceable>/sources/jackson
271 </literallayout>
272 The previous examples check out the &DISTRO_REL_TAG; tag
273 and the commit associated with the
274 <replaceable>some_commit_hash</replaceable> hash.
275 </para></listitem>
276 </itemizedlist>
277 <note>
278 If you prefer to use the latest revision every time the recipe is
279 built, use the options <filename>--autorev</filename>
280 or <filename>-a</filename>.
281 </note>
282 </para>
283 </section>
284
285 <section id='devtool-extracting-the-source-for-an-existing-recipe'>
286 <title>Extracting the Source for an Existing Recipe</title>
287
288 <para>
289 Use the <filename>devtool extract</filename> command to
290 extract the source for an existing recipe.
291 When you use this command, you must supply the root name
292 of the recipe (i.e. no version, paths, or extensions), and
293 you must supply the directory to which you want the source
294 extracted.
295 </para>
296
297 <para>
298 Additional command options let you control the name of a
299 development branch into which you can checkout the source
300 and whether or not to keep a temporary directory, which is
301 useful for debugging.
302 </para>
303 </section>
304
305 <section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
306 <title>Synchronizing a Recipe's Extracted Source Tree</title>
307
308 <para>
309 Use the <filename>devtool sync</filename> command to
310 synchronize a previously extracted source tree for an
311 existing recipe.
312 When you use this command, you must supply the root name
313 of the recipe (i.e. no version, paths, or extensions), and
314 you must supply the directory to which you want the source
315 extracted.
316 </para>
317
318 <para>
319 Additional command options let you control the name of a
320 development branch into which you can checkout the source
321 and whether or not to keep a temporary directory, which is
322 useful for debugging.
323 </para>
324 </section>
325
326 <section id='devtool-modifying-a-recipe'>
327 <title>Modifying an Existing Recipe</title>
328
329 <para>
330 Use the <filename>devtool modify</filename> command to begin
331 modifying the source of an existing recipe.
332 This command is very similar to the
333 <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link>
334 command except that it does not physically create the
335 recipe in the workspace layer because the recipe already
336 exists in an another layer.
337 </para>
338
339 <para>
340 The <filename>devtool modify</filename> command extracts the
341 source for a recipe, sets it up as a Git repository if the
342 source had not already been fetched from Git, checks out a
343 branch for development, and applies any patches from the recipe
344 as commits on top.
345 You can use the following command to checkout the source
346 files:
347 <literallayout class='monospaced'>
348 $ devtool modify <replaceable>recipe</replaceable>
349 </literallayout>
350 Using the above command form, <filename>devtool</filename> uses
351 the existing recipe's
352 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
353 statement to locate the upstream source, extracts the source
354 into the default sources location in the workspace.
355 The default development branch used is "devtool".
356 </para>
357 </section>
358
359 <section id='devtool-edit-an-existing-recipe'>
360 <title>Edit an Existing Recipe</title>
361
362 <para>
363 Use the <filename>devtool edit-recipe</filename> command
364 to run the default editor, which is identified using the
365 <filename>EDITOR</filename> variable, on the specified recipe.
366 </para>
367
368 <para>
369 When you use the <filename>devtool edit-recipe</filename>
370 command, you must supply the root name of the recipe
371 (i.e. no version, paths, or extensions).
372 Also, the recipe file itself must reside in the workspace
373 as a result of the <filename>devtool add</filename> or
374 <filename>devtool upgrade</filename> commands.
375 However, you can override that requirement by using the
376 "-a" or "--any-recipe" option.
377 Using either of these options allows you to edit any recipe
378 regardless of its location.
379 </para>
380 </section>
381
382 <section id='devtool-updating-a-recipe'>
383 <title>Updating a Recipe</title>
384
385 <para>
386 Use the <filename>devtool update-recipe</filename> command to
387 update your recipe with patches that reflect changes you make
388 to the source files.
389 For example, if you know you are going to work on some
390 code, you could first use the
391 <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
392 command to extract the code and set up the workspace.
393 After which, you could modify, compile, and test the code.
394 </para>
395
396 <para>
397 When you are satisfied with the results and you have committed
398 your changes to the Git repository, you can then
399 run the <filename>devtool update-recipe</filename> to create the
400 patches and update the recipe:
401 <literallayout class='monospaced'>
402 $ devtool update-recipe <replaceable>recipe</replaceable>
403 </literallayout>
404 If you run the <filename>devtool update-recipe</filename>
405 without committing your changes, the command ignores the
406 changes.
407 </para>
408
409 <para>
410 Often, you might want to apply customizations made to your
411 software in your own layer rather than apply them to the
412 original recipe.
413 If so, you can use the
414 <filename>-a</filename> or <filename>--append</filename>
415 option with the <filename>devtool update-recipe</filename>
416 command.
417 These options allow you to specify the layer into which to
418 write an append file:
419 <literallayout class='monospaced'>
420 $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
421 </literallayout>
422 The <filename>*.bbappend</filename> file is created at the
423 appropriate path within the specified layer directory, which
424 may or may not be in your <filename>bblayers.conf</filename>
425 file.
426 If an append file already exists, the command updates it
427 appropriately.
428 </para>
429 </section>
430
431 <section id='devtool-checking-on-the-upgrade-status-of-a-recipe'>
432 <title>Checking on the Upgrade Status of a Recipe</title>
433
434 <para>
435 Upstream recipes change over time.
436 Consequently, you might find that you need to determine if you
437 can upgrade a recipe to a newer version.
438 </para>
439
440 <para>
441 To check on the upgrade status of a recipe, use the
442 <filename>devtool check-upgrade-status</filename> command.
443 The command displays a table of your current recipe versions,
444 the latest upstream versions, the email address of the recipe's
445 maintainer, and any additional information such as commit hash
446 strings and reasons you might not be able to upgrade a particular
447 recipe.
448 <note><title>NOTES:</title>
449 <itemizedlist>
450 <listitem><para>
451 For the <filename>oe-core</filename> layer, recipe
452 maintainers come from the
453 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc'><filename>maintainers.inc</filename></ulink>
454 file.
455 </para></listitem>
456 <listitem><para>
457 If the recipe is using the
458 <ulink url='&YOCTO_DOCS_BB_URL;#git-fetcher'>Git fetcher</ulink>
459 rather than a tarball, the commit hash points to the
460 commit that matches the recipe's latest version tag.
461 </para></listitem>
462 </itemizedlist>
463 </note>
464 </para>
465
466 <para>
467 As with all <filename>devtool</filename> commands, you can get
468 help on the individual command:
469 <literallayout class='monospaced'>
470 $ devtool check-upgrade-status -h
471 NOTE: Starting bitbake server...
472 usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]]
473
474 Prints a table of recipes together with versions currently provided by
475 recipes, and latest upstream versions, when there is a later version available
476
477 arguments:
478 recipe Name of the recipe to report (omit to report upgrade info for
479 all recipes)
480
481 options:
482 -h, --help show this help message and exit
483 --all, -a Show all recipes, not just recipes needing upgrade
484 </literallayout>
485 </para>
486
487 <para>
488 Unless you provide a specific recipe name on the command line,
489 the command checks all recipes in all configured layers.
490 </para>
491
492 <para>
493 Following is a partial example table that reports on all the
494 recipes.
495 Notice the reported reason for not upgrading the
496 <filename>base-passwd</filename> recipe.
497 In this example, while a new version is available upstream,
498 you do not want to use it because the dependency on
499 <filename>cdebconf</filename> is not easily satisfied.
500 <note>
501 When a reason for not upgrading displays, the reason is
502 usually written into the recipe using the
503 <filename>RECIPE_NO_UPDATE_REASON</filename> variable.
504 See the
505 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/recipes-core/base-passwd/base-passwd_3.5.29.bb'><filename>base-passwd.bb</filename></ulink>
506 recipe for an example.
507 </note>
508 <literallayout class='monospaced'>
509 $ devtool check-upgrade-status
510 ...
511 NOTE: acpid 2.0.30 2.0.31
512 Ross Burton &lt;ross.burton@intel.com&gt;
513 NOTE: u-boot-fw-utils 2018.11 2019.01
514 Marek Vasut &lt;marek.vasut@gmail.com&gt;
515 d3689267f92c5956e09cc7d1baa4700141662bff
516 NOTE: u-boot-tools 2018.11 2019.01
517 Marek Vasut &lt;marek.vasut@gmail.com&gt;
518 d3689267f92c5956e09cc7d1baa4700141662bff
519 .
520 .
521 .
522 NOTE: base-passwd 3.5.29 3.5.45
523 Anuj Mittal &lt;anuj.mittal@intel.com&gt; cannot be updated due to: Version
524 3.5.38 requires cdebconf for update-passwd utility
525 NOTE: busybox 1.29.2 1.30.0
526 Andrej Valek &lt;andrej.valek@siemens.com&gt;
527 NOTE: dbus-test 1.12.10 1.12.12
528 Chen Qi &lt;Qi.Chen@windriver.com&gt;
529 </literallayout>
530 </para>
531 </section>
532
533 <section id='devtool-upgrading-a-recipe'>
534 <title>Upgrading a Recipe</title>
535
536 <para>
537 As software matures, upstream recipes are upgraded to newer
538 versions.
539 As a developer, you need to keep your local recipes up-to-date
540 with the upstream version releases.
541 Several methods exist by which you can upgrade recipes.
542 You can read about them in the
543 "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes'>Upgrading Recipes</ulink>"
544 section of the Yocto Project Development Tasks Manual.
545 This section overviews the <filename>devtool upgrade</filename>
546 command.
547 <note>
548 Before you upgrade a recipe, you can check on its upgrade
549 status.
550 See the
551 "<link linkend='devtool-checking-on-the-upgrade-status-of-a-recipe'>Checking on the Upgrade Status of a Recipe</link>"
552 for more information.
553 </note>
554 </para>
555
556 <para>
557 The <filename>devtool upgrade</filename> command
558 upgrades an existing recipe to a more recent version of the
559 recipe upstream.
560 The command puts the upgraded recipe file along with any associated
561 files into a "workspace" and, if necessary, extracts the source
562 tree to a specified location.
563 During the upgrade, patches associated with the recipe are
564 rebased or added as needed.
565 </para>
566
567 <para>
568 When you use the <filename>devtool upgrade</filename> command,
569 you must supply the root name of the recipe (i.e. no version,
570 paths, or extensions), and you must supply the directory
571 to which you want the source extracted.
572 Additional command options let you control things such as
573 the version number to which you want to upgrade (i.e. the
574 <link linkend='var-PV'><filename>PV</filename></link>),
575 the source revision to which you want to upgrade (i.e. the
576 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>),
577 whether or not to apply patches, and so forth.
578 </para>
579
580 <para>
581 You can read more on the <filename>devtool upgrade</filename>
582 workflow in the
583 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>"
584 section in the Yocto Project Application Development and the
585 Extensible Software Development Kit (eSDK) manual.
586 You can also see an example of how to use
587 <filename>devtool upgrade</filename> in the
588 "<ulink url='&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade'>Using <filename>devtool upgrade</filename></ulink>"
589 section in the Yocto Project Development Tasks Manual.
590 </para>
591 </section>
592
593 <section id='devtool-resetting-a-recipe'>
594 <title>Resetting a Recipe</title>
595
596 <para>
597 Use the <filename>devtool reset</filename> command to remove a
598 recipe and its configuration (e.g. the corresponding
599 <filename>.bbappend</filename> file) from the workspace layer.
600 Realize that this command deletes the recipe and the
601 append file.
602 The command does not physically move them for you.
603 Consequently, you must be sure to physically relocate your
604 updated recipe and the append file outside of the workspace
605 layer before running the <filename>devtool reset</filename>
606 command.
607 </para>
608
609 <para>
610 If the <filename>devtool reset</filename> command detects that
611 the recipe or the append files have been modified, the
612 command preserves the modified files in a separate "attic"
613 subdirectory under the workspace layer.
614 </para>
615
616 <para>
617 Here is an example that resets the workspace directory that
618 contains the <filename>mtr</filename> recipe:
619 <literallayout class='monospaced'>
620 $ devtool reset mtr
621 NOTE: Cleaning sysroot for recipe mtr...
622 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
623 longer need it then please delete it manually
624 $
625 </literallayout>
626 </para>
627 </section>
628
629 <section id='devtool-building-your-recipe'>
630 <title>Building Your Recipe</title>
631
632 <para>
633 Use the <filename>devtool build</filename> command to build your
634 recipe.
635 The <filename>devtool build</filename> command is equivalent to
636 the <filename>bitbake -c populate_sysroot</filename> command.
637 </para>
638
639 <para>
640 When you use the <filename>devtool build</filename> command,
641 you must supply the root name of the recipe (i.e. do not provide
642 versions, paths, or extensions).
643 You can use either the "-s" or the "--disable-parallel-make"
644 options to disable parallel makes during the build.
645 Here is an example:
646 <literallayout class='monospaced'>
647 $ devtool build <replaceable>recipe</replaceable>
648 </literallayout>
649 </para>
650 </section>
651
652 <section id='devtool-building-your-image'>
653 <title>Building Your Image</title>
654
655 <para>
656 Use the <filename>devtool build-image</filename> command
657 to build an image, extending it to include packages from
658 recipes in the workspace.
659 Using this command is useful when you want an image that
660 ready for immediate deployment onto a device for testing.
661 For proper integration into a final image, you need to
662 edit your custom image recipe appropriately.
663 </para>
664
665 <para>
666 When you use the <filename>devtool build-image</filename>
667 command, you must supply the name of the image.
668 This command has no command line options:
669 <literallayout class='monospaced'>
670 $ devtool build-image <replaceable>image</replaceable>
671 </literallayout>
672 </para>
673 </section>
674
675 <section id='devtool-deploying-your-software-on-the-target-machine'>
676 <title>Deploying Your Software on the Target Machine</title>
677
678 <para>
679 Use the <filename>devtool deploy-target</filename> command to
680 deploy the recipe's build output to the live target machine:
681 <literallayout class='monospaced'>
682 $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
683 </literallayout>
684 The <replaceable>target</replaceable> is the address of the
685 target machine, which must be running an SSH server (i.e.
686 <filename>user@hostname[:destdir]</filename>).
687 </para>
688
689 <para>
690 This command deploys all files installed during the
691 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
692 task.
693 Furthermore, you do not need to have package management enabled
694 within the target machine.
695 If you do, the package manager is bypassed.
696 <note><title>Notes</title>
697 <para>
698 The <filename>deploy-target</filename>
699 functionality is for development only.
700 You should never use it to update an image that will be
701 used in production.
702 </para>
703 </note>
704 </para>
705
706 <para>
707 Some conditions exist that could prevent a deployed application
708 from behaving as expected.
709 When both of the following conditions exist, your application has
710 the potential to not behave correctly when run on the target:
711 <itemizedlist>
712 <listitem><para>
713 You are deploying a new application to the target and
714 the recipe you used to build the application had
715 correctly defined runtime dependencies.
716 </para></listitem>
717 <listitem><para>
718 The target does not physically have the packages on which
719 the application depends installed.
720 </para></listitem>
721 </itemizedlist>
722 If both of these conditions exist, your application will not
723 behave as expected.
724 The reason for this misbehavior is because the
725 <filename>devtool deploy-target</filename> command does not deploy
726 the packages (e.g. libraries) on which your new application
727 depends.
728 The assumption is that the packages are already on the target.
729 Consequently, when a runtime call is made in the application
730 for a dependent function (e.g. a library call), the function
731 cannot be found.
732 </para>
733
734 <para>
735 To be sure you have all the dependencies local to the target, you
736 need to be sure that the packages are pre-deployed (installed)
737 on the target before attempting to run your application.
738 </para>
739 </section>
740
741 <section id='devtool-removing-your-software-from-the-target-machine'>
742 <title>Removing Your Software from the Target Machine</title>
743
744 <para>
745 Use the <filename>devtool undeploy-target</filename> command to
746 remove deployed build output from the target machine.
747 For the <filename>devtool undeploy-target</filename> command to
748 work, you must have previously used the
749 <link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link>
750 command.
751 <literallayout class='monospaced'>
752 $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
753 </literallayout>
754 The <replaceable>target</replaceable> is the address of the
755 target machine, which must be running an SSH server (i.e.
756 <filename>user@hostname</filename>).
757 </para>
758 </section>
759
760 <section id='devtool-creating-the-workspace'>
761 <title>Creating the Workspace Layer in an Alternative Location</title>
762
763 <para>
764 Use the <filename>devtool create-workspace</filename> command to
765 create a new workspace layer in your
766 <link linkend='build-directory'>Build Directory</link>.
767 When you create a new workspace layer, it is populated with the
768 <filename>README</filename> file and the
769 <filename>conf</filename> directory only.
770 </para>
771
772 <para>
773 The following example creates a new workspace layer in your
774 current working and by default names the workspace layer
775 "workspace":
776 <literallayout class='monospaced'>
777 $ devtool create-workspace
778 </literallayout>
779 </para>
780
781 <para>
782 You can create a workspace layer anywhere by supplying
783 a pathname with the command.
784 The following command creates a new workspace layer named
785 "new-workspace":
786 <literallayout class='monospaced'>
787 $ devtool create-workspace /home/scottrif/new-workspace
788 </literallayout>
789 </para>
790 </section>
791
792 <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
793 <title>Get the Status of the Recipes in Your Workspace</title>
794
795 <para>
796 Use the <filename>devtool status</filename> command to
797 list the recipes currently in your workspace.
798 Information includes the paths to their respective
799 external source trees.
800 </para>
801
802 <para>
803 The <filename>devtool status</filename> command has no
804 command-line options:
805 <literallayout class='monospaced'>
806 $ devtool status
807 </literallayout>
808 Following is sample output after using
809 <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></link>
810 to create and add the <filename>mtr_0.86.bb</filename> recipe
811 to the <filename>workspace</filename> directory:
812 <literallayout class='monospaced'>
813 $ devtool status
814 mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
815 $
816 </literallayout>
817 </para>
818 </section>
819
820 <section id='devtool-search-for-available-target-recipes'>
821 <title>Search for Available Target Recipes</title>
822
823 <para>
824 Use the <filename>devtool search</filename> command to
825 search for available target recipes.
826 The command matches the recipe name, package name,
827 description, and installed files.
828 The command displays the recipe name as a result of a
829 match.
830 </para>
831
832 <para>
833 When you use the <filename>devtool search</filename> command,
834 you must supply a <replaceable>keyword</replaceable>.
835 The command uses the <replaceable>keyword</replaceable> when
836 searching for a match.
837 </para>
838 </section>
839</chapter>
840<!--
841vim: expandtab tw=80 ts=4
842-->
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
deleted file mode 100644
index 8cab5ec3a8..0000000000
--- a/documentation/ref-manual/ref-features.xml
+++ /dev/null
@@ -1,461 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-features'>
7 <title>Features</title>
8
9 <para>
10 This chapter provides a reference of shipped machine and distro features
11 you can include as part of your image, a reference on image features you can
12 select, and a reference on feature backfilling.
13 </para>
14
15 <para>
16 Features provide a mechanism for working out which packages
17 should be included in the generated images.
18 Distributions can select which features they want to support through the
19 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
20 variable, which is set or appended to in a distribution's configuration file such as
21 <filename>poky.conf</filename>,
22 <filename>poky-tiny.conf</filename>,
23 <filename>poky-lsb.conf</filename> and so forth.
24 Machine features are set in the
25 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
26 variable, which is set in the machine configuration file and
27 specifies the hardware features for a given machine.
28 </para>
29
30 <para>
31 These two variables combine to work out which kernel modules,
32 utilities, and other packages to include.
33 A given distribution can support a selected subset of features so some machine features might not
34 be included if the distribution itself does not support them.
35 </para>
36
37 <para>
38 One method you can use to determine which recipes are checking to see if a
39 particular feature is contained or not is to <filename>grep</filename> through
40 the <link linkend='metadata'>Metadata</link>
41 for the feature.
42 Here is an example that discovers the recipes whose build is potentially
43 changed based on a given feature:
44 <literallayout class='monospaced'>
45 $ cd poky
46 $ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>'
47 </literallayout>
48 </para>
49
50 <section id='ref-features-machine'>
51 <title>Machine Features</title>
52
53 <para>
54 The items below are features you can use with
55 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
56 Features do not have a one-to-one correspondence to packages, and they can
57 go beyond simply controlling the installation of a package or packages.
58 Sometimes a feature can influence how certain recipes are built.
59 For example, a feature might determine whether a particular configure option
60 is specified within the
61 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
62 task for a particular recipe.
63 </para>
64
65 <para>
66 This feature list only represents features as shipped with the Yocto Project metadata:
67 <itemizedlist>
68 <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
69 </para></listitem>
70 <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
71 </para></listitem>
72 <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
73 </para></listitem>
74 <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
75 </para></listitem>
76 <listitem><para><emphasis>efi:</emphasis> Support for booting through EFI
77 </para></listitem>
78 <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
79 </para></listitem>
80 <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
81 </para></listitem>
82 <listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS
83 </para></listitem>
84 <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
85 </para></listitem>
86 <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
87 </para></listitem>
88 <listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support
89 </para></listitem>
90 <listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display
91 </para></listitem>
92 <listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock
93 </para></listitem>
94 <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
95 </para></listitem>
96 <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
97 </para></listitem>
98 <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
99 </para></listitem>
100 <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
101 </para></listitem>
102 <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
103 </para></listitem>
104 <listitem><para><emphasis>vfat:</emphasis> FAT file system support
105 </para></listitem>
106 <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
107 </para></listitem>
108 </itemizedlist>
109 </para>
110 </section>
111
112 <section id='ref-features-distro'>
113 <title>Distro Features</title>
114
115 <para>
116 The items below are features you can use with
117 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
118 to enable features across your distribution.
119 Features do not have a one-to-one correspondence to packages,
120 and they can go beyond simply controlling the installation of a
121 package or packages.
122 In most cases, the presence or absence of a feature translates to
123 the appropriate option supplied to the configure script during the
124 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
125 task for the recipes that optionally
126 support the feature.
127 </para>
128
129 <para>
130 Some distro features are also machine features.
131 These select features make sense to be controlled both at
132 the machine and distribution configuration level.
133 See the
134 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>
135 variable for more information.
136 </para>
137
138 <para>
139 This list only represents features as shipped with the Yocto Project metadata:
140 <itemizedlist>
141 <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
142 (OSS compatibility kernel modules installed if available).
143 </para></listitem>
144 <listitem><para><emphasis>api-documentation:</emphasis>
145 Enables generation of API documentation during recipe
146 builds.
147 The resulting documentation is added to SDK tarballs
148 when the
149 <filename>bitbake -c populate_sdk</filename> command
150 is used.
151 See the
152 "<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding API Documentation to the Standard SDK</ulink>"
153 section in the Yocto Project Application Development and
154 the Extensible Software Development Kit (eSDK) manual.
155 </para></listitem>
156 <listitem><para><emphasis>bluetooth:</emphasis> Include
157 bluetooth support (integrated BT only).</para></listitem>
158 <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
159 support.</para></listitem>
160 <listitem><para><emphasis>directfb:</emphasis>
161 Include DirectFB support.
162 </para></listitem>
163 <listitem><para><emphasis>ext2:</emphasis> Include tools for
164 supporting for devices with internal HDD/Microdrive for
165 storing files (instead of Flash only devices).
166 </para></listitem>
167 <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
168 support.</para></listitem>
169 <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
170 </para></listitem>
171 <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
172 support (e.g. keymaps will be loaded during boot).
173 </para></listitem>
174 <listitem><para><emphasis>ldconfig:</emphasis>
175 Include support for ldconfig and
176 <filename>ld.so.conf</filename> on the target.
177 </para></listitem>
178 <listitem><para><emphasis>nfs:</emphasis> Include NFS client
179 support (for mounting NFS exports on device).
180 </para></listitem>
181 <listitem><para><emphasis>opengl:</emphasis>
182 Include the Open Graphics Library, which is a
183 cross-language, multi-platform application programming
184 interface used for rendering two and three-dimensional
185 graphics.</para></listitem>
186 <listitem><para><emphasis>pci:</emphasis> Include PCI bus
187 support.</para></listitem>
188 <listitem><para><emphasis>pcmcia:</emphasis> Include
189 PCMCIA/CompactFlash support.</para></listitem>
190 <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
191 support.</para></listitem>
192 <listitem><para><emphasis>ptest:</emphasis> Enables building
193 the package tests where supported by individual recipes.
194 For more information on package tests, see the
195 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
196 section in the Yocto Project Development Tasks Manual.
197 </para></listitem>
198 <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
199 client support (for mounting Samba/Microsoft Windows shares
200 on device).</para></listitem>
201 <listitem><para><emphasis>systemd:</emphasis> Include support
202 for this <filename>init</filename> manager, which is a full
203 replacement of for <filename>init</filename> with parallel
204 starting of services, reduced shell overhead, and other
205 features.
206 This <filename>init</filename> manager is used by many
207 distributions.</para></listitem>
208 <listitem><para><emphasis>usbgadget:</emphasis> Include USB
209 Gadget Device support (for USB networking/serial/storage).
210 </para></listitem>
211 <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
212 support (allows to connect external keyboard, mouse,
213 storage, network etc).</para></listitem>
214 <listitem><para><emphasis>usrmerge:</emphasis> Merges the
215 <filename>/bin</filename>, <filename>/sbin</filename>,
216 <filename>/lib</filename>, and <filename>/lib64</filename>
217 directories into their respective counterparts in the
218 <filename>/usr</filename> directory to provide better package
219 and application compatibility.</para></listitem>
220 <listitem><para><emphasis>wayland:</emphasis> Include the
221 Wayland display server protocol and the library that
222 supports it.</para></listitem>
223 <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
224 (integrated only).</para></listitem>
225 <listitem><para><emphasis>x11:</emphasis> Include the X server
226 and libraries.</para></listitem>
227 </itemizedlist>
228 </para>
229 </section>
230
231 <section id='ref-features-image'>
232 <title>Image Features</title>
233
234 <para>
235 The contents of images generated by the OpenEmbedded build system
236 can be controlled by the
237 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
238 and
239 <link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link>
240 variables that you typically configure in your image recipes.
241 Through these variables, you can add several different
242 predefined packages such as development utilities or packages with
243 debug information needed to investigate application problems or
244 profile applications.
245 </para>
246
247 <para>
248 The following image features are available for all images:
249 <itemizedlist>
250 <listitem><para><emphasis>allow-empty-password:</emphasis>
251 Allows Dropbear and OpenSSH to accept root logins
252 and logins from accounts having an empty password string.
253 </para></listitem>
254 <listitem><para><emphasis>dbg-pkgs:</emphasis>
255 Installs debug symbol packages for all packages installed
256 in a given image.
257 </para></listitem>
258 <listitem><para><emphasis>debug-tweaks:</emphasis>
259 Makes an image suitable for development (e.g.
260 allows root logins without passwords and enables
261 post-installation logging).
262 See the 'allow-empty-password', 'empty-root-password',
263 and 'post-install-logging' features in this list for
264 additional information.
265 </para></listitem>
266 <listitem><para><emphasis>dev-pkgs:</emphasis>
267 Installs development packages (headers and extra library
268 links) for all packages installed in a given image.
269 </para></listitem>
270 <listitem><para><emphasis>doc-pkgs:</emphasis> Installs
271 documentation packages for all packages installed in a
272 given image.
273 </para></listitem>
274 <listitem><para><emphasis>empty-root-password:</emphasis>
275 Sets the root password to an empty string, which allows
276 logins with a blank password.
277 </para></listitem>
278 <listitem><para><emphasis>package-management:</emphasis>
279 Installs package management tools and preserves the package
280 manager database.
281 </para></listitem>
282 <listitem><para><emphasis>post-install-logging:</emphasis>
283 Enables logging postinstall script runs to
284 the <filename>/var/log/postinstall.log</filename> file
285 on first boot of the image on the target system.
286 <note>
287 To make the <filename>/var/log</filename> directory
288 on the target persistent, use the
289 <link linkend='var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></link>
290 variable by setting it to "no".
291 </note>
292 </para></listitem>
293 <listitem><para><emphasis>ptest-pkgs:</emphasis>
294 Installs ptest packages for all ptest-enabled recipes.
295 </para></listitem>
296 <listitem><para><emphasis>read-only-rootfs:</emphasis>
297 Creates an image whose root filesystem is read-only.
298 See the
299 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
300 section in the Yocto Project Development Tasks Manual for
301 more information.
302 </para></listitem>
303 <listitem><para><emphasis>splash:</emphasis>
304 Enables showing a splash screen during boot.
305 By default, this screen is provided by
306 <filename>psplash</filename>, which does allow
307 customization.
308 If you prefer to use an alternative splash screen package,
309 you can do so by setting the <filename>SPLASH</filename>
310 variable to a different package name (or names) within the
311 image recipe or at the distro configuration level.
312 </para></listitem>
313 <listitem><para><emphasis>staticdev-pkgs:</emphasis>
314 Installs static development packages, which are
315 static libraries (i.e. <filename>*.a</filename> files), for
316 all packages installed in a given image.
317 </para></listitem>
318 </itemizedlist>
319 </para>
320
321 <para>
322 Some image features are available only when you inherit the
323 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
324 class.
325 The current list of these valid features is as follows:
326 <itemizedlist>
327 <listitem><para><emphasis>hwcodecs:</emphasis> Installs
328 hardware acceleration codecs.
329 </para></listitem>
330 <listitem><para><emphasis>nfs-server:</emphasis>
331 Installs an NFS server.
332 </para></listitem>
333 <listitem><para><emphasis>perf:</emphasis>
334 Installs profiling tools such as
335 <filename>perf</filename>, <filename>systemtap</filename>,
336 and <filename>LTTng</filename>.
337 For general information on user-space tools, see the
338 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
339 manual.
340 </para></listitem>
341 <listitem><para><emphasis>ssh-server-dropbear:</emphasis>
342 Installs the Dropbear minimal SSH server.
343 </para></listitem>
344 <listitem><para><emphasis>ssh-server-openssh:</emphasis>
345 Installs the OpenSSH SSH server, which is more
346 full-featured than Dropbear.
347 Note that if both the OpenSSH SSH server and the Dropbear
348 minimal SSH server are present in
349 <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
350 precedence and Dropbear will not be installed.
351 </para></listitem>
352 <listitem><para><emphasis>tools-debug:</emphasis>
353 Installs debugging tools such as
354 <filename>strace</filename> and <filename>gdb</filename>.
355 For information on GDB, see the
356 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
357 section in the Yocto Project Development Tasks Manual.
358 For information on tracing and profiling, see the
359 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
360 </para></listitem>
361 <listitem><para><emphasis>tools-sdk:</emphasis>
362 Installs a full SDK that runs on the device.
363 </para></listitem>
364 <listitem><para><emphasis>tools-testapps:</emphasis>
365 Installs device testing tools (e.g. touchscreen debugging).
366 </para></listitem>
367 <listitem><para><emphasis>x11:</emphasis>
368 Installs the X server.
369 </para></listitem>
370 <listitem><para><emphasis>x11-base:</emphasis>
371 Installs the X server with a minimal environment.
372 </para></listitem>
373 <listitem><para><emphasis>x11-sato:</emphasis>
374 Installs the OpenedHand Sato environment.
375 </para></listitem>
376 </itemizedlist>
377 </para>
378
379 </section>
380
381 <section id='ref-features-backfill'>
382 <title>Feature Backfilling</title>
383
384 <para>
385 Sometimes it is necessary in the OpenEmbedded build system to extend
386 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
387 or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
388 to control functionality that was previously enabled and not able
389 to be disabled.
390 For these cases, we need to add an
391 additional feature item to appear in one of these variables,
392 but we do not want to force developers who have existing values
393 of the variables in their configuration to add the new feature
394 in order to retain the same overall level of functionality.
395 Thus, the OpenEmbedded build system has a mechanism to
396 automatically "backfill" these added features into existing
397 distro or machine configurations.
398 You can see the list of features for which this is done by
399 finding the
400 <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
401 and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
402 variables in the <filename>meta/conf/bitbake.conf</filename> file.
403 </para>
404
405 <para>
406 Because such features are backfilled by default into all
407 configurations as described in the previous paragraph, developers
408 who wish to disable the new features need to be able to selectively
409 prevent the backfilling from occurring.
410 They can do this by adding the undesired feature or features to the
411 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
412 or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
413 variables for distro features and machine features respectively.
414 </para>
415
416 <para>
417 Here are two examples to help illustrate feature backfilling:
418 <itemizedlist>
419 <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
420 Previously, PulseAudio support was enabled within the Qt and
421 GStreamer frameworks.
422 Because of this, the feature is backfilled and thus
423 enabled for all distros through the
424 <filename>DISTRO_FEATURES_BACKFILL</filename>
425 variable in the <filename>meta/conf/bitbake.conf</filename> file.
426 However, your distro needs to disable the feature.
427 You can disable the feature without affecting
428 other existing distro configurations that need PulseAudio support
429 by adding "pulseaudio" to
430 <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
431 in your distro's <filename>.conf</filename> file.
432 Adding the feature to this variable when it also
433 exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
434 variable prevents the build system from adding the feature to
435 your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
436 the feature for that particular distro.</para></listitem>
437 <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
438 Previously, real time clock (RTC) support was enabled for all
439 target devices.
440 Because of this, the feature is backfilled and thus enabled
441 for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
442 variable in the <filename>meta/conf/bitbake.conf</filename> file.
443 However, your target device does not have this capability.
444 You can disable RTC support for your device without
445 affecting other machines that need RTC support
446 by adding the feature to your machine's
447 <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
448 list in the machine's <filename>.conf</filename> file.
449 Adding the feature to this variable when it also
450 exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
451 variable prevents the build system from adding the feature to
452 your configuration's <filename>MACHINE_FEATURES</filename>, effectively
453 disabling RTC support for that particular machine.</para></listitem>
454 </itemizedlist>
455 </para>
456 </section>
457</chapter>
458
459<!--
460vim: expandtab tw=80 ts=4 spell spelllang=en_gb
461-->
diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml
deleted file mode 100644
index 6f10a6fd2a..0000000000
--- a/documentation/ref-manual/ref-images.xml
+++ /dev/null
@@ -1,170 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-images'>
7 <title>Images</title>
8
9 <para>
10 The OpenEmbedded build system provides several example
11 images to satisfy different needs.
12 When you issue the <filename>bitbake</filename> command you provide a "top-level" recipe
13 that essentially begins the build for the type of image you want.
14 </para>
15
16 <note>
17 Building an image without GNU General Public License Version 3 (GPLv3),
18 GNU Lesser General Public License Version 3 (LGPLv3), and the
19 GNU Affero General Public License Version 3 (AGPL-3.0) components
20 is only supported for minimal and base images.
21 Furthermore, if you are going to build an image using non-GPLv3 and
22 similarly licensed components, you must make the following changes in
23 the <filename>local.conf</filename> file before using the BitBake
24 command to build the minimal or base image:
25 <literallayout class='monospaced'>
26 1. Comment out the EXTRA_IMAGE_FEATURES line
27 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
28 </literallayout>
29 </note>
30
31 <para>
32 From within the <filename>poky</filename> Git repository, you can use
33 the following command to display the list of directories within the
34 <link linkend='source-directory'>Source Directory</link>
35 that contain image recipe files:
36 <literallayout class='monospaced'>
37 $ ls meta*/recipes*/images/*.bb
38 </literallayout>
39 </para>
40
41 <para>
42 Following is a list of supported recipes:
43 <itemizedlist>
44 <listitem><para>
45 <filename>build-appliance-image</filename>:
46 An example virtual machine that contains all the pieces
47 required to run builds using the build system as well as the
48 build system itself.
49 You can boot and run the image using either the
50 <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink>
51 or
52 <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
53 For more information on this image, see the
54 <ulink url='&YOCTO_HOME_URL;/software-item/build-appliance/'>Build Appliance</ulink>
55 page on the Yocto Project website.
56 </para></listitem>
57 <listitem><para><filename>core-image-base</filename>:
58 A console-only image that fully supports the target device hardware.</para></listitem>
59 <listitem><para><filename>core-image-clutter</filename>:
60 An image with support for the Open GL-based toolkit Clutter, which enables development of
61 rich and animated graphical user interfaces.</para></listitem>
62 <listitem><para><filename>core-image-full-cmdline</filename>:
63 A console-only image with more full-featured Linux system
64 functionality installed.</para></listitem>
65 <listitem><para><filename>core-image-lsb</filename>:
66 An image that conforms to the Linux Standard Base (LSB)
67 specification.
68 This image requires a distribution configuration that
69 enables LSB compliance (e.g. <filename>poky-lsb</filename>).
70 If you build <filename>core-image-lsb</filename> without that
71 configuration, the image will not be LSB-compliant.
72 </para></listitem>
73 <listitem><para><filename>core-image-lsb-dev</filename>:
74 A <filename>core-image-lsb</filename> image that is suitable for development work
75 using the host.
76 The image includes headers and libraries you can use in a host development
77 environment.
78 This image requires a distribution configuration that
79 enables LSB compliance (e.g. <filename>poky-lsb</filename>).
80 If you build <filename>core-image-lsb-dev</filename> without that
81 configuration, the image will not be LSB-compliant.
82 </para></listitem>
83 <listitem><para><filename>core-image-lsb-sdk</filename>:
84 A <filename>core-image-lsb</filename> that includes everything in
85 the cross-toolchain but also includes development headers and libraries
86 to form a complete standalone SDK.
87 This image requires a distribution configuration that
88 enables LSB compliance (e.g. <filename>poky-lsb</filename>).
89 If you build <filename>core-image-lsb-sdk</filename> without that
90 configuration, the image will not be LSB-compliant.
91 This image is suitable for development using the target.</para></listitem>
92 <listitem><para><filename>core-image-minimal</filename>:
93 A small image just capable of allowing a device to boot.</para></listitem>
94 <listitem><para><filename>core-image-minimal-dev</filename>:
95 A <filename>core-image-minimal</filename> image suitable for development work
96 using the host.
97 The image includes headers and libraries you can use in a host development
98 environment.
99 </para></listitem>
100 <listitem><para id='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename>:
101 A <filename>core-image-minimal</filename> image that has the Minimal RAM-based
102 Initial Root Filesystem (initramfs) as part of the kernel,
103 which allows the system to find the first "init" program more efficiently.
104 See the
105 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
106 variable for additional information helpful when working with
107 initramfs images.
108 </para></listitem>
109 <listitem><para><filename>core-image-minimal-mtdutils</filename>:
110 A <filename>core-image-minimal</filename> image that has support
111 for the Minimal MTD Utilities, which let the user interact with the
112 MTD subsystem in the kernel to perform operations on flash devices.
113 </para></listitem>
114 <listitem><para><filename>core-image-rt</filename>:
115 A <filename>core-image-minimal</filename> image plus a real-time test suite and
116 tools appropriate for real-time use.</para></listitem>
117 <listitem><para><filename>core-image-rt-sdk</filename>:
118 A <filename>core-image-rt</filename> image that includes everything in
119 the cross-toolchain.
120 The image also includes development headers and libraries to form a complete
121 stand-alone SDK and is suitable for development using the target.
122 </para></listitem>
123 <listitem><para><filename>core-image-sato</filename>:
124 An image with Sato support, a mobile environment and visual style that works well
125 with mobile devices.
126 The image supports X11 with a Sato theme and applications such as
127 a terminal, editor, file manager, media player, and so forth.
128 </para></listitem>
129 <listitem><para><filename>core-image-sato-dev</filename>:
130 A <filename>core-image-sato</filename> image suitable for development
131 using the host.
132 The image includes libraries needed to build applications on the device itself,
133 testing and profiling tools, and debug symbols.
134 This image was formerly <filename>core-image-sdk</filename>.
135 </para></listitem>
136 <listitem><para><filename>core-image-sato-sdk</filename>:
137 A <filename>core-image-sato</filename> image that includes everything in
138 the cross-toolchain.
139 The image also includes development headers and libraries to form a complete standalone SDK
140 and is suitable for development using the target.</para></listitem>
141 <listitem><para><filename>core-image-testmaster</filename>:
142 A "master" image designed to be used for automated runtime testing.
143 Provides a "known good" image that is deployed to a separate
144 partition so that you can boot into it and use it to deploy a
145 second image to be tested.
146 You can find more information about runtime testing in the
147 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
148 section in the Yocto Project Development Tasks Manual.
149 </para></listitem>
150 <listitem><para><filename>core-image-testmaster-initramfs</filename>:
151 A RAM-based Initial Root Filesystem (initramfs) image tailored for
152 use with the <filename>core-image-testmaster</filename> image.
153 </para></listitem>
154 <listitem><para><filename>core-image-weston</filename>:
155 A very basic Wayland image with a terminal.
156 This image provides the Wayland protocol libraries and the
157 reference Weston compositor.
158 For more information, see the
159 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-using-wayland-and-weston'>Using Wayland and Weston</ulink>"
160 section in the Yocto Project Development Tasks Manual.
161 </para></listitem>
162 <listitem><para><filename>core-image-x11</filename>:
163 A very basic X11 image with a terminal.
164 </para></listitem>
165 </itemizedlist>
166 </para>
167</chapter>
168<!--
169vim: expandtab tw=80 ts=4
170-->
diff --git a/documentation/ref-manual/ref-kickstart.xml b/documentation/ref-manual/ref-kickstart.xml
deleted file mode 100644
index 45db1c0ff8..0000000000
--- a/documentation/ref-manual/ref-kickstart.xml
+++ /dev/null
@@ -1,335 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-kickstart'>
7<title>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</title>
8
9 <section id='openembedded-kickstart-wks-reference'>
10 <title>Introduction</title>
11
12 <para>
13 The current Wic implementation supports only the basic kickstart
14 partitioning commands:
15 <filename>partition</filename> (or <filename>part</filename>
16 for short) and <filename>bootloader</filename>.
17 <note>
18 Future updates will implement more commands and options.
19 If you use anything that is not specifically supported, results
20 can be unpredictable.
21 </note>
22 </para>
23
24 <para>
25 This chapter provides a reference on the available kickstart
26 commands.
27 The information lists the commands, their syntax, and meanings.
28 Kickstart commands are based on the Fedora kickstart versions but
29 with modifications to reflect Wic capabilities.
30 You can see the original documentation for those commands at the
31 following link:
32 <literallayout class='monospaced'>
33 <ulink url='http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html'>http://pykickstart.readthedocs.io/en/latest/kickstart-docs.html</ulink>
34 </literallayout>
35 </para>
36 </section>
37
38 <section id='command-part-or-partition'>
39 <title>Command: part or partition</title>
40
41 <para>
42 Either of these commands creates a partition on the system and uses
43 the following syntax:
44 <literallayout class='monospaced'>
45 part [<replaceable>mntpoint</replaceable>]
46 partition [<replaceable>mntpoint</replaceable>]
47 </literallayout>
48 If you do not provide <replaceable>mntpoint</replaceable>, Wic
49 creates a partition but does not mount it.
50 </para>
51
52 <para>
53 The <filename><replaceable>mntpoint</replaceable></filename> is
54 where the partition is mounted and must be in one of the
55 following forms:
56 <itemizedlist>
57 <listitem><para>
58 <filename>/<replaceable>path</replaceable></filename>:
59 For example, "/", "/usr", or "/home"
60 </para></listitem>
61 <listitem><para>
62 <filename>swap</filename>:
63 The created partition is used as swap space
64 </para></listitem>
65 </itemizedlist>
66 </para>
67
68 <para>
69 Specifying a <replaceable>mntpoint</replaceable> causes the
70 partition to automatically be mounted.
71 Wic achieves this by adding entries to the filesystem table (fstab)
72 during image generation.
73 In order for Wic to generate a valid fstab, you must also provide
74 one of the <filename>--ondrive</filename>,
75 <filename>--ondisk</filename>, or
76 <filename>--use-uuid</filename> partition options as part of the
77 command.
78 <note>
79 The mount program must understand the PARTUUID syntax you use
80 with <filename>--use-uuid</filename> and non-root
81 <replaceable>mountpoint</replaceable>, including swap.
82 The busybox versions of these application are currently
83 excluded.
84 </note>
85 Here is an example that uses "/" as the
86 <replaceable>mountpoint</replaceable>.
87 The command uses <filename>--ondisk</filename> to force the
88 partition onto the
89 <filename>sdb</filename> disk:
90 <literallayout class='monospaced'>
91 part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024
92 </literallayout>
93 </para>
94
95 <para>
96 Here is a list that describes other supported options you can use
97 with the <filename>part</filename> and
98 <filename>partition</filename> commands:
99 <itemizedlist>
100 <listitem><para>
101 <emphasis><filename>--size</filename>:</emphasis>
102 The minimum partition size in MBytes.
103 Specify an integer value such as 500.
104 Do not append the number with "MB".
105 You do not need this option if you use
106 <filename>--source</filename>.
107 </para></listitem>
108 <listitem><para>
109 <emphasis><filename>--fixed-size</filename>:</emphasis>
110 The exact partition size in MBytes.
111 You cannot specify with <filename>--size</filename>.
112 An error occurs when assembling the disk image if the
113 partition data is larger than
114 <filename>--fixed-size</filename>.
115 </para></listitem>
116 <listitem><para>
117 <emphasis><filename>--source</filename>:</emphasis>
118 This option is a Wic-specific option that names the source
119 of the data that populates the partition.
120 The most common value for this option is "rootfs", but you
121 can use any value that maps to a valid source plugin.
122 For information on the source plugins, see the
123 "<ulink url='&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plugin-interface'>Using the Wic Plugins Interface</ulink>"
124 section in the Yocto Project Development Tasks Manual.
125 </para>
126
127 <para>If you use <filename>--source rootfs</filename>, Wic
128 creates a partition as large as needed and fills it with
129 the contents of the root filesystem pointed to by the
130 <filename>-r</filename> command-line option or the
131 equivalent rootfs derived from the <filename>-e</filename>
132 command-line option.
133 The filesystem type used to create the partition is driven
134 by the value of the <filename>--fstype</filename> option
135 specified for the partition.
136 See the entry on <filename>--fstype</filename> that follows
137 for more information.</para>
138
139 <para>If you use
140 <filename>--source <replaceable>plugin-name</replaceable></filename>,
141 Wic creates a partition as large as needed and fills it
142 with the contents of the partition that is generated by the
143 specified plugin name using the data pointed to by the
144 <filename>-r</filename> command-line option or the
145 equivalent rootfs derived from the <filename>-e</filename>
146 command-line option.
147 Exactly what those contents are and filesystem type used are
148 dependent on the given plugin implementation.
149 </para>
150
151 <para>If you do not use the <filename>--source</filename>
152 option, the <filename>wic</filename> command creates an
153 empty partition.
154 Consequently, you must use the <filename>--size</filename>
155 option to specify the size of the empty partition.
156 </para></listitem>
157 <listitem><para>
158 <emphasis><filename>--ondisk</filename> or <filename>--ondrive</filename>:</emphasis>
159 Forces the partition to be created on a particular disk.
160 </para></listitem>
161 <listitem><para>
162 <emphasis><filename>--fstype</filename>:</emphasis>
163 Sets the file system type for the partition.
164 Valid values are:
165 <itemizedlist>
166 <listitem><para>
167 <filename>ext4</filename>
168 </para></listitem>
169 <listitem><para>
170 <filename>ext3</filename>
171 </para></listitem>
172 <listitem><para>
173 <filename>ext2</filename>
174 </para></listitem>
175 <listitem><para>
176 <filename>btrfs</filename>
177 </para></listitem>
178 <listitem><para>
179 <filename>squashfs</filename>
180 </para></listitem>
181 <listitem><para>
182 <filename>swap</filename>
183 </para></listitem>
184 </itemizedlist>
185 </para></listitem>
186 <listitem><para>
187 <emphasis><filename>--fsoptions</filename>:</emphasis>
188 Specifies a free-form string of options to be used when
189 mounting the filesystem.
190 This string is copied into the
191 <filename>/etc/fstab</filename> file of the installed
192 system and should be enclosed in quotes.
193 If not specified, the default string is "defaults".
194 </para></listitem>
195 <listitem><para>
196 <emphasis><filename>--label label</filename>:</emphasis>
197 Specifies the label to give to the filesystem to be made on
198 the partition.
199 If the given label is already in use by another filesystem,
200 a new label is created for the partition.
201 </para></listitem>
202 <listitem><para>
203 <emphasis><filename>--active</filename>:</emphasis>
204 Marks the partition as active.
205 </para></listitem>
206 <listitem><para>
207 <emphasis><filename>--align (in KBytes)</filename>:</emphasis>
208 This option is a Wic-specific option that says to start
209 partitions on boundaries given
210 <replaceable>x</replaceable> KBytes.
211 </para></listitem>
212 <listitem><para>
213 <emphasis><filename>--no-table</filename>:</emphasis>
214 This option is a Wic-specific option.
215 Using the option reserves space for the partition and
216 causes it to become populated.
217 However, the partition is not added to the partition table.
218 </para></listitem>
219 <listitem><para>
220 <emphasis><filename>--exclude-path</filename>:</emphasis>
221 This option is a Wic-specific option that excludes the given
222 relative path from the resulting image.
223 This option is only effective with the rootfs source
224 plugin.
225 </para></listitem>
226 <listitem><para>
227 <emphasis><filename>--extra-space</filename>:</emphasis>
228 This option is a Wic-specific option that adds extra space
229 after the space filled by the content of the partition.
230 The final size can exceed the size specified by the
231 <filename>--size</filename> option.
232 The default value is 10 Mbytes.
233 </para></listitem>
234 <listitem><para>
235 <emphasis><filename>--overhead-factor</filename>:</emphasis>
236 This option is a Wic-specific option that multiplies the
237 size of the partition by the option's value.
238 You must supply a value greater than or equal to "1".
239 The default value is "1.3".
240 </para></listitem>
241 <listitem><para>
242 <emphasis><filename>--part-name</filename>:</emphasis>
243 This option is a Wic-specific option that specifies a name
244 for GPT partitions.
245 </para></listitem>
246 <listitem><para>
247 <emphasis><filename>--part-type</filename>:</emphasis>
248 This option is a Wic-specific option that specifies the
249 partition type globally unique identifier (GUID) for GPT
250 partitions.
251 You can find the list of partition type GUIDs at
252 <ulink url='http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs'></ulink>.
253 </para></listitem>
254 <listitem><para>
255 <emphasis><filename>--use-uuid</filename>:</emphasis>
256 This option is a Wic-specific option that causes Wic to
257 generate a random GUID for the partition.
258 The generated identifier is used in the bootloader
259 configuration to specify the root partition.
260 </para></listitem>
261 <listitem><para>
262 <emphasis><filename>--uuid</filename>:</emphasis>
263 This option is a Wic-specific option that specifies the
264 partition UUID.
265 </para></listitem>
266 <listitem><para>
267 <emphasis><filename>--fsuuid</filename>:</emphasis>
268 This option is a Wic-specific option that specifies the
269 filesystem UUID.
270 You can generate or modify
271 <link linkend='var-WKS_FILE'><filename>WKS_FILE</filename></link>
272 with this option if a preconfigured filesystem UUID is
273 added to the kernel command line in the bootloader
274 configuration before you run Wic.
275 </para></listitem>
276 <listitem><para>
277 <emphasis><filename>--system-id</filename>:</emphasis>
278 This option is a Wic-specific option that specifies the
279 partition system ID, which is a one byte long, hexadecimal
280 parameter with or without the 0x prefix.
281 </para></listitem>
282 <listitem><para>
283 <emphasis><filename>--mkfs-extraopts</filename>:</emphasis>
284 This option specifies additional options to pass to the
285 <filename>mkfs</filename> utility.
286 Some default options for certain filesystems do not take
287 effect.
288 See Wic's help on kickstart
289 (i.e. <filename>wic help kickstart</filename>).
290 </para></listitem>
291 </itemizedlist>
292 </para>
293 </section>
294
295 <section id='command-bootloader'>
296 <title>Command: bootloader</title>
297
298 <para>
299 This command specifies how the bootloader should be configured and
300 supports the following options:
301 <note>
302 Bootloader functionality and boot partitions are implemented by
303 the various <filename>--source</filename> plugins that
304 implement bootloader functionality.
305 The bootloader command essentially provides a means of
306 modifying bootloader configuration.
307 </note>
308 <itemizedlist>
309 <listitem><para>
310 <emphasis><filename>--timeout</filename>:</emphasis>
311 Specifies the number of seconds before the bootloader times
312 out and boots the default option.
313 </para></listitem>
314 <listitem><para>
315 <emphasis><filename>--append</filename>:</emphasis>
316 Specifies kernel parameters.
317 These parameters will be added to the syslinux
318 <filename>APPEND</filename> or <filename>grub</filename>
319 kernel command line.
320 </para></listitem>
321 <listitem><para>
322 <emphasis><filename>--configfile</filename>:</emphasis>
323 Specifies a user-defined configuration file for the
324 bootloader.
325 You can provide a full pathname for the file or a file that
326 exists in the <filename>canned-wks</filename> folder.
327 This option overrides all other bootloader options.
328 </para></listitem>
329 </itemizedlist>
330 </para>
331 </section>
332</chapter>
333<!--
334vim: expandtab tw=80 ts=4
335-->
diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl
deleted file mode 100644
index 3181f618e2..0000000000
--- a/documentation/ref-manual/ref-manual-customization.xsl
+++ /dev/null
@@ -1,31 +0,0 @@
1<?xml version='1.0'?>
2<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
3
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">
5
6 <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
7
8<!--
9
10 <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
11
12 <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
13
14-->
15
16 <xsl:include href="../template/permalinks.xsl"/>
17 <xsl:include href="../template/section.title.xsl"/>
18 <xsl:include href="../template/component.title.xsl"/>
19 <xsl:include href="../template/division.title.xsl"/>
20 <xsl:include href="../template/formal.object.heading.xsl"/>
21 <xsl:include href="../template/gloss-permalinks.xsl"/>
22 <xsl:include href="../template/qa-code-permalinks.xsl"/>
23
24 <xsl:param name="html.stylesheet" select="'ref-style.css'" />
25 <xsl:param name="chapter.autolabel" select="1" />
26 <xsl:param name="appendix.autolabel" select="A" />
27 <xsl:param name="section.autolabel" select="1" />
28 <xsl:param name="section.label.includes.component.label" select="1" />
29 <xsl:param name="generate.id.attributes" select="1" />
30
31</xsl:stylesheet>
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
deleted file mode 100755
index 9a914f19cf..0000000000
--- a/documentation/ref-manual/ref-manual.xml
+++ /dev/null
@@ -1,232 +0,0 @@
1<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<book id='ref-manual' lang='en'
6 xmlns:xi="http://www.w3.org/2003/XInclude"
7 xmlns="http://docbook.org/ns/docbook"
8 >
9 <bookinfo>
10
11 <mediaobject>
12 <imageobject>
13 <imagedata fileref='figures/poky-title.png'
14 format='SVG'
15 align='left' scalefit='1' width='100%'/>
16 </imageobject>
17 </mediaobject>
18
19 <title>
20 Yocto Project Reference Manual
21 </title>
22
23 <authorgroup>
24 <author>
25 <affiliation>
26 <orgname>&ORGNAME;</orgname>
27 </affiliation>
28 <email>&ORGEMAIL;</email>
29 </author>
30
31 </authorgroup>
32
33 <revhistory>
34 <revision>
35 <revnumber>4.0+git</revnumber>
36 <date>November 2010</date>
37 <revremark>The initial document released with the Yocto Project 0.9 Release</revremark>
38 </revision>
39 <revision>
40 <revnumber>1.0</revnumber>
41 <date>April 2011</date>
42 <revremark>Released with the Yocto Project 1.0 Release.</revremark>
43 </revision>
44 <revision>
45 <revnumber>1.1</revnumber>
46 <date>October 2011</date>
47 <revremark>Released with the Yocto Project 1.1 Release.</revremark>
48 </revision>
49 <revision>
50 <revnumber>1.2</revnumber>
51 <date>April 2012</date>
52 <revremark>Released with the Yocto Project 1.2 Release.</revremark>
53 </revision>
54 <revision>
55 <revnumber>1.3</revnumber>
56 <date>October 2012</date>
57 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
58 </revision>
59 <revision>
60 <revnumber>1.4</revnumber>
61 <date>April 2013</date>
62 <revremark>Released with the Yocto Project 1.4 Release.</revremark>
63 </revision>
64 <revision>
65 <revnumber>1.5</revnumber>
66 <date>October 2013</date>
67 <revremark>Released with the Yocto Project 1.5 Release.</revremark>
68 </revision>
69 <revision>
70 <revnumber>1.6</revnumber>
71 <date>April 2014</date>
72 <revremark>Released with the Yocto Project 1.6 Release.</revremark>
73 </revision>
74 <revision>
75 <revnumber>1.7</revnumber>
76 <date>October 2014</date>
77 <revremark>Released with the Yocto Project 1.7 Release.</revremark>
78 </revision>
79 <revision>
80 <revnumber>1.8</revnumber>
81 <date>April 2015</date>
82 <revremark>Released with the Yocto Project 1.8 Release.</revremark>
83 </revision>
84 <revision>
85 <revnumber>2.0</revnumber>
86 <date>October 2015</date>
87 <revremark>Released with the Yocto Project 2.0 Release.</revremark>
88 </revision>
89 <revision>
90 <revnumber>2.1</revnumber>
91 <date>April 2016</date>
92 <revremark>Released with the Yocto Project 2.1 Release.</revremark>
93 </revision>
94 <revision>
95 <revnumber>2.2</revnumber>
96 <date>October 2016</date>
97 <revremark>Released with the Yocto Project 2.2 Release.</revremark>
98 </revision>
99 <revision>
100 <revnumber>2.3</revnumber>
101 <date>May 2017</date>
102 <revremark>Released with the Yocto Project 2.3 Release.</revremark>
103 </revision>
104 <revision>
105 <revnumber>2.4</revnumber>
106 <date>October 2017</date>
107 <revremark>Released with the Yocto Project 2.4 Release.</revremark>
108 </revision>
109 <revision>
110 <revnumber>2.5</revnumber>
111 <date>May 2018</date>
112 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
113 </revision>
114 <revision>
115 <revnumber>2.6</revnumber>
116 <date>November 2018</date>
117 <revremark>Released with the Yocto Project 2.6 Release.</revremark>
118 </revision>
119 <revision>
120 <revnumber>2.7</revnumber>
121 <date>May 2019</date>
122 <revremark>Released with the Yocto Project 2.7 Release.</revremark>
123 </revision>
124 <revision>
125 <revnumber>3.0</revnumber>
126 <date>October 2019</date>
127 <revremark>Released with the Yocto Project 3.0 Release.</revremark>
128 </revision>
129 <revision>
130 <revnumber>3.1</revnumber>
131 <date>&REL_MONTH_YEAR;</date>
132 <revremark>Released with the Yocto Project 3.1 Release.</revremark>
133 </revision>
134 </revhistory>
135
136 <copyright>
137 <year>&COPYRIGHT_YEAR;</year>
138 <holder>Linux Foundation</holder>
139 </copyright>
140
141 <legalnotice>
142 <para>
143 Permission is granted to copy, distribute and/or modify this document under
144 the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
145 </para>
146 <note><title>Manual Notes</title>
147 <itemizedlist>
148 <listitem><para>
149 This version of the
150 <emphasis>Yocto Project Reference Manual</emphasis>
151 is for the &YOCTO_DOC_VERSION; release of the
152 Yocto Project.
153 To be sure you have the latest version of the manual
154 for this release, go to the
155 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
156 and select the manual from that site.
157 Manuals from the site are more up-to-date than manuals
158 derived from the Yocto Project released TAR files.
159 </para></listitem>
160 <listitem><para>
161 If you located this manual through a web search, the
162 version of the manual might not be the one you want
163 (e.g. the search might have returned a manual much
164 older than the Yocto Project version with which you
165 are working).
166 You can see all Yocto Project major releases by
167 visiting the
168 <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
169 page.
170 If you need a version of this manual for a different
171 Yocto Project release, visit the
172 <ulink url='&YOCTO_DOCS_URL;'>Yocto Project documentation page</ulink>
173 and select the manual set by using the
174 "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
175 pull-down menus.
176 </para></listitem>
177 <listitem>
178 <para>
179 To report any inaccuracies or problems with this
180 (or any other Yocto Project) manual, send an email to
181 the Yocto Project documentation mailing list at
182 <filename>docs@lists.yoctoproject.org</filename> or
183 log into the freenode <filename>#yocto</filename> channel.
184 </para>
185 </listitem>
186 </itemizedlist>
187 </note>
188 </legalnotice>
189
190 </bookinfo>
191
192 <xi:include href="ref-system-requirements.xml"/>
193
194 <xi:include href="ref-terms.xml"/>
195
196 <xi:include href="ref-release-process.xml"/>
197
198 <xi:include href="migration.xml"/>
199
200 <xi:include href="ref-structure.xml"/>
201
202 <xi:include href="ref-classes.xml"/>
203
204 <xi:include href="ref-tasks.xml"/>
205
206 <xi:include href="ref-devtool-reference.xml"/>
207
208 <xi:include href="ref-kickstart.xml"/>
209
210 <xi:include href="ref-qa-checks.xml"/>
211
212 <xi:include href="ref-images.xml"/>
213
214 <xi:include href="ref-features.xml"/>
215
216 <xi:include href="ref-variables.xml"/>
217
218 <xi:include href="ref-varlocality.xml"/>
219
220 <xi:include href="faq.xml"/>
221
222 <xi:include href="resources.xml"/>
223
224<!-- <index id='index'>
225 <title>Index</title>
226 </index>
227-->
228
229</book>
230<!--
231vim: expandtab tw=80 ts=4
232-->
diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml
deleted file mode 100644
index 0071e4a55d..0000000000
--- a/documentation/ref-manual/ref-qa-checks.xml
+++ /dev/null
@@ -1,1225 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-qa-checks'>
7<title>QA Error and Warning Messages</title>
8
9<section id='qa-introduction'>
10 <title>Introduction</title>
11
12 <para>
13 When building a recipe, the OpenEmbedded build system performs
14 various QA checks on the output to ensure that common issues are
15 detected and reported.
16 Sometimes when you create a new recipe to build new software,
17 it will build with no problems.
18 When this is not the case, or when you have QA issues building any
19 software, it could take a little time to resolve them.
20 </para>
21
22 <para>
23 While it is tempting to ignore a QA message or even to
24 disable QA checks, it is best to try and resolve any
25 reported QA issues.
26 This chapter provides a list of the QA messages and brief explanations
27 of the issues you could encounter so that you can properly resolve
28 problems.
29 </para>
30
31 <para>
32 The next section provides a list of all QA error and warning
33 messages based on a default configuration.
34 Each entry provides the message or error form along with an
35 explanation.
36 <note>
37 <title>Notes</title>
38 <itemizedlist>
39 <listitem><para>
40 At the end of each message, the name of the associated
41 QA test (as listed in the
42 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
43 section) appears within square brackets.
44 </para></listitem>
45 <listitem><para>
46 As mentioned, this list of error and warning messages is for
47 QA checks only.
48 The list does not cover all possible build errors or
49 warnings you could encounter.
50 </para></listitem>
51 <listitem><para>
52 Because some QA checks are disabled by default, this list
53 does not include all possible QA check errors and warnings.
54 </para></listitem>
55 </itemizedlist>
56 </note>
57 </para>
58</section>
59
60<section id='qa-errors-and-warnings'>
61 <title>Errors and Warnings</title>
62
63<!--
64This section uses the <para><code> construct to enable permalinks for the
65various QA issue and warning messages. The file templates/qa-code-permalinks.xsl
66is used to locate the construct and generate the permalink. This solution
67leverages the fact that right now this section in the ref-manual is the only
68place is all the YP docs that uses the <para><code> construct. If, in the
69future, that construct were to appear in the ref-manual, a generic permalink
70would be generated for the text between <code></code>. If a better solution
71can be found then it should be implemented. I can't find one at the moment.
72-->
73
74 <para>
75 <itemizedlist>
76 <listitem>
77 <para id='qa-issue-libexec'>
78 <code>
79 &lt;packagename&gt;: &lt;path&gt; is using libexec please relocate to &lt;libexecdir&gt; [libexec]
80 </code>
81 </para>
82
83 <para>
84 The specified package contains files in
85 <filename>/usr/libexec</filename> when the distro
86 configuration uses a different path for
87 <filename>&lt;libexecdir&gt;</filename>
88 By default, <filename>&lt;libexecdir&gt;</filename> is
89 <filename>$prefix/libexec</filename>.
90 However, this default can be changed (e.g.
91 <filename>${libdir}</filename>).
92 </para>
93
94 <para>
95 &nbsp;
96 </para>
97 </listitem>
98 </itemizedlist>
99 </para>
100
101 <para>
102 <itemizedlist>
103 <listitem>
104 <para id='qa-issue-rpaths'>
105 <code>
106 package &lt;packagename&gt; contains bad RPATH &lt;rpath&gt; in file &lt;file&gt; [rpaths]
107 </code>
108 </para>
109
110 <para>
111 The specified binary produced by the recipe contains dynamic
112 library load paths (rpaths) that contain build system paths
113 such as
114 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
115 which are incorrect for the target and could potentially
116 be a security issue.
117 Check for bad <filename>-rpath</filename> options being
118 passed to the linker in your
119 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
120 log.
121 Depending on the build system used by the software being
122 built, there might be a configure option to disable rpath
123 usage completely within the build of the software.
124 </para>
125
126 <para>
127 &nbsp;
128 </para>
129 </listitem>
130 </itemizedlist>
131 </para>
132
133 <para>
134 <itemizedlist>
135 <listitem>
136 <para id='qa-issue-useless-rpaths'>
137 <code>
138 &lt;packagename&gt;: &lt;file&gt; contains probably-redundant RPATH &lt;rpath&gt; [useless-rpaths]
139 </code>
140 </para>
141
142 <para>
143 The specified binary produced by the recipe contains dynamic
144 library load paths (rpaths) that on a standard system are
145 searched by default by the linker (e.g.
146 <filename>/lib</filename> and <filename>/usr/lib</filename>).
147 While these paths will not cause any breakage, they do waste
148 space and are unnecessary.
149 Depending on the build system used by the software being
150 built, there might be a configure option to disable rpath
151 usage completely within the build of the software.
152 </para>
153
154 <para>
155 &nbsp;
156 </para>
157 </listitem>
158 </itemizedlist>
159 </para>
160
161 <para>
162 <itemizedlist>
163 <listitem>
164 <para id='qa-issue-file-rdeps'>
165 <code>
166 &lt;packagename&gt; requires &lt;files&gt;, but no providers in its RDEPENDS [file-rdeps]
167 </code>
168 </para>
169
170 <para>
171 A file-level dependency has been identified from the
172 specified package on the specified files, but there is
173 no explicit corresponding entry in
174 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
175 If particular files are required at runtime then
176 <filename>RDEPENDS</filename> should be declared in the
177 recipe to ensure the packages providing them are built.
178 </para>
179
180 <para>
181 &nbsp;
182 </para>
183 </listitem>
184 </itemizedlist>
185 </para>
186
187 <para>
188 <itemizedlist>
189 <listitem>
190 <para id='qa-issue-build-deps'>
191 <code>
192 &lt;packagename1&gt; rdepends on &lt;packagename2&gt;, but it isn't a build dependency? [build-deps]
193 </code>
194 </para>
195
196 <para>
197 A runtime dependency exists between the two specified
198 packages, but there is nothing explicit within the recipe
199 to enable the OpenEmbedded build system to ensure that
200 dependency is satisfied.
201 This condition is usually triggered by an
202 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
203 value being added at the packaging stage rather than up
204 front, which is usually automatic based on the contents of
205 the package.
206 In most cases, you should change the recipe to add an
207 explicit <filename>RDEPENDS</filename> for the dependency.
208 </para>
209
210 <para>
211 &nbsp;
212 </para>
213 </listitem>
214 </itemizedlist>
215 </para>
216
217 <para>
218 <itemizedlist>
219 <listitem>
220 <para id='qa-issue-dev-so'>
221 <code>
222 non -dev/-dbg/nativesdk- package contains symlink .so: &lt;packagename&gt; path '&lt;path&gt;' [dev-so]
223 </code>
224 </para>
225
226 <para>
227 Symlink <filename>.so</filename> files are for development
228 only, and should therefore go into the
229 <filename>-dev</filename> package.
230 This situation might occur if you add
231 <filename>*.so*</filename> rather than
232 <filename>*.so.*</filename> to a non-dev package.
233 Change
234 <link linkend='var-FILES'><filename>FILES</filename></link>
235 (and possibly
236 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
237 such that the specified <filename>.so</filename> file goes
238 into an appropriate <filename>-dev</filename> package.
239 </para>
240
241 <para>
242 &nbsp;
243 </para>
244 </listitem>
245 </itemizedlist>
246 </para>
247
248 <para>
249 <itemizedlist>
250 <listitem>
251 <para id='qa-issue-staticdev'>
252 <code>
253 non -staticdev package contains static .a library: &lt;packagename&gt; path '&lt;path&gt;' [staticdev]
254 </code>
255 </para>
256
257 <para>
258 Static <filename>.a</filename> library files should go into
259 a <filename>-staticdev</filename> package.
260 Change
261 <link linkend='var-FILES'><filename>FILES</filename></link>
262 (and possibly
263 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
264 such that the specified <filename>.a</filename> file goes
265 into an appropriate <filename>-staticdev</filename> package.
266 </para>
267
268 <para>
269 &nbsp;
270 </para>
271 </listitem>
272 </itemizedlist>
273 </para>
274
275 <para>
276 <itemizedlist>
277 <listitem>
278 <para id='qa-issue-libdir'>
279 <code>
280 &lt;packagename&gt;: found library in wrong location [libdir]
281 </code>
282 </para>
283
284 <para>
285 The specified file may have been installed into an incorrect
286 (possibly hardcoded) installation path.
287 For example, this test will catch recipes that install
288 <filename>/lib/bar.so</filename> when
289 <filename>${base_libdir}</filename> is "lib32".
290 Another example is when recipes install
291 <filename>/usr/lib64/foo.so</filename> when
292 <filename>${libdir}</filename> is "/usr/lib".
293 False positives occasionally exist.
294 For these cases add "libdir" to
295 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
296 for the package.
297 </para>
298
299 <para>
300 &nbsp;
301 </para>
302 </listitem>
303 </itemizedlist>
304 </para>
305
306 <para>
307 <itemizedlist>
308 <listitem>
309 <para id='qa-issue-debug-files'>
310 <code>
311 non debug package contains .debug directory: &lt;packagename&gt; path &lt;path&gt; [debug-files]
312 </code>
313 </para>
314
315 <para>
316 The specified package contains a
317 <filename>.debug</filename> directory, which should not
318 appear in anything but the <filename>-dbg</filename>
319 package.
320 This situation might occur if you add a path which contains
321 a <filename>.debug</filename> directory and do not
322 explicitly add the <filename>.debug</filename> directory
323 to the <filename>-dbg</filename> package.
324 If this is the case, add the <filename>.debug</filename>
325 directory explicitly to
326 <filename>FILES_${PN}-dbg</filename>.
327 See
328 <link linkend='var-FILES'><filename>FILES</filename></link>
329 for additional information on <filename>FILES</filename>.
330 </para>
331
332 <para>
333 &nbsp;
334 </para>
335 </listitem>
336 </itemizedlist>
337 </para>
338
339 <para>
340 <itemizedlist>
341 <listitem>
342 <para id='qa-issue-arch'>
343 <code>
344 Architecture did not match (&lt;machine_arch&gt; to &lt;file_arch&gt;) on &lt;file&gt; [arch]
345 </code>
346 </para>
347
348 <para>
349 By default, the OpenEmbedded build system checks the
350 Executable and Linkable Format (ELF) type, bit size, and
351 endianness of any binaries to ensure they match the
352 target architecture.
353 This test fails if any binaries do not match the type since
354 there would be an incompatibility.
355 The test could indicate that the wrong compiler or compiler
356 options have been used.
357 Sometimes software, like bootloaders, might need to
358 bypass this check.
359 If the file you receive the error for is firmware
360 that is not intended to be executed within the target
361 operating system or is intended to run on a separate
362 processor within the device, you can add "arch" to
363 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
364 for the package.
365 Another option is to check the
366 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
367 log and verify that the compiler options being used
368 are correct.
369 </para>
370
371 <para>
372 &nbsp;
373 </para>
374 </listitem>
375 </itemizedlist>
376 </para>
377
378 <para>
379 <itemizedlist>
380 <listitem>
381 <para id='qa-issue-arch-bit-size-no-match'>
382 <code>
383 Bit size did not match (&lt;machine_bits&gt; to &lt;file_bits&gt;) &lt;recipe&gt; on &lt;file&gt; [arch]
384 </code>
385 </para>
386
387 <para>
388 By default, the OpenEmbedded build system checks
389 the Executable and Linkable Format (ELF) type,
390 bit size, and endianness of any binaries to ensure
391 they match the target architecture.
392 This test fails if any binaries do not match the type since
393 there would be an incompatibility.
394 The test could indicate that the wrong compiler or compiler
395 options have been used.
396 Sometimes software, like bootloaders, might need to
397 bypass this check.
398 If the file you receive the error for is firmware that
399 is not intended to be executed within the target
400 operating system or is intended to run on a separate
401 processor within the device, you can add "arch" to
402 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
403 for the package.
404 Another option is to check the
405 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
406 log and verify that the compiler options being used are
407 correct.
408 </para>
409
410 <para>
411 &nbsp;
412 </para>
413 </listitem>
414 </itemizedlist>
415 </para>
416
417 <para>
418 <itemizedlist>
419 <listitem>
420 <para id='qa-issue-arch-endianness-no-match'>
421 <code>
422 Endianness did not match (&lt;machine_endianness&gt; to &lt;file_endianness&gt;) on &lt;file&gt; [arch]
423 </code>
424 </para>
425
426 <para>
427 By default, the OpenEmbedded build system checks
428 the Executable and Linkable Format (ELF) type, bit
429 size, and endianness of any binaries to ensure they
430 match the target architecture.
431 This test fails if any binaries do not match the type since
432 there would be an incompatibility.
433 The test could indicate that the wrong compiler or compiler
434 options have been used.
435 Sometimes software, like bootloaders, might need to
436 bypass this check.
437 If the file you receive the error for is firmware
438 that is not intended to be executed within the target
439 operating system or is intended to run on a separate
440 processor within the device, you can add "arch" to
441 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
442 for the package.
443 Another option is to check the
444 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
445 log and verify that the compiler options being used
446 are correct.
447 </para>
448
449 <para>
450 &nbsp;
451 </para>
452 </listitem>
453 </itemizedlist>
454 </para>
455
456 <para>
457 <itemizedlist>
458 <listitem>
459 <para id='qa-issue-textrel'>
460 <code>
461 ELF binary '&lt;file&gt;' has relocations in .text [textrel]
462 </code>
463 </para>
464
465 <para>
466 The specified ELF binary contains relocations in its
467 <filename>.text</filename> sections.
468 This situation can result in a performance impact
469 at runtime.
470 </para>
471
472 <para>
473 Typically, the way to solve this performance issue is to
474 add "-fPIC" or "-fpic" to the compiler command-line
475 options.
476 For example, given software that reads
477 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
478 when you build it, you could add the following to your
479 recipe:
480 <literallayout class='monospaced'>
481 CFLAGS_append = " -fPIC "
482 </literallayout>
483 </para>
484
485 <para>
486 For more information on text relocations at runtime, see
487 <ulink url='http://www.akkadia.org/drepper/textrelocs.html'></ulink>.
488 </para>
489
490 <para>
491 &nbsp;
492 </para>
493 </listitem>
494 </itemizedlist>
495 </para>
496
497 <para>
498 <itemizedlist>
499 <listitem>
500 <para id='qa-issue-ldflags'>
501 <code>
502 No GNU_HASH in the elf binary: '&lt;file&gt;' [ldflags]
503 </code>
504 </para>
505
506 <para>
507 This indicates that binaries produced when building the
508 recipe have not been linked with the
509 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
510 options provided by the build system.
511 Check to be sure that the <filename>LDFLAGS</filename>
512 variable is being passed to the linker command.
513 A common workaround for this situation is to pass in
514 <filename>LDFLAGS</filename> using
515 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
516 within the recipe as follows:
517 <literallayout class='monospaced'>
518 TARGET_CC_ARCH += "${LDFLAGS}"
519 </literallayout>
520 </para>
521
522 <para>
523 &nbsp;
524 </para>
525 </listitem>
526 </itemizedlist>
527 </para>
528
529 <para>
530 <itemizedlist>
531 <listitem>
532 <para id='qa-issue-xorg-driver-abi'>
533 <code>
534 Package &lt;packagename&gt; contains Xorg driver (&lt;driver&gt;) but no xorg-abi- dependencies [xorg-driver-abi]
535 </code>
536 </para>
537
538 <para>
539 The specified package contains an Xorg driver, but does not
540 have a corresponding ABI package dependency.
541 The xserver-xorg recipe provides driver ABI names.
542 All drivers should depend on the ABI versions that they have
543 been built against.
544 Driver recipes that include
545 <filename>xorg-driver-input.inc</filename> or
546 <filename>xorg-driver-video.inc</filename> will
547 automatically get these versions.
548 Consequently, you should only need to explicitly add
549 dependencies to binary driver recipes.
550 </para>
551
552 <para>
553 &nbsp;
554 </para>
555 </listitem>
556 </itemizedlist>
557 </para>
558
559 <para>
560 <itemizedlist>
561 <listitem>
562 <para id='qa-issue-infodir'>
563 <code>
564 The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]
565 </code>
566 </para>
567
568 <para>
569 The <filename>/usr/share/info/dir</filename> should not be
570 packaged.
571 Add the following line to your
572 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
573 task or to your <filename>do_install_append</filename>
574 within the recipe as follows:
575 <literallayout class='monospaced'>
576 rm ${D}${infodir}/dir
577 </literallayout>
578 </para>
579
580 <para>
581 &nbsp;
582 </para>
583 </listitem>
584 </itemizedlist>
585 </para>
586
587 <para>
588 <itemizedlist>
589 <listitem>
590 <para id='qa-issue-symlink-to-sysroot'>
591 <code>
592 Symlink &lt;path&gt; in &lt;packagename&gt; points to TMPDIR [symlink-to-sysroot]
593 </code>
594 </para>
595
596 <para>
597 The specified symlink points into
598 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
599 on the host.
600 Such symlinks will work on the host.
601 However, they are clearly invalid when running on
602 the target.
603 You should either correct the symlink to use a relative
604 path or remove the symlink.
605 </para>
606
607 <para>
608 &nbsp;
609 </para>
610 </listitem>
611 </itemizedlist>
612 </para>
613
614 <para>
615 <itemizedlist>
616 <listitem>
617 <para id='qa-issue-la'>
618 <code>
619 &lt;file&gt; failed sanity test (workdir) in path &lt;path&gt; [la]
620 </code>
621 </para>
622
623 <para>
624 The specified <filename>.la</filename> file contains
625 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
626 paths.
627 Any <filename>.la</filename> file containing these paths
628 is incorrect since <filename>libtool</filename> adds the
629 correct sysroot prefix when using the files automatically
630 itself.
631 </para>
632
633 <para>
634 &nbsp;
635 </para>
636 </listitem>
637 </itemizedlist>
638 </para>
639
640 <para>
641 <itemizedlist>
642 <listitem>
643 <para id='qa-issue-pkgconfig'>
644 <code>
645 &lt;file&gt; failed sanity test (tmpdir) in path &lt;path&gt; [pkgconfig]
646 </code>
647 </para>
648
649 <para>
650 The specified <filename>.pc</filename> file contains
651 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
652 paths.
653 Any <filename>.pc</filename> file containing these paths is
654 incorrect since <filename>pkg-config</filename> itself adds
655 the correct sysroot prefix when the files are accessed.
656 </para>
657
658 <para>
659 &nbsp;
660 </para>
661 </listitem>
662 </itemizedlist>
663 </para>
664
665 <para>
666 <itemizedlist>
667 <listitem>
668 <para id='qa-issue-debug-deps'>
669 <code>
670 &lt;packagename&gt; rdepends on &lt;debug_packagename&gt; [debug-deps]
671 </code>
672 </para>
673
674 <para>
675 A dependency exists between the specified non-dbg package
676 (i.e. a package whose name does not end in
677 <filename>-dbg</filename>) and a package that is a
678 <filename>dbg</filename> package.
679 The <filename>dbg</filename> packages contain
680 debug symbols and are brought in using several
681 different methods:
682 <itemizedlist>
683 <listitem><para>
684 Using the <filename>dbg-pkgs</filename>
685 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
686 value.
687 </para></listitem>
688 <listitem><para>
689 Using
690 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
691 </para></listitem>
692 <listitem><para>
693 As a dependency of another
694 <filename>dbg</filename> package that was brought
695 in using one of the above methods.
696 </para></listitem>
697 </itemizedlist>
698 The dependency might have been automatically added
699 because the <filename>dbg</filename> package erroneously
700 contains files that it should not contain (e.g. a
701 non-symlink <filename>.so</filename> file) or it might
702 have been added manually (e.g. by adding to
703 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
704 </para>
705
706 <para>
707 &nbsp;
708 </para>
709 </listitem>
710 </itemizedlist>
711 </para>
712
713 <para>
714 <itemizedlist>
715 <listitem>
716 <para id='qa-issue-dev-deps'>
717 <code>
718 &lt;packagename&gt; rdepends on &lt;dev_packagename&gt; [dev-deps]
719 </code>
720 </para>
721
722 <para>
723 A dependency exists between the specified non-dev package
724 (a package whose name does not end in
725 <filename>-dev</filename>) and a package that is a
726 <filename>dev</filename> package.
727 The <filename>dev</filename> packages contain development
728 headers and are usually brought in using several different
729 methods:
730 <itemizedlist>
731 <listitem><para>
732 Using the <filename>dev-pkgs</filename>
733 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
734 value.
735 </para></listitem>
736 <listitem><para>
737 Using
738 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
739 </para></listitem>
740 <listitem><para>
741 As a dependency of another
742 <filename>dev</filename> package that was brought
743 in using one of the above methods.
744 </para></listitem>
745 </itemizedlist>
746 The dependency might have been automatically added (because
747 the <filename>dev</filename> package erroneously contains
748 files that it should not have (e.g. a non-symlink
749 <filename>.so</filename> file) or it might have been added
750 manually (e.g. by adding to
751 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
752 </para>
753
754 <para>
755 &nbsp;
756 </para>
757 </listitem>
758 </itemizedlist>
759 </para>
760
761 <para>
762 <itemizedlist>
763 <listitem>
764 <para id='qa-issue-dep-cmp'>
765 <code>
766 &lt;var&gt;_&lt;packagename&gt; is invalid: &lt;comparison&gt; (&lt;value&gt;) only comparisons &lt;, =, &gt;, &lt;=, and &gt;= are allowed [dep-cmp]
767 </code>
768 </para>
769
770 <para>
771 If you are adding a versioned dependency relationship to one
772 of the dependency variables
773 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
774 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
775 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
776 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
777 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
778 or
779 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>),
780 you must only use the named comparison operators.
781 Change the versioned dependency values you are adding
782 to match those listed in the message.
783 </para>
784
785 <para>
786 &nbsp;
787 </para>
788 </listitem>
789 </itemizedlist>
790 </para>
791
792 <para>
793 <itemizedlist>
794 <listitem>
795 <para id='qa-issue-compile-host-path'>
796 <code>
797 &lt;recipename&gt;: The compile log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' for more information. [compile-host-path]
798 </code>
799 </para>
800
801 <para>
802 The log for the
803 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
804 task indicates that paths on the host were searched
805 for files, which is not appropriate when cross-compiling.
806 Look for "is unsafe for cross-compilation" or "CROSS COMPILE
807 Badness" in the specified log file.
808 </para>
809
810 <para>
811 &nbsp;
812 </para>
813 </listitem>
814 </itemizedlist>
815 </para>
816
817 <para>
818 <itemizedlist>
819 <listitem>
820 <para id='qa-issue-install-host-path'>
821 <code>
822 &lt;recipename&gt;: The install log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' for more information. [install-host-path]
823 </code>
824 </para>
825
826 <para>
827 The log for the
828 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
829 task indicates that paths on the host were searched
830 for files, which is not appropriate when cross-compiling.
831 Look for "is unsafe for cross-compilation"
832 or "CROSS COMPILE Badness" in the specified log file.
833 </para>
834
835 <para>
836 &nbsp;
837 </para>
838 </listitem>
839 </itemizedlist>
840 </para>
841
842 <para>
843 <itemizedlist>
844 <listitem>
845 <para id='qa-issue-autoconf-log'>
846 <code>
847 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 '&lt;path&gt;'
848 </code>
849 </para>
850
851 <para>
852 The log for the
853 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
854 task indicates that paths on the host were searched
855 for files, which is not appropriate when cross-compiling.
856 Look for "is unsafe for cross-compilation" or
857 "CROSS COMPILE Badness" in the specified log file.
858 </para>
859
860 <para>
861 &nbsp;
862 </para>
863 </listitem>
864 </itemizedlist>
865 </para>
866
867 <para>
868 <itemizedlist>
869 <listitem>
870 <para id='qa-issue-pkgname'>
871 <code>
872 &lt;packagename&gt; doesn't match the [a-z0-9.+-]+ regex [pkgname]
873 </code>
874 </para>
875
876 <para>
877 The convention within the OpenEmbedded build system
878 (sometimes enforced by the package manager itself) is to
879 require that package names are all lower case
880 and to allow a restricted set of characters.
881 If your recipe name does not match this, or you add
882 packages to
883 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
884 that do not conform to the convention, then you
885 will receive this error.
886 Rename your recipe.
887 Or, if you have added a non-conforming package name to
888 <filename>PACKAGES</filename>, change the package name
889 appropriately.
890 </para>
891
892 <para>
893 &nbsp;
894 </para>
895 </listitem>
896 </itemizedlist>
897 </para>
898
899 <para>
900 <itemizedlist>
901 <listitem>
902 <para id='qa-issue-unknown-configure-option'>
903 <code>
904 &lt;recipe&gt;: configure was passed unrecognized options: &lt;options&gt; [unknown-configure-option]
905 </code>
906 </para>
907
908 <para>
909 The configure script is reporting that the specified
910 options are unrecognized.
911 This situation could be because the options
912 were previously valid but have been removed from the
913 configure script.
914 Or, there was a mistake when the options were added
915 and there is another option that should be used instead.
916 If you are unsure, consult the upstream build
917 documentation, the
918 <filename>./configure --help</filename> output,
919 and the upstream change log or release notes.
920 Once you have worked out what the appropriate
921 change is, you can update
922 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>,
923 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>,
924 or the individual
925 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
926 option values accordingly.
927 </para>
928
929 <para>
930 &nbsp;
931 </para>
932 </listitem>
933 </itemizedlist>
934 </para>
935
936 <para>
937 <itemizedlist>
938 <listitem>
939 <para id='qa-issue-pn-overrides'>
940 <code>
941 Recipe &lt;recipefile&gt; has PN of "&lt;recipename&gt;" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]
942 </code>
943 </para>
944
945 <para>
946 The specified recipe has a name
947 (<link linkend='var-PN'><filename>PN</filename></link>)
948 value that appears in
949 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
950 If a recipe is named such that its <filename>PN</filename>
951 value matches something already in
952 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
953 happens to be the same as
954 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
955 or
956 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
957 it can have unexpected consequences.
958 For example, assignments such as
959 <filename>FILES_${PN} = "xyz"</filename> effectively
960 turn into <filename>FILES = "xyz"</filename>.
961 Rename your recipe (or if <filename>PN</filename> is being
962 set explicitly, change the <filename>PN</filename> value) so
963 that the conflict does not occur.
964 See
965 <link linkend='var-FILES'><filename>FILES</filename></link>
966 for additional information.
967 </para>
968
969 <para>
970 &nbsp;
971 </para>
972 </listitem>
973 </itemizedlist>
974 </para>
975
976 <para>
977 <itemizedlist>
978 <listitem>
979 <para id='qa-issue-pkgvarcheck'>
980 <code>
981 &lt;recipefile&gt;: Variable &lt;variable&gt; is set as not being package specific, please fix this. [pkgvarcheck]
982 </code>
983 </para>
984
985 <para>
986 Certain variables
987 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
988 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
989 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
990 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
991 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
992 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
993 <link linkend='var-FILES'><filename>FILES</filename></link>,
994 <filename>pkg_preinst</filename>,
995 <filename>pkg_postinst</filename>,
996 <filename>pkg_prerm</filename>,
997 <filename>pkg_postrm</filename>, and
998 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>)
999 should always be set specific to a package (i.e. they
1000 should be set with a package name override such as
1001 <filename>RDEPENDS_${PN} = "value"</filename> rather than
1002 <filename>RDEPENDS = "value"</filename>).
1003 If you receive this error, correct any assignments to these
1004 variables within your recipe.
1005 </para>
1006
1007 <para>
1008 &nbsp;
1009 </para>
1010 </listitem>
1011 </itemizedlist>
1012 </para>
1013
1014 <para>
1015 <itemizedlist>
1016 <listitem>
1017 <para id='qa-issue-already-stripped'>
1018 <code>
1019 File '&lt;file&gt;' from &lt;recipename&gt; was already stripped, this will prevent future debugging! [already-stripped]
1020 </code>
1021 </para>
1022
1023 <para>
1024 Produced binaries have already been stripped prior to the
1025 build system extracting debug symbols.
1026 It is common for upstream software projects to default to
1027 stripping debug symbols for output binaries.
1028 In order for debugging to work on the target using
1029 <filename>-dbg</filename> packages, this stripping must be
1030 disabled.
1031 </para>
1032
1033 <para>
1034 Depending on the build system used by the software being
1035 built, disabling this stripping could be as easy as
1036 specifying an additional configure option.
1037 If not, disabling stripping might involve patching
1038 the build scripts.
1039 In the latter case, look for references to "strip" or
1040 "STRIP", or the "-s" or "-S" command-line options being
1041 specified on the linker command line (possibly
1042 through the compiler command line if preceded with "-Wl,").
1043 <note>
1044 Disabling stripping here does not mean that the final
1045 packaged binaries will be unstripped.
1046 Once the OpenEmbedded build system splits out debug
1047 symbols to the <filename>-dbg</filename> package,
1048 it will then strip the symbols from the binaries.
1049 </note>
1050 </para>
1051
1052 <para>
1053 &nbsp;
1054 </para>
1055 </listitem>
1056 </itemizedlist>
1057 </para>
1058
1059 <para>
1060 <itemizedlist>
1061 <listitem>
1062 <para id='qa-issue-packages-list'>
1063 <code>
1064 &lt;packagename&gt; is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]
1065 </code>
1066 </para>
1067
1068 <para>
1069 Package names must appear only once in the
1070 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1071 variable.
1072 You might receive this error if you are attempting to add a
1073 package to <filename>PACKAGES</filename> that is
1074 already in the variable's value.
1075 </para>
1076
1077 <para>
1078 &nbsp;
1079 </para>
1080 </listitem>
1081 </itemizedlist>
1082 </para>
1083
1084 <para>
1085 <itemizedlist>
1086 <listitem>
1087 <para id='qa-issue-files-invalid'>
1088 <code>
1089 FILES variable for package &lt;packagename&gt; contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]
1090 </code>
1091 </para>
1092
1093 <para>
1094 The string "//" is invalid in a Unix path.
1095 Correct all occurrences where this string appears in a
1096 <link linkend='var-FILES'><filename>FILES</filename></link>
1097 variable so that there is only a single "/".
1098 </para>
1099
1100 <para>
1101 &nbsp;
1102 </para>
1103 </listitem>
1104 </itemizedlist>
1105 </para>
1106
1107 <para>
1108 <itemizedlist>
1109 <listitem>
1110 <para id='qa-issue-installed-vs-shipped'>
1111 <code>
1112 &lt;recipename&gt;: Files/directories were installed but not shipped in any package [installed-vs-shipped]
1113 </code>
1114 </para>
1115
1116 <para>
1117 Files have been installed within the
1118 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1119 task but have not been included in any package by way of the
1120 <link linkend='var-FILES'><filename>FILES</filename></link>
1121 variable.
1122 Files that do not appear in any package cannot be present in
1123 an image later on in the build process.
1124 You need to do one of the following:
1125 <itemizedlist>
1126 <listitem><para>
1127 Add the files to <filename>FILES</filename> for the
1128 package you want them to appear in (e.g.
1129 <filename>FILES_${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> for the main
1130 package).
1131 </para></listitem>
1132 <listitem><para>
1133 Delete the files at the end of the
1134 <filename>do_install</filename> task if the files
1135 are not needed in any package.
1136 </para></listitem>
1137 </itemizedlist>
1138 </para>
1139
1140 <para>
1141 &nbsp;
1142 </para>
1143 </listitem>
1144 </itemizedlist>
1145 </para>
1146
1147 <para>
1148 <itemizedlist>
1149 <listitem>
1150 <para id='qa-issue-old-and-new-package-and-version-names'>
1151 <code>
1152 &lt;oldpackage&gt;-&lt;oldpkgversion&gt; was registered as shlib provider for &lt;library&gt;, changing it to &lt;newpackage&gt;-&lt;newpkgversion&gt; because it was built later
1153 </code>
1154 </para>
1155
1156 <para>
1157 This message means that both
1158 <filename>&lt;oldpackage&gt;</filename> and
1159 <filename>&lt;newpackage&gt;</filename> provide the specified
1160 shared library.
1161 You can expect this message when a recipe has been renamed.
1162 However, if that is not the case, the message might indicate
1163 that a private version of a library is being erroneously
1164 picked up as the provider for a common library.
1165 If that is the case, you should add the library's
1166 <filename>.so</filename> file name to
1167 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
1168 in the recipe that provides
1169 the private version of the library.
1170 </para>
1171 </listitem>
1172 </itemizedlist>
1173 </para>
1174
1175 <para>
1176 <itemizedlist>
1177 <listitem>
1178 <para id='qa-issue-unlisted-pkg-lics'>
1179 <code>
1180 LICENSE_&lt;packagename&gt; includes licenses (&lt;licenses&gt;) 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 &nbsp;
1195 </para>
1196 </listitem>
1197 </itemizedlist>
1198 </para>
1199</section>
1200
1201<section id='configuring-and-disabling-qa-checks'>
1202 <title>Configuring and Disabling QA Checks</title>
1203
1204 <para>
1205 You can configure the QA checks globally so that specific check
1206 failures either raise a warning or an error message, using the
1207 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1208 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1209 variables, respectively.
1210 You can also disable checks within a particular recipe using
1211 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1212 For information on how to work with the QA checks, see the
1213 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1214 section.
1215 <note><title>Tip</title>
1216 Please keep in mind that the QA checks exist in order to
1217 detect real or potential problems in the packaged output.
1218 So exercise caution when disabling these checks.
1219 </note>
1220 </para>
1221</section>
1222</chapter>
1223<!--
1224vim: expandtab tw=80 ts=4
1225-->
diff --git a/documentation/ref-manual/ref-release-process.xml b/documentation/ref-manual/ref-release-process.xml
deleted file mode 100644
index 87f5308067..0000000000
--- a/documentation/ref-manual/ref-release-process.xml
+++ /dev/null
@@ -1,256 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-release-process'>
7<title>Yocto Project Releases and the Stable Release Process</title>
8
9<para>
10 The Yocto Project release process is predictable and consists of both
11 major and minor (point) releases.
12 This brief chapter provides information on how releases are named, their
13 life cycle, and their stability.
14</para>
15
16<section id='major-and-minor-release-cadence'>
17 <title>Major and Minor Release Cadence</title>
18
19 <para>
20 The Yocto Project delivers major releases (e.g. &DISTRO;) using a six
21 month cadence roughly timed each April and October of the year.
22 Following are examples of some major YP releases with their codenames
23 also shown.
24 See the
25 "<link linkend='major-release-codenames'>Major Release Codenames</link>"
26 section for information on codenames used with major releases.
27 <literallayout class='monospaced'>
28 2.2 (Morty)
29 2.1 (Krogoth)
30 2.0 (Jethro)
31 </literallayout>
32 While the cadence is never perfect, this timescale facilitates
33 regular releases that have strong QA cycles while not overwhelming
34 users with too many new releases.
35 The cadence is predictable and avoids many major holidays in various
36 geographies.
37 </para>
38
39 <para>
40 The Yocto project delivers minor (point) releases on an unscheduled
41 basis and are usually driven by the accumulation of enough significant
42 fixes or enhancements to the associated major release.
43 Following are some example past point releases:
44 <literallayout class='monospaced'>
45 2.1.1
46 2.1.2
47 2.2.1
48 </literallayout>
49 The point release indicates a point in the major release branch where
50 a full QA cycle and release process validates the content of the new
51 branch.
52 <note>
53 Realize that there can be patches merged onto the stable release
54 branches as and when they become available.
55 </note>
56 </para>
57</section>
58
59<section id='major-release-codenames'>
60 <title>Major Release Codenames</title>
61
62 <para>
63 Each major release receives a codename that identifies the release in
64 the
65 <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>.
66 The concept is that branches of
67 <link linkend='metadata'>Metadata</link>
68 with the same codename are likely to be compatible and thus
69 work together.
70 <note>
71 Codenames are associated with major releases because a Yocto
72 Project release number (e.g. &DISTRO;) could conflict with
73 a given layer or company versioning scheme.
74 Codenames are unique, interesting, and easily identifiable.
75 </note>
76 Releases are given a nominal release version as well but the codename
77 is used in repositories for this reason.
78 You can find information on Yocto Project releases and codenames at
79 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'></ulink>.
80 </para>
81</section>
82
83<section id='stable-release-process'>
84 <title>Stable Release Process</title>
85
86 <para>
87 Once released, the release enters the stable release process at which
88 time a person is assigned as the maintainer for that stable release.
89 This maintainer monitors activity for the release by investigating
90 and handling nominated patches and backport activity.
91 Only fixes and enhancements that have first been applied on the
92 "master" branch (i.e. the current, in-development branch) are
93 considered for backporting to a stable release.
94 <note>
95 The current Yocto Project policy regarding backporting is to
96 consider bug fixes and security fixes only.
97 Policy dictates that features are not backported to a stable
98 release.
99 This policy means generic recipe version upgrades are unlikely to
100 be accepted for backporting.
101 The exception to this policy occurs when a strong reason exists
102 such as the fix happens to also be the preferred upstream approach.
103 </note>
104 </para>
105
106 <para>
107 Stable release branches have strong maintenance for about a year after
108 their initial release.
109 Should significant issues be found for any release regardless of its
110 age, fixes could be backported to older releases.
111 For issues that are not backported given an older release,
112 Community LTS trees and branches exist where
113 community members share patches for older releases.
114 However, these types of patches do not go through the same release
115 process as do point releases.
116 You can find more information about stable branch maintenance at
117 <ulink url='https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance'></ulink>.
118 </para>
119</section>
120
121<section id='testing-and-quality-assurance'>
122 <title>Testing and Quality Assurance</title>
123
124 <para>
125 Part of the Yocto Project development and release process is quality
126 assurance through the execution of test strategies.
127 Test strategies provide the Yocto Project team a way to ensure a
128 release is validated.
129 Additionally, because the test strategies are visible to you as a
130 developer, you can validate your projects.
131 This section overviews the available test infrastructure used in the
132 Yocto Project.
133 For information on how to run available tests on your projects, see the
134 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
135 section in the Yocto Project Development Tasks Manual.
136 </para>
137
138 <para>
139 The QA/testing infrastructure is woven into the project to the point
140 where core developers take some of it for granted.
141 The infrastructure consists of the following pieces:
142 <itemizedlist>
143 <listitem><para>
144 <filename>bitbake-selftest</filename>:
145 A standalone command that runs unit tests on key pieces of
146 BitBake and its fetchers.
147 </para></listitem>
148 <listitem><para>
149 <link linkend='ref-classes-sanity'><filename>sanity.bbclass</filename></link>:
150 This automatically included class checks the build environment
151 for missing tools (e.g. <filename>gcc</filename>) or common
152 misconfigurations such as
153 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
154 set incorrectly.
155 </para></listitem>
156 <listitem><para>
157 <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>:
158 This class checks the generated output from builds for sanity.
159 For example, if building for an ARM target, did the build
160 produce ARM binaries.
161 If, for example, the build produced PPC binaries then there
162 is a problem.
163 </para></listitem>
164 <listitem><para>
165 <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>:
166 This class performs runtime testing of images after they are
167 built.
168 The tests are usually used with
169 <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU</ulink>
170 to boot the images and check the combined runtime result
171 boot operation and functions.
172 However, the test can also use the IP address of a machine to
173 test.
174 </para></listitem>
175 <listitem><para>
176 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'><filename>ptest</filename></ulink>:
177 Runs tests against packages produced during the build for a
178 given piece of software.
179 The test allows the packages to be be run within a target
180 image.
181 </para></listitem>
182 <listitem><para>
183 <filename>oe-selftest</filename>:
184 Tests combination BitBake invocations.
185 These tests operate outside the OpenEmbedded build system
186 itself.
187 The <filename>oe-selftest</filename> can run all tests by
188 default or can run selected tests or test suites.
189 <note>
190 Running <filename>oe-selftest</filename> requires
191 host packages beyond the "Essential" grouping.
192 See the
193 "<link linkend='required-packages-for-the-build-host'>Required Packages for the Build Host</link>"
194 section for more information.
195 </note>
196 </para></listitem>
197 </itemizedlist>
198 </para>
199
200 <para>
201 Originally, much of this testing was done manually.
202 However, significant effort has been made to automate the tests so
203 that more people can use them and the Yocto Project development team
204 can run them faster and more efficiently.
205 </para>
206
207 <para>
208 The Yocto Project's main Autobuilder
209 (<filename>autobuilder.yoctoproject.org</filename>) publicly tests
210 each Yocto Project release's code in the
211 <link linkend='oe-core'>OE-Core</link>, Poky, and BitBake
212 repositories.
213 The testing occurs for both the current state of the
214 "master" branch and also for submitted patches.
215 Testing for submitted patches usually occurs in the
216 "ross/mut" branch in the <filename>poky-contrib</filename> repository
217 (i.e. the master-under-test branch) or in the "master-next" branch
218 in the <filename>poky</filename> repository.
219 <note>
220 You can find all these branches in the Yocto Project
221 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>.
222 </note>
223 Testing within these public branches ensures in a publicly visible way
224 that all of the main supposed architectures and recipes in OE-Core
225 successfully build and behave properly.
226 </para>
227
228 <para>
229 Various features such as <filename>multilib</filename>, sub
230 architectures (e.g. <filename>x32</filename>,
231 <filename>poky-tiny</filename>, <filename>musl</filename>,
232 <filename>no-x11</filename> and and so forth),
233 <filename>bitbake-selftest</filename>, and
234 <filename>oe-selftest</filename> are tested as part of
235 the QA process of a release.
236 Complete testing and validation for a release takes the Autobuilder
237 workers several hours.
238 <note>
239 The Autobuilder workers are non-homogeneous, which means regular
240 testing across a variety of Linux distributions occurs.
241 The Autobuilder is limited to only testing QEMU-based setups and
242 not real hardware.
243 </note>
244 </para>
245
246 <para>
247 Finally, in addition to the Autobuilder's tests, the Yocto Project
248 QA team also performs testing on a variety of platforms, which includes
249 actual hardware, to ensure expected results.
250 </para>
251</section>
252
253</chapter>
254<!--
255vim: expandtab tw=80 ts=4
256-->
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
deleted file mode 100644
index 8588e9c2dd..0000000000
--- a/documentation/ref-manual/ref-structure.xml
+++ /dev/null
@@ -1,1123 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-structure'>
7
8<title>Source Directory Structure</title>
9
10<para>
11 The <link linkend='source-directory'>Source Directory</link>
12 consists of numerous files, directories and subdirectories;
13 understanding their locations and contents is key to using the
14 Yocto Project effectively.
15 This chapter describes the Source Directory and gives information about
16 those files and directories.
17</para>
18
19<para>
20 For information on how to establish a local Source Directory on your
21 development system, see the
22 "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
23 section in the Yocto Project Development Tasks Manual.
24</para>
25
26 <note>
27 The OpenEmbedded build system does not support file or directory names that
28 contain spaces.
29 Be sure that the Source Directory you use does not contain these types
30 of names.
31 </note>
32
33<section id='structure-core'>
34 <title>Top-Level Core Components</title>
35
36 <para>
37 This section describes the top-level components of the
38 <link linkend='source-directory'>Source Directory</link>.
39 </para>
40
41 <section id='structure-core-bitbake'>
42 <title><filename>bitbake/</filename></title>
43
44 <para>
45 This directory includes a copy of BitBake for ease of use.
46 The copy usually matches the current stable BitBake release from
47 the BitBake project.
48 BitBake, a
49 <link linkend='metadata'>Metadata</link>
50 interpreter, reads the Yocto Project Metadata and runs the tasks
51 defined by that data.
52 Failures are usually caused by errors in your Metadata and not from BitBake itself;
53 consequently, most users do not need to worry about BitBake.
54 </para>
55
56 <para>
57 When you run the <filename>bitbake</filename> command, the
58 main BitBake executable (which resides in the
59 <filename>bitbake/bin/</filename> directory) starts.
60 Sourcing the environment setup script (i.e.
61 <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>)
62 places the <filename>scripts/</filename> and
63 <filename>bitbake/bin/</filename> directories (in that order) into
64 the shell's <filename>PATH</filename> environment variable.
65 </para>
66
67 <para>
68 For more information on BitBake, see the
69 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
70 </para>
71 </section>
72
73 <section id='structure-core-build'>
74 <title><filename>build/</filename></title>
75
76 <para>
77 This directory contains user configuration files and the output
78 generated by the OpenEmbedded build system in its standard configuration where
79 the source tree is combined with the output.
80 The
81 <link linkend='build-directory'>Build Directory</link>
82 is created initially when you <filename>source</filename>
83 the OpenEmbedded build environment setup script
84 (i.e.
85 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
86 </para>
87
88 <para>
89 It is also possible to place output and configuration
90 files in a directory separate from the
91 <link linkend='source-directory'>Source Directory</link>
92 by providing a directory name when you <filename>source</filename>
93 the setup script.
94 For information on separating output from your local
95 Source Directory files (commonly described as an "out of tree" build), see the
96 "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
97 section.
98 </para>
99 </section>
100
101 <section id='handbook'>
102 <title><filename>documentation/</filename></title>
103
104 <para>
105 This directory holds the source for the Yocto Project documentation
106 as well as templates and tools that allow you to generate PDF and HTML
107 versions of the manuals.
108 Each manual is contained in its own sub-folder;
109 for example, the files for this reference manual reside in
110 the <filename>ref-manual/</filename> directory.
111 </para>
112 </section>
113
114 <section id='structure-core-meta'>
115 <title><filename>meta/</filename></title>
116
117 <para>
118 This directory contains the minimal, underlying OpenEmbedded-Core metadata.
119 The directory holds recipes, common classes, and machine
120 configuration for strictly emulated targets (<filename>qemux86</filename>,
121 <filename>qemuarm</filename>, and so forth.)
122 </para>
123 </section>
124
125 <section id='structure-core-meta-poky'>
126 <title><filename>meta-poky/</filename></title>
127
128 <para>
129 Designed above the <filename>meta/</filename> content, this directory
130 adds just enough metadata to define the Poky reference distribution.
131 </para>
132 </section>
133
134 <section id='structure-core-meta-yocto-bsp'>
135 <title><filename>meta-yocto-bsp/</filename></title>
136
137 <para>
138 This directory contains the Yocto Project reference
139 hardware Board Support Packages (BSPs).
140 For more information on BSPs, see the
141 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
142 </para>
143 </section>
144
145 <section id='structure-meta-selftest'>
146 <title><filename>meta-selftest/</filename></title>
147
148 <para>
149 This directory adds additional recipes and append files
150 used by the OpenEmbedded selftests to verify the behavior
151 of the build system.
152 You do not have to add this layer to your
153 <filename>bblayers.conf</filename> file unless you want to run the
154 selftests.
155 </para>
156 </section>
157
158 <section id='structure-meta-skeleton'>
159 <title><filename>meta-skeleton/</filename></title>
160
161 <para>
162 This directory contains template recipes for BSP and kernel development.
163 </para>
164 </section>
165
166 <section id='structure-core-scripts'>
167 <title><filename>scripts/</filename></title>
168
169 <para>
170 This directory contains various integration scripts that implement
171 extra functionality in the Yocto Project environment (e.g. QEMU scripts).
172 The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
173 script prepends this directory to the shell's
174 <filename>PATH</filename> environment variable.
175 </para>
176
177 <para>
178 The <filename>scripts</filename> directory has useful scripts that assist in contributing
179 back to the Yocto Project, such as <filename>create-pull-request</filename> and
180 <filename>send-pull-request</filename>.
181 </para>
182 </section>
183
184 <section id='structure-core-script'>
185 <title><filename>&OE_INIT_FILE;</filename></title>
186
187 <para>
188 This script sets up the OpenEmbedded build environment.
189 Running this script with the <filename>source</filename> command in
190 a shell makes changes to <filename>PATH</filename> and sets other
191 core BitBake variables based on the current working directory.
192 You need to run an environment setup script before running BitBake
193 commands.
194 The script uses other scripts within the
195 <filename>scripts</filename> directory to do the bulk of the work.
196 </para>
197
198 <para>
199 When you run this script, your Yocto Project environment is set
200 up, a
201 <link linkend='build-directory'>Build Directory</link>
202 is created, your working directory becomes the Build Directory,
203 and you are presented with some simple suggestions as to what to do
204 next, including a list of some possible targets to build.
205 Here is an example:
206 <literallayout class='monospaced'>
207 $ source oe-init-build-env
208
209 ### Shell environment set up for builds. ###
210
211 You can now run 'bitbake &lt;target&gt;'
212
213 Common targets are:
214 core-image-minimal
215 core-image-sato
216 meta-toolchain
217 meta-ide-support
218
219 You can also run generated qemu images with a command like 'runqemu qemux86-64'
220 </literallayout>
221 The default output of the <filename>oe-init-build-env</filename> script
222 is from the <filename>conf-notes.txt</filename> file, which is found in the
223 <filename>meta-poky</filename> directory within the
224 <link linkend='source-directory'>Source Directory</link>.
225 If you design a custom distribution, you can include your own version
226 of this configuration file to mention the targets defined by your
227 distribution.
228 See the
229 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
230 section in the Yocto Project Development Tasks Manual for more
231 information.
232 </para>
233
234 <para>
235 By default, running this script without a Build Directory
236 argument creates the <filename>build/</filename> directory
237 in your current working directory.
238 If you provide a Build Directory argument when you
239 <filename>source</filename> the script, you direct the OpenEmbedded
240 build system to create a Build Directory of your choice.
241 For example, the following command creates a Build Directory named
242 <filename>mybuilds/</filename> that is outside of the
243 <link linkend='source-directory'>Source Directory</link>:
244 <literallayout class='monospaced'>
245 $ source &OE_INIT_FILE; ~/mybuilds
246 </literallayout>
247 The OpenEmbedded build system uses the template configuration
248 files, which are found by default in the
249 <filename>meta-poky/conf/</filename> directory in the
250 Source Directory.
251 See the
252 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>"
253 section in the Yocto Project Development Tasks Manual for more
254 information.
255 <note>
256 The OpenEmbedded build system does not support file or directory names that
257 contain spaces.
258 If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
259 from a Source Directory that contains spaces in either the filenames
260 or directory names, the script returns an error indicating no such
261 file or directory.
262 Be sure to use a Source Directory free of names containing spaces.
263 </note>
264 </para>
265 </section>
266
267 <section id='structure-basic-top-level'>
268 <title><filename>LICENSE, README, and README.hardware</filename></title>
269
270 <para>
271 These files are standard top-level files.
272 </para>
273 </section>
274</section>
275
276<section id='structure-build'>
277 <title>The Build Directory - <filename>build/</filename></title>
278
279 <para>
280 The OpenEmbedded build system creates the
281 <link linkend='build-directory'>Build Directory</link>
282 when you run the build environment setup script
283 <link
284linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
285 If you do not give the Build Directory a specific name when you run
286 the setup script, the name defaults to <filename>build/</filename>.
287 </para>
288
289 <para>
290 For subsequent parsing and processing, the name of the Build
291 directory is available via the
292 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> variable.
293 </para>
294
295 <section id='structure-build-buildhistory'>
296 <title><filename>build/buildhistory/</filename></title>
297
298 <para>
299 The OpenEmbedded build system creates this directory when you
300 enable build history via the <filename>buildhistory</filename> class file.
301 The directory organizes build information into image, packages, and
302 SDK subdirectories.
303 For information on the build history feature, see the
304 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
305 section in the Yocto Project Development Tasks Manual.
306 </para>
307 </section>
308
309 <section id='structure-build-conf-local.conf'>
310 <title><filename>build/conf/local.conf</filename></title>
311
312 <para>
313 This configuration file contains all the local user configurations
314 for your build environment.
315 The <filename>local.conf</filename> file contains documentation on
316 the various configuration options.
317 Any variable set here overrides any variable set elsewhere within
318 the environment unless that variable is hard-coded within a file
319 (e.g. by using '=' instead of '?=').
320 Some variables are hard-coded for various reasons but such
321 variables are relatively rare.
322 </para>
323
324 <para>
325 At a minimum, you would normally edit this file to select the target
326 <filename><link linkend='var-MACHINE'>MACHINE</link></filename>,
327 which package types you wish to use
328 (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
329 and the location from which you want to access downloaded files
330 (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>).
331 </para>
332
333 <para>
334 If <filename>local.conf</filename> is not present when you
335 start the build, the OpenEmbedded build system creates it from
336 <filename>local.conf.sample</filename> when
337 you <filename>source</filename> the top-level build environment
338 setup script
339 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
340 </para>
341
342 <para>
343 The source <filename>local.conf.sample</filename> file used
344 depends on the <filename>$TEMPLATECONF</filename> script variable,
345 which defaults to <filename>meta-poky/conf/</filename>
346 when you are building from the Yocto Project development
347 environment, and to <filename>meta/conf/</filename> when
348 you are building from the OpenEmbedded-Core environment.
349 Because the script variable points to the source of the
350 <filename>local.conf.sample</filename> file, this implies that
351 you can configure your build environment from any layer by setting
352 the variable in the top-level build environment setup script as
353 follows:
354 <literallayout class='monospaced'>
355 TEMPLATECONF=<replaceable>your_layer</replaceable>/conf
356 </literallayout>
357 Once the build process gets the sample file, it uses
358 <filename>sed</filename> to substitute final
359 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
360 values for all <filename>##OEROOT##</filename> values.
361 <note>
362 You can see how the <filename>TEMPLATECONF</filename> variable
363 is used by looking at the
364 <filename>scripts/oe-setup-builddir</filename> script in the
365 <link linkend='source-directory'>Source Directory</link>.
366 You can find the Yocto Project version of the
367 <filename>local.conf.sample</filename> file in the
368 <filename>meta-poky/conf</filename> directory.
369 </note>
370 </para>
371 </section>
372
373 <section id='structure-build-conf-bblayers.conf'>
374 <title><filename>build/conf/bblayers.conf</filename></title>
375
376 <para>
377 This configuration file defines
378 <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
379 which are directory trees, traversed (or walked) by BitBake.
380 The <filename>bblayers.conf</filename> file uses the
381 <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link>
382 variable to list the layers BitBake tries to find.
383 </para>
384
385 <para>
386 If <filename>bblayers.conf</filename> is not present when you
387 start the build, the OpenEmbedded build system creates it from
388 <filename>bblayers.conf.sample</filename> when
389 you <filename>source</filename> the top-level build environment
390 setup script (i.e.
391 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
392 </para>
393
394 <para>
395 As with the <filename>local.conf</filename> file,
396 the source <filename>bblayers.conf.sample</filename> file used
397 depends on the <filename>$TEMPLATECONF</filename> script variable,
398 which defaults to <filename>meta-poky/conf/</filename>
399 when you are building from the Yocto Project development
400 environment, and to <filename>meta/conf/</filename> when
401 you are building from the OpenEmbedded-Core environment.
402 Because the script variable points to the source of the
403 <filename>bblayers.conf.sample</filename> file, this implies that
404 you can base your build from any layer by setting the variable in
405 the top-level build environment setup script as follows:
406 <literallayout class='monospaced'>
407 TEMPLATECONF=<replaceable>your_layer</replaceable>/conf
408 </literallayout>
409 Once the build process gets the sample file, it uses
410 <filename>sed</filename> to substitute final
411 <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename>
412 values for all <filename>##OEROOT##</filename> values.
413 <note>
414 You can see how the <filename>TEMPLATECONF</filename> variable
415 <filename>scripts/oe-setup-builddir</filename> script in the
416 <link linkend='source-directory'>Source Directory</link>.
417 You can find the Yocto Project version of the
418 <filename>bblayers.conf.sample</filename> file in the
419 <filename>meta-poky/conf/</filename> directory.
420 </note>
421 </para>
422 </section>
423
424 <section id='structure-build-conf-sanity_info'>
425 <title><filename>build/cache/sanity_info</filename></title>
426
427 <para>
428 This file indicates the state of the sanity checks and is created
429 during the build.
430 </para>
431 </section>
432
433 <section id='structure-build-downloads'>
434 <title><filename>build/downloads/</filename></title>
435
436 <para>
437 This directory contains downloaded upstream source tarballs.
438 You can reuse the directory for multiple builds or move
439 the directory to another location.
440 You can control the location of this directory through the
441 <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
442 </para>
443 </section>
444
445 <section id='structure-build-sstate-cache'>
446 <title><filename>build/sstate-cache/</filename></title>
447
448 <para>
449 This directory contains the shared state cache.
450 You can reuse the directory for multiple builds or move
451 the directory to another location.
452 You can control the location of this directory through the
453 <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
454 </para>
455 </section>
456
457 <section id='structure-build-tmp'>
458 <title><filename>build/tmp/</filename></title>
459
460 <para>
461 The OpenEmbedded build system creates and uses this directory
462 for all the build system's output.
463 The
464 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
465 variable points to this directory.
466 </para>
467
468 <para>
469 BitBake creates this directory if it does not exist.
470 As a last resort, to clean up a build and start it from scratch
471 (other than the downloads), you can remove everything in the
472 <filename>tmp</filename> directory or get rid of the
473 directory completely.
474 If you do, you should also completely remove the
475 <filename>build/sstate-cache</filename> directory.
476 </para>
477 </section>
478
479 <section id='structure-build-tmp-buildstats'>
480 <title><filename>build/tmp/buildstats/</filename></title>
481
482 <para>
483 This directory stores the build statistics.
484 </para>
485 </section>
486
487 <section id='structure-build-tmp-cache'>
488 <title><filename>build/tmp/cache/</filename></title>
489
490 <para>
491 When BitBake parses the metadata (recipes and configuration files),
492 it caches the results in <filename>build/tmp/cache/</filename>
493 to speed up future builds.
494 The results are stored on a per-machine basis.
495 </para>
496
497 <para>
498 During subsequent builds, BitBake checks each recipe (together
499 with, for example, any files included or appended to it) to see
500 if they have been modified.
501 Changes can be detected, for example, through file modification
502 time (mtime) changes and hashing of file contents.
503 If no changes to the file are detected, then the parsed result
504 stored in the cache is reused.
505 If the file has changed, it is reparsed.
506 </para>
507 </section>
508
509 <section id='structure-build-tmp-deploy'>
510 <title><filename>build/tmp/deploy/</filename></title>
511
512 <para>
513 This directory contains any "end result" output from the
514 OpenEmbedded build process.
515 The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
516 variable points to this directory.
517 For more detail on the contents of the <filename>deploy</filename>
518 directory, see the
519 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
520 and
521 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
522 sections in the Yocto Project Overview and Concepts Manual.
523 </para>
524 </section>
525
526 <section id='structure-build-tmp-deploy-deb'>
527 <title><filename>build/tmp/deploy/deb/</filename></title>
528
529 <para>
530 This directory receives any <filename>.deb</filename> packages produced by
531 the build process.
532 The packages are sorted into feeds for different architecture types.
533 </para>
534 </section>
535
536 <section id='structure-build-tmp-deploy-rpm'>
537 <title><filename>build/tmp/deploy/rpm/</filename></title>
538
539 <para>
540 This directory receives any <filename>.rpm</filename> packages produced by
541 the build process.
542 The packages are sorted into feeds for different architecture types.
543 </para>
544 </section>
545
546 <section id='structure-build-tmp-deploy-ipk'>
547 <title><filename>build/tmp/deploy/ipk/</filename></title>
548
549 <para>
550 This directory receives <filename>.ipk</filename> packages produced by
551 the build process.
552 </para>
553 </section>
554
555 <section id='structure-build-tmp-deploy-licenses'>
556 <title><filename>build/tmp/deploy/licenses/</filename></title>
557
558 <para>
559 This directory receives package licensing information.
560 For example, the directory contains sub-directories for <filename>bash</filename>,
561 <filename>busybox</filename>, and <filename>glibc</filename> (among others) that in turn
562 contain appropriate <filename>COPYING</filename> license files with other licensing information.
563 For information on licensing, see the
564 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
565 section in the Yocto Project Development Tasks Manual.
566 </para>
567 </section>
568
569 <section id='structure-build-tmp-deploy-images'>
570 <title><filename>build/tmp/deploy/images/</filename></title>
571
572 <para>
573 This directory is populated with the basic output objects of the
574 build (think of them as the "generated artifacts" of the build process),
575 including things like the boot loader image, kernel, root filesystem and more.
576 If you want to flash the resulting image from a build onto a device,
577 look here for the necessary components.
578 </para>
579
580 <para>
581 Be careful when deleting files in this directory.
582 You can safely delete old images from this directory (e.g.
583 <filename>core-image-*</filename>).
584 However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
585 bootloader and other supplementary files might be deployed here prior to building an
586 image.
587 Because these files are not directly produced from the image, if you
588 delete them they will not be automatically re-created when you build the image again.
589 </para>
590
591 <para>
592 If you do accidentally delete files here, you will need to force them to be
593 re-created.
594 In order to do that, you will need to know the target that produced them.
595 For example, these commands rebuild and re-create the kernel files:
596 <literallayout class='monospaced'>
597 $ bitbake -c clean virtual/kernel
598 $ bitbake virtual/kernel
599 </literallayout>
600 </para>
601 </section>
602
603 <section id='structure-build-tmp-deploy-sdk'>
604 <title><filename>build/tmp/deploy/sdk/</filename></title>
605
606 <para>
607 The OpenEmbedded build system creates this directory to hold
608 toolchain installer scripts which, when executed, install the
609 sysroot that matches your target hardware.
610 You can find out more about these installers in the
611 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
612 section in the Yocto Project Application Development and the
613 Extensible Software Development Kit (eSDK) manual.
614 </para>
615 </section>
616
617 <section id='structure-build-tmp-sstate-control'>
618 <title><filename>build/tmp/sstate-control/</filename></title>
619
620 <para>
621 The OpenEmbedded build system uses this directory for the
622 shared state manifest files.
623 The shared state code uses these files to record the files
624 installed by each sstate task so that the files can be removed
625 when cleaning the recipe or when a newer version is about to
626 be installed.
627 The build system also uses the manifests to detect and produce
628 a warning when files from one task are overwriting those from
629 another.
630 </para>
631 </section>
632
633 <section id='structure-build-tmp-sysroots-components'>
634 <title><filename>build/tmp/sysroots-components/</filename></title>
635
636 <para>
637 This directory is the location of the sysroot contents that the
638 task
639 <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
640 links or copies into the recipe-specific sysroot for each
641 recipe listed in
642 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
643 Population of this directory is handled through shared state, while
644 the path is specified by the
645 <link linkend='var-COMPONENTS_DIR'><filename>COMPONENTS_DIR</filename></link>
646 variable. Apart from a few unusual circumstances, handling of the
647 <filename>sysroots-components</filename> directory should be
648 automatic, and recipes should not directly reference
649 <filename>build/tmp/sysroots-components</filename>.
650 </para>
651 </section>
652
653 <section id='structure-build-tmp-sysroots'>
654 <title><filename>build/tmp/sysroots/</filename></title>
655
656 <para>
657 Previous versions of the OpenEmbedded build system used to
658 create a global shared sysroot per machine along with a native
659 sysroot.
660 Beginning with the &DISTRO; version of the Yocto Project,
661 sysroots exist in recipe-specific
662 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
663 directories.
664 Thus, the <filename>build/tmp/sysroots/</filename> directory
665 is unused.
666 <note>
667 The <filename>build/tmp/sysroots/</filename> directory
668 can still be populated using the
669 <filename>bitbake build-sysroots</filename> command and can
670 be used for compatibility in some cases.
671 However, in general it is not recommended to populate
672 this directory.
673 Individual recipe-specific sysroots should be used.
674 </note>
675 </para>
676 </section>
677
678 <section id='structure-build-tmp-stamps'>
679 <title><filename>build/tmp/stamps/</filename></title>
680
681 <para>
682 This directory holds information that BitBake uses for
683 accounting purposes to track what tasks have run and when they
684 have run.
685 The directory is sub-divided by architecture, package name, and
686 version.
687 Following is an example:
688 <literallayout class='monospaced'>
689 stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
690 </literallayout>
691 Although the files in the directory are empty of data,
692 BitBake uses the filenames and timestamps for tracking purposes.
693 </para>
694
695 <para>
696 For information on how BitBake uses stamp files to determine if
697 a task should be rerun, see the
698 "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
699 section in the Yocto Project Overview and Concepts Manual.
700 </para>
701 </section>
702
703 <section id='structure-build-tmp-log'>
704 <title><filename>build/tmp/log/</filename></title>
705
706 <para>
707 This directory contains general logs that are not otherwise placed using the
708 package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
709 Examples of logs are the output from the
710 <filename>do_check_pkg</filename> or
711 <filename>do_distro_check</filename> tasks.
712 Running a build does not necessarily mean this directory is created.
713 </para>
714 </section>
715
716 <section id='structure-build-tmp-work'>
717 <title><filename>build/tmp/work/</filename></title>
718
719 <para>
720 This directory contains architecture-specific work sub-directories
721 for packages built by BitBake.
722 All tasks execute from the appropriate work directory.
723 For example, the source for a particular package is unpacked,
724 patched, configured and compiled all within its own work directory.
725 Within the work directory, organization is based on the package group
726 and version for which the source is being compiled
727 as defined by the
728 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
729 </para>
730
731 <para>
732 It is worth considering the structure of a typical work directory.
733 As an example, consider <filename>linux-yocto-kernel-3.0</filename>
734 on the machine <filename>qemux86</filename>
735 built within the Yocto Project.
736 For this package, a work directory of
737 <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
738 referred to as the <filename>WORKDIR</filename>, is created.
739 Within this directory, the source is unpacked to
740 <filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
741 (See the
742 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using Quilt in Your Workflow</ulink>"
743 section in the Yocto Project Development Tasks Manual for more
744 information.)
745 Within the <filename>linux-qemux86-standard-build</filename> directory,
746 standard Quilt directories <filename>linux-3.0/patches</filename>
747 and <filename>linux-3.0/.pc</filename> are created,
748 and standard Quilt commands can be used.
749 </para>
750
751 <para>
752 There are other directories generated within <filename>WORKDIR</filename>.
753 The most important directory is <filename>WORKDIR/temp/</filename>,
754 which has log files for each task (<filename>log.do_*.pid</filename>)
755 and contains the scripts BitBake runs for each task
756 (<filename>run.do_*.pid</filename>).
757 The <filename>WORKDIR/image/</filename> directory is where "make
758 install" places its output that is then split into sub-packages
759 within <filename>WORKDIR/packages-split/</filename>.
760 </para>
761 </section>
762
763 <section id='structure-build-tmp-work-tunearch-recipename-version'>
764 <title><filename>build/tmp/work/<replaceable>tunearch</replaceable>/<replaceable>recipename</replaceable>/<replaceable>version</replaceable>/</filename></title>
765
766 <para>
767 The recipe work directory - <filename>${WORKDIR}</filename>.
768 </para>
769
770 <para>
771 As described earlier in the
772 "<link linkend='structure-build-tmp-sysroots'><filename>build/tmp/sysroots/</filename></link>"
773 section, beginning with the &DISTRO; release of the Yocto
774 Project, the OpenEmbedded build system builds each recipe in its
775 own work directory (i.e.
776 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
777 The path to the work directory is constructed using the
778 architecture of the given build (e.g.
779 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>,
780 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>,
781 or "allarch"), the recipe name, and the version of the recipe (i.e.
782 <link linkend='var-PE'><filename>PE</filename></link><filename>:</filename><link linkend='var-PV'><filename>PV</filename></link><filename>-</filename><link linkend='var-PR'><filename>PR</filename></link>).
783 </para>
784
785 <para>
786 A number of key subdirectories exist within each recipe
787 work directory:
788 <itemizedlist>
789 <listitem><para>
790 <filename>${WORKDIR}/temp</filename>:
791 Contains the log files of each task executed for this
792 recipe, the "run" files for each executed task, which
793 contain the code run, and a
794 <filename>log.task_order</filename> file, which lists the
795 order in which tasks were executed.
796 </para></listitem>
797 <listitem><para>
798 <filename>${WORKDIR}/image</filename>:
799 Contains the output of the
800 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
801 task, which corresponds to the
802 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
803 variable in that task.
804 </para></listitem>
805 <listitem><para>
806 <filename>${WORKDIR}/pseudo</filename>:
807 Contains the pseudo database and log for any tasks executed
808 under pseudo for the recipe.
809 </para></listitem>
810 <listitem><para>
811 <filename>${WORKDIR}/sysroot-destdir</filename>:
812 Contains the output of the
813 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
814 task.
815 </para></listitem>
816 <listitem><para>
817 <filename>${WORKDIR}/package</filename>:
818 Contains the output of the
819 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
820 task before the output is split into individual packages.
821 </para></listitem>
822 <listitem><para>
823 <filename>${WORKDIR}/packages-split</filename>:
824 Contains the output of the <filename>do_package</filename>
825 task after the output has been split into individual
826 packages.
827 Subdirectories exist for each individual package created
828 by the recipe.
829 </para></listitem>
830 <listitem><para>
831 <filename>${WORKDIR}/recipe-sysroot</filename>:
832 A directory populated with the target dependencies of the
833 recipe.
834 This directory looks like the target filesystem and
835 contains libraries that the recipe might need to link
836 against (e.g. the C library).
837 </para></listitem>
838 <listitem><para>
839 <filename>${WORKDIR}/recipe-sysroot-native</filename>:
840 A directory populated with the native dependencies of the
841 recipe.
842 This directory contains the tools the recipe needs to build
843 (e.g. the compiler, Autoconf, libtool, and so forth).
844 </para></listitem>
845 <listitem><para>
846 <filename>${WORKDIR}/build</filename>:
847 This subdirectory applies only to recipes that support
848 builds where the source is separate from the
849 build artifacts.
850 The OpenEmbedded build system uses this directory as a
851 separate build directory (i.e.
852 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>).
853 </para></listitem>
854 </itemizedlist>
855 </para>
856 </section>
857
858 <section id='structure-build-work-shared'>
859 <title><filename>build/tmp/work-shared/</filename></title>
860
861 <para>
862 For efficiency, the OpenEmbedded build system creates and uses
863 this directory to hold recipes that share a work directory with
864 other recipes.
865 In practice, this is only used for <filename>gcc</filename>
866 and its variants (e.g. <filename>gcc-cross</filename>,
867 <filename>libgcc</filename>, <filename>gcc-runtime</filename>,
868 and so forth).
869 </para>
870 </section>
871</section>
872
873<section id='structure-meta'>
874 <title>The Metadata - <filename>meta/</filename></title>
875
876 <para>
877 As mentioned previously,
878 <link linkend='metadata'>Metadata</link> is the core
879 of the Yocto Project.
880 Metadata has several important subdivisions:
881 </para>
882
883 <section id='structure-meta-classes'>
884 <title><filename>meta/classes/</filename></title>
885
886 <para>
887 This directory contains the <filename>*.bbclass</filename> files.
888 Class files are used to abstract common code so it can be reused by multiple
889 packages.
890 Every package inherits the <filename>base.bbclass</filename> file.
891 Examples of other important classes are <filename>autotools.bbclass</filename>, which
892 in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
893 Another example is <filename>kernel.bbclass</filename> that contains common code and functions
894 for working with the Linux kernel.
895 Functions like image generation or packaging also have their specific class files
896 such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
897 <filename>package*.bbclass</filename>.
898 </para>
899
900 <para>
901 For reference information on classes, see the
902 "<link linkend='ref-classes'>Classes</link>" chapter.
903 </para>
904 </section>
905
906 <section id='structure-meta-conf'>
907 <title><filename>meta/conf/</filename></title>
908
909 <para>
910 This directory contains the core set of configuration files that start from
911 <filename>bitbake.conf</filename> and from which all other configuration
912 files are included.
913 See the include statements at the end of the
914 <filename>bitbake.conf</filename> file and you will note that even
915 <filename>local.conf</filename> is loaded from there.
916 While <filename>bitbake.conf</filename> sets up the defaults, you can often override
917 these by using the (<filename>local.conf</filename>) file, machine file or
918 the distribution configuration file.
919 </para>
920 </section>
921
922 <section id='structure-meta-conf-machine'>
923 <title><filename>meta/conf/machine/</filename></title>
924
925 <para>
926 This directory contains all the machine configuration files.
927 If you set <filename>MACHINE = "qemux86"</filename>,
928 the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
929 directory.
930 The <filename>include</filename> directory contains various data common to multiple machines.
931 If you want to add support for a new machine to the Yocto Project, look in this directory.
932 </para>
933 </section>
934
935 <section id='structure-meta-conf-distro'>
936 <title><filename>meta/conf/distro/</filename></title>
937
938 <para>
939 The contents of this directory controls any distribution-specific
940 configurations.
941 For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
942 This directory includes the versions and the
943 <filename>SRCDATE</filename> definitions for applications that are configured here.
944 An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
945 Although this file mainly inherits its configuration from Poky.
946 </para>
947 </section>
948
949 <section id='structure-meta-conf-machine-sdk'>
950 <title><filename>meta/conf/machine-sdk/</filename></title>
951
952 <para>
953 The OpenEmbedded build system searches this directory for
954 configuration files that correspond to the value of
955 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
956 By default, 32-bit and 64-bit x86 files ship with the Yocto
957 Project that support some SDK hosts.
958 However, it is possible to extend that support to other SDK hosts
959 by adding additional configuration files in this subdirectory
960 within another layer.
961 </para>
962 </section>
963
964 <section id='structure-meta-files'>
965 <title><filename>meta/files/</filename></title>
966
967 <para>
968 This directory contains common license files and several text files
969 used by the build system.
970 The text files contain minimal device information and
971 lists of files and directories with known permissions.
972 </para>
973 </section>
974
975 <section id='structure-meta-lib'>
976 <title><filename>meta/lib/</filename></title>
977
978 <para>
979 This directory contains OpenEmbedded Python library code
980 used during the build process.
981 </para>
982 </section>
983
984 <section id='structure-meta-recipes-bsp'>
985 <title><filename>meta/recipes-bsp/</filename></title>
986
987 <para>
988 This directory contains anything linking to specific hardware or hardware
989 configuration information such as "u-boot" and "grub".
990 </para>
991 </section>
992
993 <section id='structure-meta-recipes-connectivity'>
994 <title><filename>meta/recipes-connectivity/</filename></title>
995
996 <para>
997 This directory contains libraries and applications related to communication with other devices.
998 </para>
999 </section>
1000
1001 <section id='structure-meta-recipes-core'>
1002 <title><filename>meta/recipes-core/</filename></title>
1003
1004 <para>
1005 This directory contains what is needed to build a basic working Linux image
1006 including commonly used dependencies.
1007 </para>
1008 </section>
1009
1010 <section id='structure-meta-recipes-devtools'>
1011 <title><filename>meta/recipes-devtools/</filename></title>
1012
1013 <para>
1014 This directory contains tools that are primarily used by the build system.
1015 The tools, however, can also be used on targets.
1016 </para>
1017 </section>
1018
1019 <section id='structure-meta-recipes-extended'>
1020 <title><filename>meta/recipes-extended/</filename></title>
1021
1022 <para>
1023 This directory contains non-essential applications that add features compared to the
1024 alternatives in core.
1025 You might need this directory for full tool functionality or for Linux Standard Base (LSB)
1026 compliance.
1027 </para>
1028 </section>
1029
1030 <section id='structure-meta-recipes-gnome'>
1031 <title><filename>meta/recipes-gnome/</filename></title>
1032
1033 <para>
1034 This directory contains all things related to the GTK+ application framework.
1035 </para>
1036 </section>
1037
1038 <section id='structure-meta-recipes-graphics'>
1039 <title><filename>meta/recipes-graphics/</filename></title>
1040
1041 <para>
1042 This directory contains X and other graphically related system libraries.
1043 </para>
1044 </section>
1045
1046 <section id='structure-meta-recipes-kernel'>
1047 <title><filename>meta/recipes-kernel/</filename></title>
1048
1049 <para>
1050 This directory contains the kernel and generic applications and libraries that
1051 have strong kernel dependencies.
1052 </para>
1053 </section>
1054
1055 <section id='structure-meta-recipes-lsb4'>
1056 <title><filename>meta/recipes-lsb4/</filename></title>
1057
1058 <para>
1059 This directory contains recipes specifically added to support
1060 the Linux Standard Base (LSB) version 4.x.
1061 </para>
1062 </section>
1063
1064 <section id='structure-meta-recipes-multimedia'>
1065 <title><filename>meta/recipes-multimedia/</filename></title>
1066
1067 <para>
1068 This directory contains codecs and support utilities for audio, images and video.
1069 </para>
1070 </section>
1071
1072 <section id='structure-meta-recipes-rt'>
1073 <title><filename>meta/recipes-rt/</filename></title>
1074
1075 <para>
1076 This directory contains package and image recipes for using and testing
1077 the <filename>PREEMPT_RT</filename> kernel.
1078 </para>
1079 </section>
1080
1081 <section id='structure-meta-recipes-sato'>
1082 <title><filename>meta/recipes-sato/</filename></title>
1083
1084 <para>
1085 This directory contains the Sato demo/reference UI/UX and its associated applications
1086 and configuration data.
1087 </para>
1088 </section>
1089
1090 <section id='structure-meta-recipes-support'>
1091 <title><filename>meta/recipes-support/</filename></title>
1092
1093 <para>
1094 This directory contains recipes used by other recipes, but that are
1095 not directly included in images (i.e. dependencies of other
1096 recipes).
1097 </para>
1098 </section>
1099
1100 <section id='structure-meta-site'>
1101 <title><filename>meta/site/</filename></title>
1102
1103 <para>
1104 This directory contains a list of cached results for various architectures.
1105 Because certain "autoconf" test results cannot be determined when cross-compiling due to
1106 the tests not able to run on a live system, the information in this directory is
1107 passed to "autoconf" for the various architectures.
1108 </para>
1109 </section>
1110
1111 <section id='structure-meta-recipes-txt'>
1112 <title><filename>meta/recipes.txt</filename></title>
1113
1114 <para>
1115 This file is a description of the contents of <filename>recipes-*</filename>.
1116 </para>
1117 </section>
1118</section>
1119
1120</chapter>
1121<!--
1122vim: expandtab tw=80 ts=4
1123-->
diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css
deleted file mode 100644
index 622ceb8f7e..0000000000
--- a/documentation/ref-manual/ref-style.css
+++ /dev/null
@@ -1,1035 +0,0 @@
1/*
2
3 SPDX-License-Identifier: CC-BY-2.0-UK
4
5 Generic XHTML / DocBook XHTML CSS Stylesheet.
6
7 Browser wrangling and typographic design by
8 Oyvind Kolas / pippin@gimp.org
9
10 Customised for Poky by
11 Matthew Allum / mallum@o-hand.com
12
13 Thanks to:
14 Liam R. E. Quin
15 William Skaggs
16 Jakub Steiner
17
18 Structure
19 ---------
20
21 The stylesheet is divided into the following sections:
22
23 Positioning
24 Margins, paddings, width, font-size, clearing.
25 Decorations
26 Borders, style
27 Colors
28 Colors
29 Graphics
30 Graphical backgrounds
31 Nasty IE tweaks
32 Workarounds needed to make it work in internet explorer,
33 currently makes the stylesheet non validating, but up until
34 this point it is validating.
35 Mozilla extensions
36 Transparency for footer
37 Rounded corners on boxes
38
39*/
40
41
42 /*************** /
43 / Positioning /
44/ ***************/
45
46body {
47 font-family: Verdana, Sans, sans-serif;
48
49 min-width: 640px;
50 width: 80%;
51 margin: 0em auto;
52 padding: 2em 5em 5em 5em;
53 color: #333;
54}
55
56h1,h2,h3,h4,h5,h6,h7 {
57 font-family: Arial, Sans;
58 color: #00557D;
59 clear: both;
60}
61
62h1 {
63 font-size: 2em;
64 text-align: left;
65 padding: 0em 0em 0em 0em;
66 margin: 2em 0em 0em 0em;
67}
68
69h2.subtitle {
70 margin: 0.10em 0em 3.0em 0em;
71 padding: 0em 0em 0em 0em;
72 font-size: 1.8em;
73 padding-left: 20%;
74 font-weight: normal;
75 font-style: italic;
76}
77
78h2 {
79 margin: 2em 0em 0.66em 0em;
80 padding: 0.5em 0em 0em 0em;
81 font-size: 1.5em;
82 font-weight: bold;
83}
84
85h3.subtitle {
86 margin: 0em 0em 1em 0em;
87 padding: 0em 0em 0em 0em;
88 font-size: 142.14%;
89 text-align: right;
90}
91
92h3 {
93 margin: 1em 0em 0.5em 0em;
94 padding: 1em 0em 0em 0em;
95 font-size: 140%;
96 font-weight: bold;
97}
98
99h4 {
100 margin: 1em 0em 0.5em 0em;
101 padding: 1em 0em 0em 0em;
102 font-size: 120%;
103 font-weight: bold;
104}
105
106h5 {
107 margin: 1em 0em 0.5em 0em;
108 padding: 1em 0em 0em 0em;
109 font-size: 110%;
110 font-weight: bold;
111}
112
113h6 {
114 margin: 1em 0em 0em 0em;
115 padding: 1em 0em 0em 0em;
116 font-size: 110%;
117 font-weight: bold;
118}
119
120.authorgroup {
121 background-color: transparent;
122 background-repeat: no-repeat;
123 padding-top: 256px;
124 background-image: url("figures/poky-title.png");
125 background-position: left top;
126 margin-top: -256px;
127 padding-right: 50px;
128 margin-left: 0px;
129 text-align: right;
130 width: 740px;
131}
132
133h3.author {
134 margin: 0em 0me 0em 0em;
135 padding: 0em 0em 0em 0em;
136 font-weight: normal;
137 font-size: 100%;
138 color: #333;
139 clear: both;
140}
141
142.author tt.email {
143 font-size: 66%;
144}
145
146.titlepage hr {
147 width: 0em;
148 clear: both;
149}
150
151.revhistory {
152 padding-top: 2em;
153 clear: both;
154}
155
156.toc,
157.list-of-tables,
158.list-of-examples,
159.list-of-figures {
160 padding: 1.33em 0em 2.5em 0em;
161 color: #00557D;
162}
163
164.toc p,
165.list-of-tables p,
166.list-of-figures p,
167.list-of-examples p {
168 padding: 0em 0em 0em 0em;
169 padding: 0em 0em 0.3em;
170 margin: 1.5em 0em 0em 0em;
171}
172
173.toc p b,
174.list-of-tables p b,
175.list-of-figures p b,
176.list-of-examples p b{
177 font-size: 100.0%;
178 font-weight: bold;
179}
180
181.toc dl,
182.list-of-tables dl,
183.list-of-figures dl,
184.list-of-examples dl {
185 margin: 0em 0em 0.5em 0em;
186 padding: 0em 0em 0em 0em;
187}
188
189.toc dt {
190 margin: 0em 0em 0em 0em;
191 padding: 0em 0em 0em 0em;
192}
193
194.toc dd {
195 margin: 0em 0em 0em 2.6em;
196 padding: 0em 0em 0em 0em;
197}
198
199/* Use this set when you decide to get the images in for variables.
200
201div.glossary dl,
202div.variablelist dl {
203}
204
205.glossary dl dt,
206.variablelist dl dt,
207.variablelist dl dt span.term {
208 font-weight: normal;
209 width: 0em;
210 text-align: right;
211}
212
213.variablelist dl dt {
214 margin-top: 0.5em;
215}
216
217.glossary dl dd,
218.variablelist dl dd {
219 margin-top: 0em;
220 margin-left: 15.5em;
221 margin-bottom: 2em;
222}
223
224.glossary dd p,
225.variablelist dd p {
226 margin-top: 0em;
227 margin-bottom: 1em;
228}
229
230.glossdeffirst {
231 text-indent: -70px;
232}
233*/
234
235/* Start of non-image set */
236
237div.glossary dl,
238div.variablelist dl {
239}
240
241.glossary dl dt,
242.variablelist dl dt,
243.variablelist dl dt span.term {
244 font-weight: normal;
245 width: 20em;
246 text-align: right;
247}
248
249.variablelist dl dt {
250 margin-top: 0.5em;
251}
252
253.glossary dl dd,
254.variablelist dl dd {
255 margin-top: 0em;
256 margin-left: 25.5em;
257}
258
259.glossary dd p,
260.variablelist dd p {
261 margin-top: 0em;
262 margin-bottom: 1em;
263}
264
265.glossdeffirst {
266 text-indent: 0px;
267}
268
269/* End of non-image set */
270
271div.calloutlist table td {
272 padding: 0em 0em 0em 0em;
273 margin: 0em 0em 0em 0em;
274}
275
276div.calloutlist table td p {
277 margin-top: 0em;
278 margin-bottom: 1em;
279}
280
281div p.copyright {
282 text-align: left;
283}
284
285div.legalnotice p.legalnotice-title {
286 margin-bottom: 0em;
287}
288
289p {
290 line-height: 1.5em;
291 margin-top: 0em;
292
293}
294
295dl {
296 padding-top: 0em;
297}
298
299hr {
300 border: solid 1px;
301}
302
303
304.mediaobject,
305.mediaobjectco {
306 text-align: center;
307}
308
309img {
310 border: none;
311}
312
313ul {
314 padding: 0em 0em 0em 1.5em;
315}
316
317ul li {
318 padding: 0em 0em 0em 0em;
319}
320
321ul li p {
322 text-align: left;
323}
324
325table {
326 width :100%;
327}
328
329th {
330 padding: 0.25em;
331 text-align: left;
332 font-weight: normal;
333 vertical-align: top;
334}
335
336td {
337 padding: 0.25em;
338 vertical-align: top;
339}
340
341p a[id] {
342 margin: 0px;
343 padding: 0px;
344 display: inline;
345 background-image: none;
346}
347
348a {
349 text-decoration: underline;
350 color: #444;
351}
352
353pre {
354 overflow: auto;
355}
356
357a:hover {
358 text-decoration: underline;
359 /*font-weight: bold;*/
360}
361
362/* This style defines how the permalink character
363 appears by itself and when hovered over with
364 the mouse. */
365
366[alt='Permalink'] { color: #eee; }
367[alt='Permalink']:hover { color: black; }
368
369
370div.informalfigure,
371div.informalexample,
372div.informaltable,
373div.figure,
374div.table,
375div.example {
376 margin: 1em 0em;
377 padding: 1em;
378 page-break-inside: avoid;
379}
380
381
382div.informalfigure p.title b,
383div.informalexample p.title b,
384div.informaltable p.title b,
385div.figure p.title b,
386div.example p.title b,
387div.table p.title b{
388 padding-top: 0em;
389 margin-top: 0em;
390 font-size: 100%;
391 font-weight: normal;
392}
393
394.mediaobject .caption,
395.mediaobject .caption p {
396 text-align: center;
397 font-size: 80%;
398 padding-top: 0.5em;
399 padding-bottom: 0.5em;
400}
401
402.epigraph {
403 padding-left: 55%;
404 margin-bottom: 1em;
405}
406
407.epigraph p {
408 text-align: left;
409}
410
411.epigraph .quote {
412 font-style: italic;
413}
414.epigraph .attribution {
415 font-style: normal;
416 text-align: right;
417}
418
419span.application {
420 font-style: italic;
421}
422
423.programlisting {
424 font-family: monospace;
425 font-size: 80%;
426 white-space: pre;
427 margin: 1.33em 0em;
428 padding: 1.33em;
429}
430
431.tip,
432.warning,
433.caution,
434.note {
435 margin-top: 1em;
436 margin-bottom: 1em;
437
438}
439
440/* force full width of table within div */
441.tip table,
442.warning table,
443.caution table,
444.note table {
445 border: none;
446 width: 100%;
447}
448
449
450.tip table th,
451.warning table th,
452.caution table th,
453.note table th {
454 padding: 0.8em 0.0em 0.0em 0.0em;
455 margin : 0em 0em 0em 0em;
456}
457
458.tip p,
459.warning p,
460.caution p,
461.note p {
462 margin-top: 0.5em;
463 margin-bottom: 0.5em;
464 padding-right: 1em;
465 text-align: left;
466}
467
468.acronym {
469 text-transform: uppercase;
470}
471
472b.keycap,
473.keycap {
474 padding: 0.09em 0.3em;
475 margin: 0em;
476}
477
478.itemizedlist li {
479 clear: none;
480}
481
482.filename {
483 font-size: medium;
484 font-family: Courier, monospace;
485}
486
487
488div.navheader, div.heading{
489 position: absolute;
490 left: 0em;
491 top: 0em;
492 width: 100%;
493 background-color: #cdf;
494 width: 100%;
495}
496
497div.navfooter, div.footing{
498 position: fixed;
499 left: 0em;
500 bottom: 0em;
501 background-color: #eee;
502 width: 100%;
503}
504
505
506div.navheader td,
507div.navfooter td {
508 font-size: 66%;
509}
510
511div.navheader table th {
512 /*font-family: Georgia, Times, serif;*/
513 /*font-size: x-large;*/
514 font-size: 80%;
515}
516
517div.navheader table {
518 border-left: 0em;
519 border-right: 0em;
520 border-top: 0em;
521 width: 100%;
522}
523
524div.navfooter table {
525 border-left: 0em;
526 border-right: 0em;
527 border-bottom: 0em;
528 width: 100%;
529}
530
531div.navheader table td a,
532div.navfooter table td a {
533 color: #777;
534 text-decoration: none;
535}
536
537/* normal text in the footer */
538div.navfooter table td {
539 color: black;
540}
541
542div.navheader table td a:visited,
543div.navfooter table td a:visited {
544 color: #444;
545}
546
547
548/* links in header and footer */
549div.navheader table td a:hover,
550div.navfooter table td a:hover {
551 text-decoration: underline;
552 background-color: transparent;
553 color: #33a;
554}
555
556div.navheader hr,
557div.navfooter hr {
558 display: none;
559}
560
561
562.qandaset tr.question td p {
563 margin: 0em 0em 1em 0em;
564 padding: 0em 0em 0em 0em;
565}
566
567.qandaset tr.answer td p {
568 margin: 0em 0em 1em 0em;
569 padding: 0em 0em 0em 0em;
570}
571.answer td {
572 padding-bottom: 1.5em;
573}
574
575.emphasis {
576 font-weight: bold;
577}
578
579
580 /************* /
581 / decorations /
582/ *************/
583
584.titlepage {
585}
586
587.part .title {
588}
589
590.subtitle {
591 border: none;
592}
593
594/*
595h1 {
596 border: none;
597}
598
599h2 {
600 border-top: solid 0.2em;
601 border-bottom: solid 0.06em;
602}
603
604h3 {
605 border-top: 0em;
606 border-bottom: solid 0.06em;
607}
608
609h4 {
610 border: 0em;
611 border-bottom: solid 0.06em;
612}
613
614h5 {
615 border: 0em;
616}
617*/
618
619.programlisting {
620 border: solid 1px;
621}
622
623div.figure,
624div.table,
625div.informalfigure,
626div.informaltable,
627div.informalexample,
628div.example {
629 border: 1px solid;
630}
631
632
633
634.tip,
635.warning,
636.caution,
637.note {
638 border: 1px solid;
639}
640
641.tip table th,
642.warning table th,
643.caution table th,
644.note table th {
645 border-bottom: 1px solid;
646}
647
648.question td {
649 border-top: 1px solid black;
650}
651
652.answer {
653}
654
655
656b.keycap,
657.keycap {
658 border: 1px solid;
659}
660
661
662div.navheader, div.heading{
663 border-bottom: 1px solid;
664}
665
666
667div.navfooter, div.footing{
668 border-top: 1px solid;
669}
670
671 /********* /
672 / colors /
673/ *********/
674
675body {
676 color: #333;
677 background: white;
678}
679
680a {
681 background: transparent;
682}
683
684a:hover {
685 background-color: #dedede;
686}
687
688
689h1,
690h2,
691h3,
692h4,
693h5,
694h6,
695h7,
696h8 {
697 background-color: transparent;
698}
699
700hr {
701 border-color: #aaa;
702}
703
704
705.tip, .warning, .caution, .note {
706 border-color: #fff;
707}
708
709
710.tip table th,
711.warning table th,
712.caution table th,
713.note table th {
714 border-bottom-color: #fff;
715}
716
717
718.warning {
719 background-color: #f0f0f2;
720}
721
722.caution {
723 background-color: #f0f0f2;
724}
725
726.tip {
727 background-color: #f0f0f2;
728}
729
730.note {
731 background-color: #f0f0f2;
732}
733
734.glossary dl dt,
735.variablelist dl dt,
736.variablelist dl dt span.term {
737 color: #044;
738}
739
740div.figure,
741div.table,
742div.example,
743div.informalfigure,
744div.informaltable,
745div.informalexample {
746 border-color: #aaa;
747}
748
749pre.programlisting {
750 color: black;
751 background-color: #fff;
752 border-color: #aaa;
753 border-width: 2px;
754}
755
756.guimenu,
757.guilabel,
758.guimenuitem {
759 background-color: #eee;
760}
761
762
763b.keycap,
764.keycap {
765 background-color: #eee;
766 border-color: #999;
767}
768
769
770div.navheader {
771 border-color: black;
772}
773
774
775div.navfooter {
776 border-color: black;
777}
778
779.writernotes {
780 color: red;
781}
782
783
784 /*********** /
785 / graphics /
786/ ***********/
787
788/*
789body {
790 background-image: url("images/body_bg.jpg");
791 background-attachment: fixed;
792}
793
794.navheader,
795.note,
796.tip {
797 background-image: url("images/note_bg.jpg");
798 background-attachment: fixed;
799}
800
801.warning,
802.caution {
803 background-image: url("images/warning_bg.jpg");
804 background-attachment: fixed;
805}
806
807.figure,
808.informalfigure,
809.example,
810.informalexample,
811.table,
812.informaltable {
813 background-image: url("images/figure_bg.jpg");
814 background-attachment: fixed;
815}
816
817*/
818h1,
819h2,
820h3,
821h4,
822h5,
823h6,
824h7{
825}
826
827/*
828Example of how to stick an image as part of the title.
829
830div.article .titlepage .title
831{
832 background-image: url("figures/white-on-black.png");
833 background-position: center;
834 background-repeat: repeat-x;
835}
836*/
837
838div.preface .titlepage .title,
839div.colophon .title,
840div.chapter .titlepage .title,
841div.article .titlepage .title
842{
843}
844
845div.section div.section .titlepage .title,
846div.sect2 .titlepage .title {
847 background: none;
848}
849
850
851h1.title {
852 background-color: transparent;
853 background-image: url("figures/poky-title.png");
854 background-repeat: no-repeat;
855 height: 256px;
856 text-indent: -9000px;
857 overflow:hidden;
858}
859
860h2.subtitle {
861 background-color: transparent;
862 text-indent: -9000px;
863 overflow:hidden;
864 width: 0px;
865 display: none;
866}
867
868 /*************************************** /
869 / pippin.gimp.org specific alterations /
870/ ***************************************/
871
872/*
873div.heading, div.navheader {
874 color: #777;
875 font-size: 80%;
876 padding: 0;
877 margin: 0;
878 text-align: left;
879 position: absolute;
880 top: 0px;
881 left: 0px;
882 width: 100%;
883 height: 50px;
884 background: url('/gfx/heading_bg.png') transparent;
885 background-repeat: repeat-x;
886 background-attachment: fixed;
887 border: none;
888}
889
890div.heading a {
891 color: #444;
892}
893
894div.footing, div.navfooter {
895 border: none;
896 color: #ddd;
897 font-size: 80%;
898 text-align:right;
899
900 width: 100%;
901 padding-top: 10px;
902 position: absolute;
903 bottom: 0px;
904 left: 0px;
905
906 background: url('/gfx/footing_bg.png') transparent;
907}
908*/
909
910
911
912 /****************** /
913 / nasty ie tweaks /
914/ ******************/
915
916/*
917div.heading, div.navheader {
918 width:expression(document.body.clientWidth + "px");
919}
920
921div.footing, div.navfooter {
922 width:expression(document.body.clientWidth + "px");
923 margin-left:expression("-5em");
924}
925body {
926 padding:expression("4em 5em 0em 5em");
927}
928*/
929
930 /**************************************** /
931 / mozilla vendor specific css extensions /
932/ ****************************************/
933/*
934div.navfooter, div.footing{
935 -moz-opacity: 0.8em;
936}
937
938div.figure,
939div.table,
940div.informalfigure,
941div.informaltable,
942div.informalexample,
943div.example,
944.tip,
945.warning,
946.caution,
947.note {
948 -moz-border-radius: 0.5em;
949}
950
951b.keycap,
952.keycap {
953 -moz-border-radius: 0.3em;
954}
955*/
956
957table tr td table tr td {
958 display: none;
959}
960
961
962hr {
963 display: none;
964}
965
966table {
967 border: 0em;
968}
969
970 .photo {
971 float: right;
972 margin-left: 1.5em;
973 margin-bottom: 1.5em;
974 margin-top: 0em;
975 max-width: 17em;
976 border: 1px solid gray;
977 padding: 3px;
978 background: white;
979}
980 .seperator {
981 padding-top: 2em;
982 clear: both;
983 }
984
985 #validators {
986 margin-top: 5em;
987 text-align: right;
988 color: #777;
989 }
990 @media print {
991 body {
992 font-size: 8pt;
993 }
994 .noprint {
995 display: none;
996 }
997 }
998
999
1000.tip,
1001.note {
1002 background: #f0f0f2;
1003 color: #333;
1004 padding: 20px;
1005 margin: 20px;
1006}
1007
1008.tip h3,
1009.note h3 {
1010 padding: 0em;
1011 margin: 0em;
1012 font-size: 2em;
1013 font-weight: bold;
1014 color: #333;
1015}
1016
1017.tip a,
1018.note a {
1019 color: #333;
1020 text-decoration: underline;
1021}
1022
1023.footnote {
1024 font-size: small;
1025 color: #333;
1026}
1027
1028/* Changes the announcement text */
1029.tip h3,
1030.warning h3,
1031.caution h3,
1032.note h3 {
1033 font-size:large;
1034 color: #00557D;
1035}
diff --git a/documentation/ref-manual/ref-system-requirements.xml b/documentation/ref-manual/ref-system-requirements.xml
deleted file mode 100644
index ac8b0032db..0000000000
--- a/documentation/ref-manual/ref-system-requirements.xml
+++ /dev/null
@@ -1,577 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-manual-system-requirements'>
7<title>System Requirements</title>
8
9 <para>
10 Welcome to the Yocto Project Reference Manual!
11 This manual provides reference information for the current release
12 of the Yocto Project, and
13 is most effectively used after you have an understanding
14 of the basics of the Yocto Project.
15 The manual is neither meant to be read as a starting point to the
16 Yocto Project, nor read from start to finish.
17 Rather, use this manual to find variable definitions, class
18 descriptions, and so forth as needed during the course of using
19 the Yocto Project.
20 </para>
21
22 <para>
23 For introductory information on the Yocto Project, see the
24 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the
25 "<ulink url='&YOCTO_DOCS_OM_URL;#overview-development-environment'>Yocto Project Development Environment</ulink>"
26 chapter in the Yocto Project Overview and Concepts Manual.
27 </para>
28
29 <para>
30 If you want to use the Yocto Project to quickly build an image
31 without having to understand concepts, work through the
32 <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
33 document.
34 You can find "how-to" information in the
35 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>.
36 You can find Yocto Project overview and conceptual information in the
37 <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
38 <note><title>Tip</title>
39 For more information about the Yocto Project Documentation set,
40 see the
41 "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>"
42 section.
43 </note>
44 </para>
45
46 <section id='detailed-supported-distros'>
47 <title>Supported Linux Distributions</title>
48
49 <para>
50 Currently, the Yocto Project is supported on the following
51 distributions:
52 <note><title>Notes</title>
53 <itemizedlist>
54 <listitem><para>
55 Yocto Project releases are tested against the stable
56 Linux distributions in the following list.
57 The Yocto Project should work on other distributions but
58 validation is not performed against them.
59 </para></listitem>
60 <listitem><para>
61 In particular, the Yocto Project does not support
62 and currently has no plans to support
63 rolling-releases or development distributions due to
64 their constantly changing nature.
65 We welcome patches and bug reports, but keep in mind
66 that our priority is on the supported platforms listed
67 below.
68 </para></listitem>
69 <listitem><para>
70 You may use Windows Subsystem For Linux v2 to set up a build
71 host using Windows 10, but validation is not performed
72 against build hosts using WSLv2.
73 <note>
74 The Yocto Project is not compatible with WSLv1, it is
75 compatible but not officially supported nor validated
76 with WSLv2, if you still decide to use WSL please upgrade
77 to WSLv2.
78 </note>
79 </para></listitem>
80 <listitem><para>
81 If you encounter problems, please go to
82 <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
83 and submit a bug.
84 We are interested in hearing about your experience.
85 For information on how to submit a bug, see the
86 Yocto Project
87 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>
88 and the
89 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
90 section in the Yocto Project Development Tasks Manual.
91 </para></listitem>
92 </itemizedlist>
93 </note>
94 <itemizedlist>
95 <listitem><para>Ubuntu 16.04 (LTS)</para></listitem>
96 <listitem><para>Ubuntu 18.04 (LTS)</para></listitem>
97 <listitem><para>Ubuntu 20.04</para></listitem>
98 <listitem><para>Fedora 30</para></listitem>
99 <listitem><para>Fedora 31</para></listitem>
100 <listitem><para>Fedora 32</para></listitem>
101 <listitem><para>CentOS 7.x</para></listitem>
102 <listitem><para>CentOS 8.x</para></listitem>
103 <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem>
104 <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem>
105 <listitem><para>Debian GNU/Linux 10.x (Buster)</para></listitem>
106 <listitem><para>OpenSUSE Leap 15.1</para></listitem>
107 </itemizedlist>
108 </para>
109
110 <note>
111 While the Yocto Project Team attempts to ensure all Yocto Project
112 releases are one hundred percent compatible with each officially
113 supported Linux distribution, instances might exist where you
114 encounter a problem while using the Yocto Project on a specific
115 distribution.
116 </note>
117 </section>
118
119 <section id='required-packages-for-the-build-host'>
120 <title>Required Packages for the Build Host</title>
121
122 <para>
123 The list of packages you need on the host development system can
124 be large when covering all build scenarios using the Yocto Project.
125 This section describes required packages according to
126 Linux distribution and function.
127 </para>
128
129 <section id='ubuntu-packages'>
130 <title>Ubuntu and Debian</title>
131
132 <para>
133 The following list shows the required packages by function
134 given a supported Ubuntu or Debian Linux distribution:
135 <note><title>Notes</title>
136 <itemizedlist>
137 <listitem><para>
138 If your build system has the
139 <filename>oss4-dev</filename> package installed, you
140 might experience QEMU build failures due to the package
141 installing its own custom
142 <filename>/usr/include/linux/soundcard.h</filename> on
143 the Debian system.
144 If you run into this situation, either of the following
145 solutions exist:
146 <literallayout class='monospaced'>
147 $ sudo apt-get build-dep qemu
148 $ sudo apt-get remove oss4-dev
149 </literallayout>
150 </para></listitem>
151 <listitem><para>
152 For Debian-8, <filename>python3-git</filename> and <filename>pylint3</filename> are no longer available via <filename>apt-get</filename>.
153 <literallayout class='monospaced'>
154 $ sudo pip3 install GitPython pylint==1.9.5
155 </literallayout>
156 </para></listitem>
157 </itemizedlist>
158 </note>
159 <itemizedlist>
160 <listitem><para><emphasis>Essentials:</emphasis>
161 Packages needed to build an image on a headless
162 system:
163 <literallayout class='monospaced'>
164 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
165 </literallayout></para></listitem>
166 <listitem><para><emphasis>Documentation:</emphasis>
167 Packages needed if you are going to build out the
168 Yocto Project documentation manuals:
169 <literallayout class='monospaced'>
170 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
171 </literallayout></para></listitem>
172 </itemizedlist>
173 </para>
174 </section>
175
176 <section id='fedora-packages'>
177 <title>Fedora Packages</title>
178
179 <para>
180 The following list shows the required packages by function
181 given a supported Fedora Linux distribution:
182 <itemizedlist>
183 <listitem><para><emphasis>Essentials:</emphasis>
184 Packages needed to build an image for a headless
185 system:
186 <literallayout class='monospaced'>
187 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
188 </literallayout></para></listitem>
189 <listitem><para><emphasis>Documentation:</emphasis>
190 Packages needed if you are going to build out the
191 Yocto Project documentation manuals:
192 <literallayout class='monospaced'>
193 $ sudo dnf install docbook-style-dsssl docbook-style-xsl \
194 docbook-dtds docbook-utils fop libxslt dblatex xmlto
195 </literallayout></para></listitem>
196 </itemizedlist>
197 </para>
198 </section>
199
200 <section id='opensuse-packages'>
201 <title>openSUSE Packages</title>
202
203 <para>
204 The following list shows the required packages by function
205 given a supported openSUSE Linux distribution:
206 <itemizedlist>
207 <listitem><para><emphasis>Essentials:</emphasis>
208 Packages needed to build an image for a headless
209 system:
210 <literallayout class='monospaced'>
211 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
212 </literallayout></para></listitem>
213 <listitem><para><emphasis>Documentation:</emphasis>
214 Packages needed if you are going to build out the
215 Yocto Project documentation manuals:
216 <literallayout class='monospaced'>
217 $ sudo zypper install dblatex xmlto
218 </literallayout></para></listitem>
219 </itemizedlist>
220 </para>
221 </section>
222
223 <section id='centos-7-packages'>
224 <title>CentOS-7 Packages</title>
225
226 <para>
227 The following list shows the required packages by function
228 given a supported CentOS-7 Linux distribution:
229 <itemizedlist>
230 <listitem><para><emphasis>Essentials:</emphasis>
231 Packages needed to build an image for a headless
232 system:
233 <literallayout class='monospaced'>
234 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
235 </literallayout>
236 <note><title>Notes</title>
237 <itemizedlist>
238 <listitem><para>
239 Extra Packages for Enterprise Linux
240 (i.e. <filename>epel-release</filename>)
241 is a collection of packages from Fedora
242 built on RHEL/CentOS for easy installation
243 of packages not included in enterprise
244 Linux by default.
245 You need to install these packages
246 separately.
247 </para></listitem>
248 <listitem><para>
249 The <filename>makecache</filename> command
250 consumes additional Metadata from
251 <filename>epel-release</filename>.
252 </para></listitem>
253 </itemizedlist>
254 </note>
255 </para></listitem>
256 <listitem><para><emphasis>Documentation:</emphasis>
257 Packages needed if you are going to build out the
258 Yocto Project documentation manuals:
259 <literallayout class='monospaced'>
260 $ sudo yum install docbook-style-dsssl docbook-style-xsl \
261 docbook-dtds docbook-utils fop libxslt dblatex xmlto
262 </literallayout>
263 </para></listitem>
264 </itemizedlist>
265 </para>
266 </section>
267
268 <section id='centos-8-packages'>
269 <title>CentOS-8 Packages</title>
270
271 <para>
272 The following list shows the required packages by function
273 given a supported CentOS-8 Linux distribution:
274 <itemizedlist>
275 <listitem><para><emphasis>Essentials:</emphasis>
276 Packages needed to build an image for a headless
277 system:
278 <literallayout class='monospaced'>
279 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
280 </literallayout>
281 <note><title>Notes</title>
282 <itemizedlist>
283 <listitem><para>
284 Extra Packages for Enterprise Linux
285 (i.e. <filename>epel-release</filename>)
286 is a collection of packages from Fedora
287 built on RHEL/CentOS for easy installation
288 of packages not included in enterprise
289 Linux by default.
290 You need to install these packages
291 separately.
292 </para></listitem>
293 <listitem><para>
294 The <filename>PowerTools</filename> repo
295 provides additional packages such as
296 <filename>rpcgen</filename> and
297 <filename>texinfo</filename>.
298 </para></listitem>
299 <listitem><para>
300 The <filename>makecache</filename> command
301 consumes additional Metadata from
302 <filename>epel-release</filename>.
303 </para></listitem>
304 </itemizedlist>
305 </note>
306 </para></listitem>
307 <listitem><para><emphasis>Documentation:</emphasis>
308 Packages needed if you are going to build out the
309 Yocto Project documentation manuals:
310 <literallayout class='monospaced'>
311 $ sudo dnf install docbook-style-dsssl docbook-style-xsl \
312 docbook-dtds docbook-utils fop libxslt dblatex xmlto
313 </literallayout>
314 </para></listitem>
315 </itemizedlist>
316 </para>
317 </section>
318 </section>
319
320 <section id='required-git-tar-python-and-gcc-versions'>
321 <title>Required Git, tar, Python and gcc Versions</title>
322
323 <para>
324 In order to use the build system, your host development system
325 must meet the following version requirements for Git, tar, and
326 Python:
327 <itemizedlist>
328 <listitem><para>Git 1.8.3.1 or greater</para></listitem>
329 <listitem><para>tar 1.28 or greater</para></listitem>
330 <listitem><para>Python 3.5.0 or greater</para></listitem>
331 </itemizedlist>
332 </para>
333
334 <para>
335 If your host development system does not meet all these requirements,
336 you can resolve this by installing a <filename>buildtools</filename>
337 tarball that contains these tools.
338 You can get the tarball one of two ways: download a pre-built
339 tarball or use BitBake to build the tarball.
340 </para>
341
342 <para>
343 In addition, your host development system must meet the following
344 version requirement for gcc:
345 <itemizedlist>
346 <listitem><para>gcc 5.0 or greater</para></listitem>
347 </itemizedlist>
348 </para>
349
350 <para>
351 If your host development system does not meet this requirement,
352 you can resolve this by installing a <filename>buildtools-extended</filename>
353 tarball that contains additional tools, the equivalent of <filename>buildtools-essential</filename>.
354 </para>
355 <section id='installing-a-pre-built-buildtools-tarball-with-install-buildtools-script'>
356 <title>Installing a Pre-Built <filename>buildtools</filename> Tarball with <filename>install-buildtools</filename> script</title>
357
358 <para>
359 The <filename>install-buildtools</filename> script is the easiest
360 of the three methods by which you can get these tools. It downloads
361 a pre-built buildtools installer and automatically installs the tools
362 for you:
363 <orderedlist>
364 <listitem><para>
365 Execute the <filename>install-buildtools</filename> script.
366 Here is an example:
367 <literallayout class='monospaced'>
368 $ cd poky
369 $ scripts/install-buildtools --without-extended-buildtools \
370 --base-url &YOCTO_DL_URL;/releases/yocto \
371 --release yocto-&DISTRO; \
372 --installer-version &DISTRO;
373 </literallayout>
374 <para>
375 During execution, the buildtools tarball will be downloaded,
376 the checksum of the download will be verified, the installer
377 will be run for you, and some basic checks will be run to
378 to make sure the installation is functional.
379 </para>
380 <para>
381 To avoid the need of <filename>sudo</filename> privileges,
382 the <filename>install-buildtools</filename> script will
383 by default tell the installer to install in:
384 <literallayout class='monospaced'>
385 <replaceable>/path/to/</replaceable>poky/buildtools
386 </literallayout>
387 </para>
388 <para>
389 If your host development system needs the additional tools
390 provided in the <filename>buildtools-extended</filename>
391 tarball, you can instead execute the
392 <filename>install-buildtools</filename> script with the
393 default parameters:
394 <literallayout class='monospaced'>
395 $ cd poky
396 $ scripts/install-buildtools
397 </literallayout>
398 </para>
399 </para></listitem>
400 <listitem><para>
401 Source the tools environment setup script by using a
402 command like the following:
403 <literallayout class='monospaced'>
404 $ source <replaceable>/path/to/</replaceable>poky/buildtools/environment-setup-x86_64-pokysdk-linux
405 </literallayout>
406 Of course, you need to supply your installation directory and be
407 sure to use the right file (i.e. i586 or x86_64).
408 </para>
409 <para>
410 After you have sourced the setup script,
411 the tools are added to <filename>PATH</filename>
412 and any other environment variables required to run the
413 tools are initialized.
414 The results are working versions versions of Git, tar,
415 Python and <filename>chrpath</filename>. And in the case of
416 the <filename>buildtools-extended</filename> tarball, additional
417 working versions of tools including <filename>gcc</filename>,
418 <filename>make</filename> and the other tools included in
419 <filename>packagegroup-core-buildessential</filename>.
420 </para></listitem>
421 </orderedlist>
422 </para>
423 </section>
424
425 <section id='downloading-a-pre-built-buildtools-tarball'>
426 <title>Downloading a Pre-Built <filename>buildtools</filename> Tarball</title>
427
428 <para>
429 Downloading and running a pre-built buildtools installer is
430 the easiest of the two methods by which you can get these tools:
431 <orderedlist>
432 <listitem><para>
433 Locate and download the <filename>*.sh</filename> at
434 <ulink url='&YOCTO_RELEASE_DL_URL;/buildtools/'></ulink>.
435 </para></listitem>
436 <listitem><para>
437 Execute the installation script.
438 Here is an example for the traditional installer:
439 <literallayout class='monospaced'>
440 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
441 </literallayout>
442 Here is an example for the extended installer:
443 <literallayout class='monospaced'>
444 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
445 </literallayout>
446 During execution, a prompt appears that allows you to
447 choose the installation directory.
448 For example, you could choose the following:
449 <literallayout class='monospaced'>
450 /home/<replaceable>your-username</replaceable>/buildtools
451 </literallayout>
452 </para></listitem>
453 <listitem><para>
454 Source the tools environment setup script by using a
455 command like the following:
456 <literallayout class='monospaced'>
457 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-i586-poky-linux
458 </literallayout>
459 Of course, you need to supply your installation directory and be
460 sure to use the right file (i.e. i585 or x86-64).
461 </para>
462 <para>
463 After you have sourced the setup script,
464 the tools are added to <filename>PATH</filename>
465 and any other environment variables required to run the
466 tools are initialized.
467 The results are working versions versions of Git, tar,
468 Python and <filename>chrpath</filename>. And in the case of
469 the <filename>buildtools-extended</filename> tarball, additional
470 working versions of tools including <filename>gcc</filename>,
471 <filename>make</filename> and the other tools included in
472 <filename>packagegroup-core-buildessential</filename>.
473 </para></listitem>
474 </orderedlist>
475 </para>
476 </section>
477
478 <section id='building-your-own-buildtools-tarball'>
479 <title>Building Your Own <filename>buildtools</filename> Tarball</title>
480
481 <para>
482 Building and running your own buildtools installer applies
483 only when you have a build host that can already run BitBake.
484 In this case, you use that machine to build the
485 <filename>.sh</filename> file and then
486 take steps to transfer and run it on a
487 machine that does not meet the minimal Git, tar, and Python
488 (or gcc) requirements.
489 </para>
490
491 <para>
492 Here are the steps to take to build and run your own
493 buildtools installer:
494 <orderedlist>
495 <listitem><para>
496 On the machine that is able to run BitBake,
497 be sure you have set up your build environment with
498 the setup script
499 (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
500 </para></listitem>
501 <listitem><para>
502 Run the BitBake command to build the tarball:
503 <literallayout class='monospaced'>
504 $ bitbake buildtools-tarball
505 </literallayout>
506 or run the BitBake command to build the extended tarball:
507 <literallayout class='monospaced'>
508 $ bitbake buildtools-extended-tarball
509 </literallayout>
510 <note>
511 The
512 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
513 variable in your <filename>local.conf</filename> file
514 determines whether you build tools for a 32-bit
515 or 64-bit system.
516 </note>
517 Once the build completes, you can find the
518 <filename>.sh</filename> file that installs
519 the tools in the <filename>tmp/deploy/sdk</filename>
520 subdirectory of the
521 <link linkend='build-directory'>Build Directory</link>.
522 The installer file has the string "buildtools"
523 (or "buildtools-extended") in the name.
524 </para></listitem>
525 <listitem><para>
526 Transfer the <filename>.sh</filename> file from the
527 build host to the machine that does not meet the
528 Git, tar, or Python (or gcc) requirements.
529 </para></listitem>
530 <listitem><para>
531 On the machine that does not meet the requirements,
532 run the <filename>.sh</filename> file
533 to install the tools.
534 Here is an example for the traditional installer:
535 <literallayout class='monospaced'>
536 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
537 </literallayout>
538 Here is an example for the extended installer:
539 <literallayout class='monospaced'>
540 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
541 </literallayout>
542 During execution, a prompt appears that allows you to
543 choose the installation directory.
544 For example, you could choose the following:
545 <literallayout class='monospaced'>
546 /home/<replaceable>your_username</replaceable>/buildtools
547 </literallayout>
548 </para></listitem>
549 <listitem><para>
550 Source the tools environment setup script by using a
551 command like the following:
552 <literallayout class='monospaced'>
553 $ source /home/<replaceable>your_username</replaceable>/buildtools/environment-setup-x86_64-poky-linux
554 </literallayout>
555 Of course, you need to supply your installation directory and be
556 sure to use the right file (i.e. i586 or x86_64).
557 </para>
558 <para>
559 After you have sourced the setup script,
560 the tools are added to <filename>PATH</filename>
561 and any other environment variables required to run the
562 tools are initialized.
563 The results are working versions versions of Git, tar,
564 Python and <filename>chrpath</filename>. And in the case of
565 the <filename>buildtools-extended</filename> tarball, additional
566 working versions of tools including <filename>gcc</filename>,
567 <filename>make</filename> and the other tools included in
568 <filename>packagegroup-core-buildessential</filename>.
569 </para></listitem>
570 </orderedlist>
571 </para>
572 </section>
573 </section>
574</chapter>
575<!--
576vim: expandtab tw=80 ts=4
577-->
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
deleted file mode 100644
index 5b09b3f2e8..0000000000
--- a/documentation/ref-manual/ref-tasks.xml
+++ /dev/null
@@ -1,1131 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-tasks'>
7<title>Tasks</title>
8
9<para>
10 Tasks are units of execution for BitBake.
11 Recipes (<filename>.bb</filename> files) use tasks to complete
12 configuring, compiling, and packaging software.
13 This chapter provides a reference of the tasks defined in the
14 OpenEmbedded build system.
15</para>
16
17<section id='normal-recipe-build-tasks'>
18 <title>Normal Recipe Build Tasks</title>
19
20 <para>
21 The following sections describe normal tasks associated with building
22 a recipe.
23 For more information on tasks and dependencies, see the
24 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
25 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
26 sections in the BitBake User Manual.
27 </para>
28
29 <section id='ref-tasks-build'>
30 <title><filename>do_build</filename></title>
31
32 <para>
33 The default task for all recipes.
34 This task depends on all other normal tasks
35 required to build a recipe.
36 </para>
37 </section>
38
39 <section id='ref-tasks-compile'>
40 <title><filename>do_compile</filename></title>
41
42 <para>
43 Compiles the source code.
44 This task runs with the current working directory set
45 to
46 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>.
47 </para>
48
49 <para>
50 The default behavior of this task is to run the
51 <filename>oe_runmake</filename> function if a makefile
52 (<filename>Makefile</filename>, <filename>makefile</filename>,
53 or <filename>GNUmakefile</filename>) is found.
54 If no such file is found, the <filename>do_compile</filename>
55 task does nothing.
56 </para>
57 </section>
58
59 <section id='ref-tasks-compile_ptest_base'>
60 <title><filename>do_compile_ptest_base</filename></title>
61
62 <para>
63 Compiles the runtime test suite included in the software being
64 built.
65 </para>
66 </section>
67
68 <section id='ref-tasks-configure'>
69 <title><filename>do_configure</filename></title>
70
71 <para>
72 Configures the source by enabling and disabling any build-time and
73 configuration options for the software being built.
74 The task runs with the current working directory set to
75 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>.
76 </para>
77
78 <para>
79 The default behavior of this task is to run
80 <filename>oe_runmake clean</filename> if a makefile
81 (<filename>Makefile</filename>, <filename>makefile</filename>,
82 or <filename>GNUmakefile</filename>) is found and
83 <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link>
84 is not set to "1".
85 If no such file is found or the <filename>CLEANBROKEN</filename>
86 variable is set to "1", the <filename>do_configure</filename>
87 task does nothing.
88 </para>
89 </section>
90
91 <section id='ref-tasks-configure_ptest_base'>
92 <title><filename>do_configure_ptest_base</filename></title>
93
94 <para>
95 Configures the runtime test suite included in the software being
96 built.
97 </para>
98 </section>
99
100 <section id='ref-tasks-deploy'>
101 <title><filename>do_deploy</filename></title>
102
103 <para>
104 Writes output files that are to be deployed to
105 <filename>${</filename><link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link><filename>}</filename>.
106 The task runs with the current working directory set to
107 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>.
108 </para>
109
110 <para>
111 Recipes implementing this task should inherit the
112 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
113 class and should write the output to
114 <filename>${</filename><link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link><filename>}</filename>,
115 which is not to be confused with <filename>${DEPLOY_DIR}</filename>.
116 The <filename>deploy</filename> class sets up
117 <filename>do_deploy</filename> as a shared state (sstate) task that
118 can be accelerated through sstate use.
119 The sstate mechanism takes care of copying the output from
120 <filename>${DEPLOYDIR}</filename> to
121 <filename>${DEPLOY_DIR_IMAGE}</filename>.
122 <note>
123 <title>Caution</title>
124 Do not write the output directly to
125 <filename>${DEPLOY_DIR_IMAGE}</filename>, as this causes
126 the sstate mechanism to malfunction.
127 </note>
128 </para>
129
130 <para>
131 The <filename>do_deploy</filename> task is not added as a task
132 by default and consequently needs to be added manually.
133 If you want the task to run after
134 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
135 you can add it by doing the following:
136 <literallayout class='monospaced'>
137 addtask deploy after do_compile
138 </literallayout>
139 Adding <filename>do_deploy</filename> after other tasks works the
140 same way.
141 <note>
142 You do not need to add <filename>before do_build</filename>
143 to the <filename>addtask</filename> command (though it is
144 harmless), because the
145 <link linkend='ref-classes-base'><filename>base</filename></link>
146 class contains the following:
147 <literallayout class='monospaced'>
148 do_build[recrdeptask] += "do_deploy"
149 </literallayout>
150 See the
151 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
152 section in the BitBake User Manual for more information.
153 </note>
154 </para>
155
156 <para>
157 If the <filename>do_deploy</filename> task re-executes, any
158 previous output is removed (i.e. "cleaned").
159 </para>
160 </section>
161
162 <section id='ref-tasks-fetch'>
163 <title><filename>do_fetch</filename></title>
164
165 <para>
166 Fetches the source code.
167 This task uses the
168 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
169 variable and the argument's prefix to determine the correct
170 <ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>fetcher</ulink>
171 module.
172 </para>
173 </section>
174
175 <section id='ref-tasks-image'>
176 <title><filename>do_image</filename></title>
177
178 <para>
179 Starts the image generation process.
180 The <filename>do_image</filename> task runs after the
181 OpenEmbedded build system has run the
182 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
183 task during which packages are identified for installation into
184 the image and the root filesystem is created, complete with
185 post-processing.
186 </para>
187
188 <para>
189 The <filename>do_image</filename> task performs pre-processing
190 on the image through the
191 <link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link>
192 and dynamically generates supporting
193 <filename>do_image_*</filename> tasks as needed.
194 </para>
195
196 <para>
197 For more information on image creation, see the
198 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
199 section in the Yocto Project Overview and Concepts Manual.
200 </para>
201 </section>
202
203 <section id='ref-tasks-image-complete'>
204 <title><filename>do_image_complete</filename></title>
205
206 <para>
207 Completes the image generation process.
208 The <filename>do_image_complete</filename> task runs after the
209 OpenEmbedded build system has run the
210 <link linkend='ref-tasks-image'><filename>do_image</filename></link>
211 task during which image pre-processing occurs and through
212 dynamically generated <filename>do_image_*</filename> tasks the
213 image is constructed.
214 </para>
215
216 <para>
217 The <filename>do_image_complete</filename> task performs
218 post-processing on the image through the
219 <link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>.
220 </para>
221
222 <para>
223 For more information on image creation, see the
224 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
225 section in the Yocto Project Overview and Concepts Manual.
226 </para>
227 </section>
228
229 <section id='ref-tasks-install'>
230 <title><filename>do_install</filename></title>
231
232 <para>
233 Copies files that are to be packaged into the holding area
234 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
235 This task runs with the current working directory set to
236 <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>,
237 which is the compilation directory.
238 The <filename>do_install</filename> task, as well as other tasks
239 that either directly or indirectly depend on the installed files
240 (e.g.
241 <link linkend='ref-tasks-package'><filename>do_package</filename></link>,
242 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>,
243 and
244 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>),
245 run under
246 <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
247 <note>
248 <title>Caution</title>
249
250 <para>
251 When installing files, be careful not to set the owner and
252 group IDs of the installed files to unintended values.
253 Some methods of copying files, notably when using the
254 recursive <filename>cp</filename> command, can preserve the
255 UID and/or GID of the original file, which is usually not
256 what you want.
257 The
258 <link linkend='insane-host-user-contaminated'><filename>host-user-contaminated</filename></link>
259 QA check checks for files that probably have the wrong
260 ownership.
261 </para>
262
263 <para>
264 Safe methods for installing files include the following:
265 <itemizedlist>
266 <listitem><para>
267 The <filename>install</filename> utility.
268 This utility is the preferred method.
269 </para></listitem>
270 <listitem><para>
271 The <filename>cp</filename> command with the
272 "--no-preserve=ownership" option.
273 </para></listitem>
274 <listitem><para>
275 The <filename>tar</filename> command with the
276 "--no-same-owner" option.
277 See the <filename>bin_package.bbclass</filename>
278 file in the <filename>meta/classes</filename>
279 directory of the
280 <link linkend='source-directory'>Source Directory</link>
281 for an example.
282 </para></listitem>
283 </itemizedlist>
284 </para>
285 </note>
286 </para>
287 </section>
288
289 <section id='ref-tasks-install_ptest_base'>
290 <title><filename>do_install_ptest_base</filename></title>
291
292 <para>
293 Copies the runtime test suite files from the compilation directory
294 to a holding area.
295 </para>
296 </section>
297
298 <section id='ref-tasks-package'>
299 <title><filename>do_package</filename></title>
300
301 <para>
302 Analyzes the content of the holding area
303 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
304 and splits the content into subsets based on available packages
305 and files.
306 This task makes use of the
307 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
308 and
309 <link linkend='var-FILES'><filename>FILES</filename></link>
310 variables.
311 </para>
312
313 <para>
314 The <filename>do_package</filename> task, in conjunction with the
315 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
316 task, also saves some important package metadata.
317 For additional information, see the
318 <link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
319 variable and the
320 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
321 section in the Yocto Project Overview and Concepts Manual.
322 </para>
323 </section>
324
325 <section id='ref-tasks-package_qa'>
326 <title><filename>do_package_qa</filename></title>
327
328 <para>
329 Runs QA checks on packaged files.
330 For more information on these checks, see the
331 <link linkend='ref-classes-insane'><filename>insane</filename></link>
332 class.
333 </para>
334 </section>
335
336 <section id='ref-tasks-package_write_deb'>
337 <title><filename>do_package_write_deb</filename></title>
338
339 <para>
340 Creates Debian packages (i.e. <filename>*.deb</filename> files) and
341 places them in the
342 <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
343 directory in the package feeds area.
344 For more information, see the
345 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
346 section in the Yocto Project Overview and Concepts Manual.
347 </para>
348 </section>
349
350 <section id='ref-tasks-package_write_ipk'>
351 <title><filename>do_package_write_ipk</filename></title>
352
353 <para>
354 Creates IPK packages (i.e. <filename>*.ipk</filename> files) and
355 places them in the
356 <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
357 directory in the package feeds area.
358 For more information, see the
359 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
360 section in the Yocto Project Overview and Concepts Manual.
361 </para>
362 </section>
363
364 <section id='ref-tasks-package_write_rpm'>
365 <title><filename>do_package_write_rpm</filename></title>
366
367 <para>
368 Creates RPM packages (i.e. <filename>*.rpm</filename> files) and
369 places them in the
370 <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
371 directory in the package feeds area.
372 For more information, see the
373 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
374 section in the Yocto Project Overview and Concepts Manual.
375 </para>
376 </section>
377
378 <section id='ref-tasks-package_write_tar'>
379 <title><filename>do_package_write_tar</filename></title>
380
381 <para>
382 Creates tarballs and places them in the
383 <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
384 directory in the package feeds area.
385 For more information, see the
386 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
387 section in the Yocto Project Overview and Concepts Manual.
388 </para>
389 </section>
390
391 <section id='ref-tasks-packagedata'>
392 <title><filename>do_packagedata</filename></title>
393
394 <para>
395 Saves package metadata generated by the
396 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
397 task in
398 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
399 to make it available globally.
400 </para>
401 </section>
402
403 <section id='ref-tasks-patch'>
404 <title><filename>do_patch</filename></title>
405
406 <para>
407 Locates patch files and applies them to the source code.
408 </para>
409
410 <para>
411 After fetching and unpacking source files, the build system
412 uses the recipe's
413 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
414 statements to locate and apply patch files to the source code.
415 <note>
416 The build system uses the
417 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
418 variable to determine the default set of directories when
419 searching for patches.
420 </note>
421 Patch files, by default, are <filename>*.patch</filename> and
422 <filename>*.diff</filename> files created and kept in a
423 subdirectory of the directory holding the recipe file.
424 For example, consider the
425 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5'><filename>bluez5</filename></ulink>
426 recipe from the OE-Core layer (i.e.
427 <filename>poky/meta</filename>):
428 <literallayout class='monospaced'>
429 poky/meta/recipes-connectivity/bluez5
430 </literallayout>
431 This recipe has two patch files located here:
432 <literallayout class='monospaced'>
433 poky/meta/recipes-connectivity/bluez5/bluez5
434 </literallayout>
435 </para>
436
437 <para>
438 In the <filename>bluez5</filename> recipe, the
439 <filename>SRC_URI</filename> statements point to the source and
440 patch files needed to build the package.
441 <note>
442 In the case for the <filename>bluez5_5.48.bb</filename>
443 recipe, the <filename>SRC_URI</filename> statements are from an
444 include file <filename>bluez5.inc</filename>.
445 </note>
446 </para>
447
448 <para>
449 As mentioned earlier, the build system treats files whose file
450 types are <filename>.patch</filename> and
451 <filename>.diff</filename> as patch files.
452 However, you can use the "apply=yes" parameter with the
453 <filename>SRC_URI</filename> statement to indicate any file as a
454 patch file:
455 <literallayout class='monospaced'>
456 SRC_URI = " \
457 git://<replaceable>path_to_repo</replaceable>/<replaceable>some_package</replaceable> \
458 file://<replaceable>file</replaceable>;apply=yes \
459 "
460 </literallayout>
461 </para>
462
463 <para>
464 Conversely, if you have a directory full of patch files and you
465 want to exclude some so that the <filename>do_patch</filename>
466 task does not apply them during the patch phase, you can use
467 the "apply=no" parameter with the <filename>SRC_URI</filename>
468 statement:
469 <literallayout class='monospaced'>
470 SRC_URI = " \
471 git://<replaceable>path_to_repo</replaceable>/<replaceable>some_package</replaceable> \
472 file://<replaceable>path_to_lots_of_patch_files</replaceable> \
473 file://<replaceable>path_to_lots_of_patch_files</replaceable>/<replaceable>patch_file5</replaceable>;apply=no \
474 "
475 </literallayout>
476 In the previous example, assuming all the files in the directory
477 holding the patch files end with either <filename>.patch</filename>
478 or <filename>.diff</filename>, every file would be applied as a
479 patch by default except for the
480 <replaceable>patch_file5</replaceable> patch.
481 </para>
482
483 <para>
484 You can find out more about the patching process in the
485 "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
486 section in the Yocto Project Overview and Concepts Manual and the
487 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
488 section in the Yocto Project Development Tasks Manual.
489 </para>
490 </section>
491
492 <section id='ref-tasks-populate_lic'>
493 <title><filename>do_populate_lic</filename></title>
494
495 <para>
496 Writes license information for the recipe that is collected later
497 when the image is constructed.
498 </para>
499 </section>
500
501 <section id='ref-tasks-populate_sdk'>
502 <title><filename>do_populate_sdk</filename></title>
503
504 <para>
505 Creates the file and directory structure for an installable SDK.
506 See the
507 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-generation-dev-environment'>SDK Generation</ulink>"
508 section in the Yocto Project Overview and Concepts Manual for more
509 information.
510 </para>
511 </section>
512
513 <section id='ref-tasks-populate_sysroot'>
514 <title><filename>do_populate_sysroot</filename></title>
515
516 <para>
517 Stages (copies) a subset of the files installed by the
518 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
519 task into the appropriate sysroot.
520 For information on how to access these files from other recipes,
521 see the
522 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR*</filename></link>
523 variables.
524 Directories that would typically not be needed by other recipes at
525 build time (e.g. <filename>/etc</filename>) are not copied by
526 default.
527 </para>
528
529 <para>
530 For information on what directories are copied by default, see the
531 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS*</filename></link>
532 variables.
533 You can change these variables inside your recipe if you need
534 to make additional (or fewer) directories available to other
535 recipes at build time.
536 </para>
537
538 <para>
539 The <filename>do_populate_sysroot</filename> task is a
540 shared state (sstate) task, which means that the task can
541 be accelerated through sstate use.
542 Realize also that if the task is re-executed, any previous output
543 is removed (i.e. "cleaned").
544 </para>
545 </section>
546
547 <section id='ref-tasks-prepare_recipe_sysroot'>
548 <title><filename>do_prepare_recipe_sysroot</filename></title>
549
550 <para>
551 Installs the files into the individual recipe specific sysroots
552 (i.e. <filename>recipe-sysroot</filename> and
553 <filename>recipe-sysroot-native</filename> under
554 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename>
555 based upon the dependencies specified by
556 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>).
557 See the
558 "<link linkend='ref-classes-staging'><filename>staging</filename></link>"
559 class for more information.
560 </para>
561 </section>
562
563 <section id='ref-tasks-rm_work'>
564 <title><filename>do_rm_work</filename></title>
565
566 <para>
567 Removes work files after the OpenEmbedded build system has
568 finished with them.
569 You can learn more by looking at the
570 "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
571 section.
572 </para>
573 </section>
574
575 <section id='ref-tasks-unpack'>
576 <title><filename>do_unpack</filename></title>
577
578 <para>
579 Unpacks the source code into a working directory pointed to
580 by
581 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename>.
582 The
583 <link linkend='var-S'><filename>S</filename></link> variable also
584 plays a role in where unpacked source files ultimately reside.
585 For more information on how source files are unpacked, see the
586 "<ulink url='&YOCTO_DOCS_OM_URL;#source-fetching-dev-environment'>Source Fetching</ulink>"
587 section in the Yocto Project Overview and Concepts Manual and also
588 see the <filename>WORKDIR</filename> and
589 <filename>S</filename> variable descriptions.
590 </para>
591 </section>
592</section>
593
594<section id='manually-called-tasks'>
595 <title>Manually Called Tasks</title>
596
597 <para>
598 These tasks are typically manually triggered (e.g. by using the
599 <filename>bitbake -c</filename> command-line option):
600 </para>
601
602 <section id='ref-tasks-checkpkg'>
603 <title><filename>do_checkpkg</filename></title>
604
605 <para>
606 Provides information about the recipe including its upstream
607 version and status.
608 The upstream version and status reveals whether or not a version
609 of the recipe exists upstream and a status of not updated, updated,
610 or unknown.
611 </para>
612
613 <para>
614 To check the upstream version and status of a recipe, use the
615 following devtool commands:
616 <literallayout class='monospaced'>
617 $ devtool latest-version
618 $ devtool check-upgrade-status
619 </literallayout>
620 See the
621 "<link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>"
622 chapter for more information on <filename>devtool</filename>.
623 See the
624 "<ulink url='&YOCTO_DOCS_REF_URL;#devtool-checking-on-the-upgrade-status-of-a-recipe'>Checking on the Upgrade Status of a Recipe</ulink>"
625 section for information on checking the upgrade status of a recipe.
626 </para>
627
628 <para>
629 To build the <filename>checkpkg</filename> task, use the
630 <filename>bitbake</filename> command with the "-c" option and
631 task name:
632 <literallayout class='monospaced'>
633 $ bitbake core-image-minimal -c checkpkg
634 </literallayout>
635 By default, the results are stored in
636 <link linkend='var-LOG_DIR'><filename>$LOG_DIR</filename></link>
637 (e.g. <filename>$BUILD_DIR/tmp/log</filename>).
638 </para>
639 </section>
640
641 <section id='ref-tasks-checkuri'>
642 <title><filename>do_checkuri</filename></title>
643
644 <para>
645 Validates the
646 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
647 value.
648 </para>
649 </section>
650
651 <section id='ref-tasks-clean'>
652 <title><filename>do_clean</filename></title>
653
654 <para>
655 Removes all output files for a target from the
656 <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link>
657 task forward (i.e. <filename>do_unpack</filename>,
658 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
659 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
660 <link linkend='ref-tasks-install'><filename>do_install</filename></link>,
661 and
662 <link linkend='ref-tasks-package'><filename>do_package</filename></link>).
663 </para>
664
665 <para>
666 You can run this task using BitBake as follows:
667 <literallayout class='monospaced'>
668 $ bitbake -c clean <replaceable>recipe</replaceable>
669 </literallayout>
670 </para>
671
672 <para>
673 Running this task does not remove the
674 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>
675 cache files.
676 Consequently, if no changes have been made and the recipe is
677 rebuilt after cleaning, output files are simply restored from the
678 sstate cache.
679 If you want to remove the sstate cache files for the recipe,
680 you need to use the
681 <link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link>
682 task instead (i.e. <filename>bitbake -c cleansstate</filename> <replaceable>recipe</replaceable>).
683 </para>
684 </section>
685
686 <section id='ref-tasks-cleanall'>
687 <title><filename>do_cleanall</filename></title>
688
689 <para>
690 Removes all output files, shared state
691 (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
692 cache, and downloaded source files for a target (i.e. the contents
693 of
694 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>).
695 Essentially, the <filename>do_cleanall</filename> task is
696 identical to the
697 <link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link>
698 task with the added removal of downloaded source files.
699 </para>
700
701 <para>
702 You can run this task using BitBake as follows:
703 <literallayout class='monospaced'>
704 $ bitbake -c cleanall <replaceable>recipe</replaceable>
705 </literallayout>
706 </para>
707
708 <para>
709 Typically, you would not normally use the
710 <filename>cleanall</filename> task.
711 Do so only if you want to start fresh with the
712 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>
713 task.
714 </para>
715 </section>
716
717 <section id='ref-tasks-cleansstate'>
718 <title><filename>do_cleansstate</filename></title>
719
720 <para>
721 Removes all output files and shared state
722 (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
723 cache for a target.
724 Essentially, the <filename>do_cleansstate</filename> task is
725 identical to the
726 <link linkend='ref-tasks-clean'><filename>do_clean</filename></link>
727 task with the added removal of shared state
728 (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
729 cache.
730 </para>
731
732 <para>
733 You can run this task using BitBake as follows:
734 <literallayout class='monospaced'>
735 $ bitbake -c cleansstate <replaceable>recipe</replaceable>
736 </literallayout>
737 </para>
738
739 <para>
740 When you run the <filename>do_cleansstate</filename> task,
741 the OpenEmbedded build system no longer uses any
742 sstate.
743 Consequently, building the recipe from scratch is guaranteed.
744 <note>
745 The <filename>do_cleansstate</filename> task cannot remove
746 sstate from a remote sstate mirror.
747 If you need to build a target from scratch using remote
748 mirrors, use the "-f" option as follows:
749 <literallayout class='monospaced'>
750 $ bitbake -f -c do_cleansstate <replaceable>target</replaceable>
751 </literallayout>
752 </note>
753 </para>
754 </section>
755
756 <section id='ref-tasks-devpyshell'>
757 <title><filename>do_devpyshell</filename></title>
758
759 <para>
760 Starts a shell in which an interactive Python interpreter allows
761 you to interact with the BitBake build environment.
762 From within this shell, you can directly examine and set
763 bits from the data store and execute functions as if within
764 the BitBake environment.
765 See the
766 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devpyshell'>Using a Development Python Shell</ulink>"
767 section in the Yocto Project Development Tasks Manual for more
768 information about using <filename>devpyshell</filename>.
769 </para>
770 </section>
771
772 <section id='ref-tasks-devshell'>
773 <title><filename>do_devshell</filename></title>
774
775 <para>
776 Starts a shell whose environment is set up for
777 development, debugging, or both.
778 See the
779 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>"
780 section in the Yocto Project Development Tasks Manual for more
781 information about using <filename>devshell</filename>.
782 </para>
783 </section>
784
785 <section id='ref-tasks-listtasks'>
786 <title><filename>do_listtasks</filename></title>
787
788 <para>
789 Lists all defined tasks for a target.
790 </para>
791 </section>
792
793 <section id='ref-tasks-package_index'>
794 <title><filename>do_package_index</filename></title>
795
796 <para>
797 Creates or updates the index in the
798 <ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>
799 area.
800 <note>
801 This task is not triggered with the
802 <filename>bitbake -c</filename> command-line option as
803 are the other tasks in this section.
804 Because this task is specifically for the
805 <filename>package-index</filename> recipe,
806 you run it using
807 <filename>bitbake package-index</filename>.
808 </note>
809 </para>
810 </section>
811</section>
812
813<section id='image-related-tasks'>
814 <title>Image-Related Tasks</title>
815
816 <para>
817 The following tasks are applicable to image recipes.
818 </para>
819
820 <section id='ref-tasks-bootimg'>
821 <title><filename>do_bootimg</filename></title>
822
823 <para>
824 Creates a bootable live image.
825 See the
826 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
827 variable for additional information on live image types.
828 </para>
829 </section>
830
831 <section id='ref-tasks-bundle_initramfs'>
832 <title><filename>do_bundle_initramfs</filename></title>
833
834 <para>
835 Combines an initial RAM disk (initramfs) image and kernel
836 together to form a single image.
837 The
838 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
839 variable has some more information about these types of images.
840 </para>
841 </section>
842
843 <section id='ref-tasks-rootfs'>
844 <title><filename>do_rootfs</filename></title>
845
846 <para>
847 Creates the root filesystem (file and directory structure) for an
848 image.
849 See the
850 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
851 section in the Yocto Project Overview and Concepts Manual for more
852 information on how the root filesystem is created.
853 </para>
854 </section>
855
856 <section id='ref-tasks-testimage'>
857 <title><filename>do_testimage</filename></title>
858
859 <para>
860 Boots an image and performs runtime tests within the image.
861 For information on automatically testing images, see the
862 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
863 section in the Yocto Project Development Tasks Manual.
864 </para>
865 </section>
866
867 <section id='ref-tasks-testimage_auto'>
868 <title><filename>do_testimage_auto</filename></title>
869
870 <para>
871 Boots an image and performs runtime tests within the image
872 immediately after it has been built.
873 This task is enabled when you set
874 <link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
875 equal to "1".
876 </para>
877
878 <para>
879 For information on automatically testing images, see the
880 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
881 section in the Yocto Project Development Tasks Manual.
882 </para>
883 </section>
884</section>
885
886<section id='kernel-related-tasks'>
887 <title>Kernel-Related Tasks</title>
888
889 <para>
890 The following tasks are applicable to kernel recipes.
891 Some of these tasks (e.g. the
892 <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link>
893 task) are also applicable to recipes that use
894 Linux kernel style configuration such as the BusyBox recipe.
895 </para>
896
897 <section id='ref-tasks-compile_kernelmodules'>
898 <title><filename>do_compile_kernelmodules</filename></title>
899
900 <para>
901 Runs the step that builds the kernel modules (if needed).
902 Building a kernel consists of two steps: 1) the kernel
903 (<filename>vmlinux</filename>) is built, and 2) the modules
904 are built (i.e. <filename>make modules</filename>).
905 </para>
906 </section>
907
908 <section id='ref-tasks-diffconfig'>
909 <title><filename>do_diffconfig</filename></title>
910
911 <para>
912 When invoked by the user, this task creates a file containing the
913 differences between the original config as produced by
914 <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>
915 task and the changes made by the user with other methods
916 (i.e. using
917 (<link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>).
918 Once the file of differences is created, it can be used to create
919 a config fragment that only contains the differences.
920 You can invoke this task from the command line as follows:
921 <literallayout class='monospaced'>
922 $ bitbake linux-yocto -c diffconfig
923 </literallayout>
924 For more information, see the
925 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
926 section in the Yocto Project Linux Kernel Development Manual.
927 </para>
928 </section>
929
930 <section id='ref-tasks-kernel_checkout'>
931 <title><filename>do_kernel_checkout</filename></title>
932
933 <para>
934 Converts the newly unpacked kernel source into a form with which
935 the OpenEmbedded build system can work.
936 Because the kernel source can be fetched in several different ways,
937 the <filename>do_kernel_checkout</filename> task makes sure that
938 subsequent tasks are given a clean working tree copy of the kernel
939 with the correct branches checked out.
940 </para>
941 </section>
942
943 <section id='ref-tasks-kernel_configcheck'>
944 <title><filename>do_kernel_configcheck</filename></title>
945
946 <para>
947 Validates the configuration produced by the
948 <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>
949 task.
950 The <filename>do_kernel_configcheck</filename> task produces
951 warnings when a requested configuration does not appear in the
952 final <filename>.config</filename> file or when you override a
953 policy configuration in a hardware configuration fragment.
954 You can run this task explicitly and view the output by using
955 the following command:
956 <literallayout class='monospaced'>
957 $ bitbake linux-yocto -c kernel_configcheck -f
958 </literallayout>
959 For more information, see the
960 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#validating-configuration'>Validating Configuration</ulink>"
961 section in the Yocto Project Linux Kernel Development Manual.
962 </para>
963 </section>
964
965 <section id='ref-tasks-kernel_configme'>
966 <title><filename>do_kernel_configme</filename></title>
967
968 <para>
969 After the kernel is patched by the
970 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
971 task, the <filename>do_kernel_configme</filename> task assembles
972 and merges all the kernel config fragments into a merged
973 configuration that can then be passed to the kernel configuration
974 phase proper.
975 This is also the time during which user-specified defconfigs
976 are applied if present, and where configuration modes such as
977 <filename>--allnoconfig</filename> are applied.
978 </para>
979 </section>
980
981 <section id='ref-tasks-kernel_menuconfig'>
982 <title><filename>do_kernel_menuconfig</filename></title>
983
984 <para>
985 Invoked by the user to manipulate the
986 <filename>.config</filename> file used to build a linux-yocto
987 recipe.
988 This task starts the Linux kernel configuration tool, which you
989 then use to modify the kernel configuration.
990 <note>
991 You can also invoke this tool from the command line as
992 follows:
993 <literallayout class='monospaced'>
994 $ bitbake linux-yocto -c menuconfig
995 </literallayout>
996 </note>
997 See the
998 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
999 section in the Yocto Project Linux Kernel Development Manual
1000 for more information on this configuration tool.
1001 </para>
1002 </section>
1003
1004 <section id='ref-tasks-kernel_metadata'>
1005 <title><filename>do_kernel_metadata</filename></title>
1006
1007 <para>
1008 Collects all the features required for a given kernel build,
1009 whether the features come from
1010 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
1011 or from Git repositories.
1012 After collection, the <filename>do_kernel_metadata</filename> task
1013 processes the features into a series of config fragments and
1014 patches, which can then be applied by subsequent tasks such as
1015 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
1016 and
1017 <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>.
1018 </para>
1019 </section>
1020
1021 <section id='ref-tasks-menuconfig'>
1022 <title><filename>do_menuconfig</filename></title>
1023
1024 <para>
1025 Runs <filename>make menuconfig</filename> for the kernel.
1026 For information on <filename>menuconfig</filename>, see the
1027 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig'>Using&nbsp;&nbsp;<filename>menuconfig</filename></ulink>"
1028 section in the Yocto Project Linux Kernel Development Manual.
1029 </para>
1030 </section>
1031
1032 <section id='ref-tasks-savedefconfig'>
1033 <title><filename>do_savedefconfig</filename></title>
1034
1035 <para>
1036 When invoked by the user, creates a defconfig file that can be
1037 used instead of the default defconfig.
1038 The saved defconfig contains the differences between the default
1039 defconfig and the changes made by the user using other methods
1040 (i.e. the
1041 <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>
1042 task.
1043 You can invoke the task using the following command:
1044 <literallayout class='monospaced'>
1045 $ bitbake linux-yocto -c savedefconfig
1046 </literallayout>
1047 </para>
1048 </section>
1049
1050 <section id='ref-tasks-shared_workdir'>
1051 <title><filename>do_shared_workdir</filename></title>
1052
1053 <para>
1054 After the kernel has been compiled but before the kernel modules
1055 have been compiled, this task copies files required for module
1056 builds and which are generated from the kernel build into the
1057 shared work directory.
1058 With these copies successfully copied, the
1059 <link linkend='ref-tasks-compile_kernelmodules'><filename>do_compile_kernelmodules</filename></link>
1060 task can successfully build the kernel modules in the next step
1061 of the build.
1062 </para>
1063 </section>
1064
1065 <section id='ref-tasks-sizecheck'>
1066 <title><filename>do_sizecheck</filename></title>
1067
1068 <para>
1069 After the kernel has been built, this task checks the size of the
1070 stripped kernel image against
1071 <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link>.
1072 If that variable was set and the size of the stripped kernel
1073 exceeds that size, the kernel build produces a warning to that
1074 effect.
1075 </para>
1076 </section>
1077
1078 <section id='ref-tasks-strip'>
1079 <title><filename>do_strip</filename></title>
1080
1081 <para>
1082 If
1083 <filename>KERNEL_IMAGE_STRIP_EXTRA_SECTIONS</filename> is defined,
1084 this task strips the sections named in that variable from
1085 <filename>vmlinux</filename>.
1086 This stripping is typically used to remove nonessential sections
1087 such as <filename>.comment</filename> sections from a
1088 size-sensitive configuration.
1089 </para>
1090 </section>
1091
1092 <section id='ref-tasks-validate_branches'>
1093 <title><filename>do_validate_branches</filename></title>
1094
1095 <para>
1096 After the kernel is unpacked but before it is patched, this task
1097 makes sure that the machine and metadata branches as specified
1098 by the <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
1099 variables actually exist on the specified branches.
1100 If these branches do not exist and
1101 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
1102 is not being used, the <filename>do_validate_branches</filename>
1103 task fails during the build.
1104 </para>
1105 </section>
1106</section>
1107
1108<section id='miscellaneous-tasks'>
1109 <title>Miscellaneous Tasks</title>
1110
1111 <para>
1112 The following sections describe miscellaneous tasks.
1113 </para>
1114
1115 <section id='ref-tasks-spdx'>
1116 <title><filename>do_spdx</filename></title>
1117
1118 <para>
1119 A build stage that takes the source code and scans it on a remote
1120 FOSSOLOGY server in order to produce an SPDX document.
1121 This task applies only to the
1122 <link linkend='ref-classes-spdx'><filename>spdx</filename></link>
1123 class.
1124 </para>
1125 </section>
1126</section>
1127
1128</chapter>
1129<!--
1130vim: expandtab tw=80 ts=4
1131-->
diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml
deleted file mode 100644
index 2a0452bd78..0000000000
--- a/documentation/ref-manual/ref-terms.xml
+++ /dev/null
@@ -1,525 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-terms'>
7<title>Yocto Project Terms</title>
8
9 <para>
10 Following is a list of terms and definitions users new to the Yocto
11 Project development environment might find helpful.
12 While some of these terms are universal, the list includes them
13 just in case:
14 <itemizedlist>
15 <listitem><para>
16 <emphasis>Append Files:</emphasis>
17 Files that append build information to a recipe file.
18 Append files are known as BitBake append files and
19 <filename>.bbappend</filename> files.
20 The OpenEmbedded build system expects every append file to have
21 a corresponding recipe (<filename>.bb</filename>) file.
22 Furthermore, the append file and corresponding recipe file
23 must use the same root filename.
24 The filenames can differ only in the file type suffix used
25 (e.g.
26 <filename>formfactor_0.0.bb</filename> and
27 <filename>formfactor_0.0.bbappend</filename>).</para>
28
29 <para>Information in append files extends or overrides the
30 information in the similarly-named recipe file.
31 For an example of an append file in use, see the
32 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>"
33 section in the Yocto Project Development Tasks Manual.</para>
34
35 <para>When you name an append file, you can use the
36 "<filename>%</filename>" wildcard character to allow for
37 matching recipe names.
38 For example, suppose you have an append file named as follows:
39 <literallayout class='monospaced'>
40 busybox_1.21.%.bbappend
41 </literallayout>
42 That append file would match any
43 <filename>busybox_1.21.</filename><replaceable>x</replaceable><filename>.bb</filename>
44 version of the recipe.
45 So, the append file would match any of the following recipe names:
46 <literallayout class='monospaced'>
47 busybox_1.21.1.bb
48 busybox_1.21.2.bb
49 busybox_1.21.3.bb
50 busybox_1.21.10.bb
51 busybox_1.21.25.bb
52 </literallayout>
53 <note><title>Important</title>
54 The use of the "<filename>%</filename>" character
55 is limited in that it only works directly in front of the
56 <filename>.bbappend</filename> portion of the append file's
57 name.
58 You cannot use the wildcard character in any other
59 location of the name.
60 </note>
61 </para></listitem>
62 <listitem><para id='bitbake-term'>
63 <emphasis>BitBake:</emphasis>
64 The task executor and scheduler used by the OpenEmbedded build
65 system to build images.
66 For more information on BitBake, see the
67 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
68 </para></listitem>
69 <listitem><para id='board-support-package-bsp-term'>
70 <emphasis>Board Support Package (BSP):</emphasis>
71 A group of drivers, definitions, and other components that
72 provide support for a specific hardware configuration.
73 For more information on BSPs, see the
74 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
75 </para></listitem>
76 <listitem>
77 <para id='build-directory'>
78 <emphasis>Build Directory:</emphasis>
79 This term refers to the area used by the OpenEmbedded build
80 system for builds.
81 The area is created when you <filename>source</filename> the
82 setup environment script that is found in the Source Directory
83 (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>).
84 The
85 <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link>
86 variable points to the Build Directory.</para>
87
88 <para>You have a lot of flexibility when creating the Build
89 Directory.
90 Following are some examples that show how to create the
91 directory.
92 The examples assume your
93 <link linkend='source-directory'>Source Directory</link> is
94 named <filename>poky</filename>:
95 <itemizedlist>
96 <listitem><para>Create the Build Directory inside your
97 Source Directory and let the name of the Build
98 Directory default to <filename>build</filename>:
99 <literallayout class='monospaced'>
100 $ cd $HOME/poky
101 $ source &OE_INIT_FILE;
102 </literallayout>
103 </para></listitem>
104 <listitem><para>Create the Build Directory inside your
105 home directory and specifically name it
106 <filename>test-builds</filename>:
107 <literallayout class='monospaced'>
108 $ cd $HOME
109 $ source poky/&OE_INIT_FILE; test-builds
110 </literallayout>
111 </para></listitem>
112 <listitem><para>
113 Provide a directory path and specifically name the
114 Build Directory.
115 Any intermediate folders in the pathname must exist.
116 This next example creates a Build Directory named
117 <filename>YP-&POKYVERSION;</filename>
118 in your home directory within the existing
119 directory <filename>mybuilds</filename>:
120 <literallayout class='monospaced'>
121 $ cd $HOME
122 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
123 </literallayout>
124 </para></listitem>
125 </itemizedlist>
126 <note>
127 By default, the Build Directory contains
128 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
129 which is a temporary directory the build system uses for
130 its work.
131 <filename>TMPDIR</filename> cannot be under NFS.
132 Thus, by default, the Build Directory cannot be under NFS.
133 However, if you need the Build Directory to be under NFS,
134 you can set this up by setting <filename>TMPDIR</filename>
135 in your <filename>local.conf</filename> file
136 to use a local drive.
137 Doing so effectively separates <filename>TMPDIR</filename>
138 from <filename>TOPDIR</filename>, which is the Build
139 Directory.
140 </note>
141 </para></listitem>
142 <listitem><para id='hardware-build-system-term'>
143 <emphasis>Build Host:</emphasis>
144 The system used to build images in a Yocto Project
145 Development environment.
146 The build system is sometimes referred to as the
147 <firstterm>development host</firstterm>.
148 </para></listitem>
149 <listitem><para>
150 <emphasis>Classes:</emphasis>
151 Files that provide for logic encapsulation and inheritance so
152 that commonly used patterns can be defined once and then
153 easily used in multiple recipes.
154 For reference information on the Yocto Project classes, see the
155 "<link linkend='ref-classes'>Classes</link>" chapter.
156 Class files end with the <filename>.bbclass</filename>
157 filename extension.
158 </para></listitem>
159 <listitem><para>
160 <emphasis>Configuration File:</emphasis>
161 Files that hold global definitions of variables,
162 user-defined variables, and hardware configuration
163 information.
164 These files tell the OpenEmbedded build system what to
165 build and what to put into the image to support a
166 particular platform.</para>
167
168 <para>Configuration files end with a <filename>.conf</filename>
169 filename extension.
170 The <filename>conf/local.conf</filename> configuration file in
171 the
172 <link linkend='build-directory'>Build Directory</link>
173 contains user-defined variables that affect every build.
174 The <filename>meta-poky/conf/distro/poky.conf</filename>
175 configuration file defines Yocto "distro" configuration
176 variables used only when building with this policy.
177 Machine configuration files, which
178 are located throughout the
179 <link linkend='source-directory'>Source Directory</link>, define
180 variables for specific hardware and are only used when building
181 for that target (e.g. the
182 <filename>machine/beaglebone.conf</filename> configuration
183 file defines variables for the Texas Instruments ARM Cortex-A8
184 development board).
185 </para></listitem>
186 <listitem><para id='term-container-layer'>
187 <emphasis>Container Layer:</emphasis>
188 Layers that hold other layers.
189 An example of a container layer is OpenEmbedded's
190 <ulink url='https://github.com/openembedded/meta-openembedded'><filename>meta-openembedded</filename></ulink>
191 layer.
192 The <filename>meta-openembedded</filename> layer contains
193 many <filename>meta-*</filename> layers.
194 </para></listitem>
195 <listitem><para id='cross-development-toolchain'>
196 <emphasis>Cross-Development Toolchain:</emphasis>
197 In general, a cross-development toolchain is a collection of
198 software development tools and utilities that run on one
199 architecture and allow you to develop software for a
200 different, or targeted, architecture.
201 These toolchains contain cross-compilers, linkers, and
202 debuggers that are specific to the target architecture.</para>
203
204 <para>The Yocto Project supports two different cross-development
205 toolchains:
206 <itemizedlist>
207 <listitem><para>
208 A toolchain only used by and within
209 BitBake when building an image for a target
210 architecture.
211 </para></listitem>
212 <listitem><para>A relocatable toolchain used outside of
213 BitBake by developers when developing applications
214 that will run on a targeted device.
215 </para></listitem>
216 </itemizedlist></para>
217
218 <para>Creation of these toolchains is simple and automated.
219 For information on toolchain concepts as they apply to the
220 Yocto Project, see the
221 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
222 section in the Yocto Project Overview and Concepts Manual.
223 You can also find more information on using the
224 relocatable toolchain in the
225 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
226 manual.
227 </para></listitem>
228 <listitem><para>
229 <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
230 A custom SDK for application developers.
231 This eSDK allows developers to incorporate their library
232 and programming changes back into the image to make
233 their code available to other application developers.</para>
234
235 <para>For information on the eSDK, see the
236 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
237 manual.
238 </para></listitem>
239 <listitem><para>
240 <emphasis>Image:</emphasis>
241 An image is an artifact of the BitBake build process given
242 a collection of recipes and related Metadata.
243 Images are the binary output that run on specific hardware or
244 QEMU and are used for specific use-cases.
245 For a list of the supported image types that the Yocto Project
246 provides, see the
247 "<link linkend='ref-images'>Images</link>"
248 chapter.
249 </para></listitem>
250 <listitem><para>
251 <emphasis>Layer:</emphasis>
252 A collection of related recipes.
253 Layers allow you to consolidate related metadata to
254 customize your build.
255 Layers also isolate information used when building
256 for multiple architectures.
257 Layers are hierarchical in their ability to override
258 previous specifications.
259 You can include any number of available layers from the
260 Yocto Project and customize the build by adding your
261 layers after them.
262 You can search the Layer Index for layers used within
263 Yocto Project.</para>
264
265 <para>For introductory information on layers, see the
266 "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
267 section in the Yocto Project Overview and Concepts Manual.
268 For more detailed information on layers, see the
269 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
270 section in the Yocto Project Development Tasks Manual.
271 For a discussion specifically on BSP Layers, see the
272 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
273 section in the Yocto Project Board Support Packages (BSP)
274 Developer's Guide.
275 </para></listitem>
276 <listitem><para id='metadata'>
277 <emphasis>Metadata:</emphasis>
278 A key element of the Yocto Project is the Metadata that
279 is used to construct a Linux distribution and is contained
280 in the files that the
281 <link linkend='build-system-term'>OpenEmbedded build system</link>
282 parses when building an image.
283 In general, Metadata includes recipes, configuration
284 files, and other information that refers to the build
285 instructions themselves, as well as the data used to
286 control what things get built and the effects of the
287 build.
288 Metadata also includes commands and data used to
289 indicate what versions of software are used, from
290 where they are obtained, and changes or additions to the
291 software itself (patches or auxiliary files) that
292 are used to fix bugs or customize the software for use
293 in a particular situation.
294 OpenEmbedded-Core is an important set of validated
295 metadata.</para>
296
297 <para>In the context of the kernel ("kernel Metadata"), the
298 term refers to the kernel config fragments and features
299 contained in the
300 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink>
301 Git repository.
302 </para></listitem>
303 <listitem><para id='oe-core'>
304 <emphasis>OpenEmbedded-Core (OE-Core):</emphasis>
305 OE-Core is metadata comprised of foundational recipes,
306 classes, and associated files that are meant to be
307 common among many different OpenEmbedded-derived systems,
308 including the Yocto Project.
309 OE-Core is a curated subset of an original repository
310 developed by the OpenEmbedded community that has been
311 pared down into a smaller, core set of continuously
312 validated recipes.
313 The result is a tightly controlled and an quality-assured
314 core set of recipes.</para>
315
316 <para>You can see the Metadata in the
317 <filename>meta</filename> directory of the Yocto Project
318 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>.
319 </para></listitem>
320 <listitem><para id='build-system-term'>
321 <emphasis>OpenEmbedded Build System:</emphasis>
322 The build system specific to the Yocto Project.
323 The OpenEmbedded build system is based on another project known
324 as "Poky", which uses
325 <link linkend='bitbake-term'>BitBake</link> as the task
326 executor.
327 Throughout the Yocto Project documentation set, the
328 OpenEmbedded build system is sometimes referred to simply
329 as "the build system".
330 If other build systems, such as a host or target build system
331 are referenced, the documentation clearly states the
332 difference.
333 <note>
334 For some historical information about Poky, see the
335 <link linkend='poky'>Poky</link> term.
336 </note>
337 </para></listitem>
338 <listitem><para>
339 <emphasis>Package:</emphasis>
340 In the context of the Yocto Project, this term refers to a
341 recipe's packaged output produced by BitBake (i.e. a
342 "baked recipe").
343 A package is generally the compiled binaries produced from the
344 recipe's sources.
345 You "bake" something by running it through BitBake.</para>
346
347 <para>It is worth noting that the term "package" can,
348 in general, have subtle meanings.
349 For example, the packages referred to in the
350 "<link linkend='required-packages-for-the-build-host'>Required Packages for the Build Host</link>"
351 section are compiled binaries that, when installed, add
352 functionality to your Linux distribution.</para>
353
354 <para>Another point worth noting is that historically within
355 the Yocto Project, recipes were referred to as packages - thus,
356 the existence of several BitBake variables that are seemingly
357 mis-named,
358 (e.g. <link linkend='var-PR'><filename>PR</filename></link>,
359 <link linkend='var-PV'><filename>PV</filename></link>, and
360 <link linkend='var-PE'><filename>PE</filename></link>).
361 </para></listitem>
362 <listitem><para>
363 <emphasis>Package Groups:</emphasis>
364 Arbitrary groups of software Recipes.
365 You use package groups to hold recipes that, when built,
366 usually accomplish a single task.
367 For example, a package group could contain the recipes for a
368 company's proprietary or value-add software.
369 Or, the package group could contain the recipes that enable
370 graphics.
371 A package group is really just another recipe.
372 Because package group files are recipes, they end with the
373 <filename>.bb</filename> filename extension.
374 </para></listitem>
375 <listitem><para id='poky'>
376 <emphasis>Poky:</emphasis>
377 Poky, which is pronounced <emphasis>Pock</emphasis>-ee,
378 is a reference embedded distribution and a reference
379 test configuration.
380 Poky provides the following:
381 <itemizedlist>
382 <listitem><para>
383 A base-level functional distro used to illustrate
384 how to customize a distribution.
385 </para></listitem>
386 <listitem><para>
387 A means by which to test the Yocto Project
388 components (i.e. Poky is used to validate
389 the Yocto Project).
390 </para></listitem>
391 <listitem><para>
392 A vehicle through which you can download
393 the Yocto Project.
394 </para></listitem>
395 </itemizedlist>
396 Poky is not a product level distro.
397 Rather, it is a good starting point for customization.
398 <note>
399 Poky began as an open-source
400 project initially developed by OpenedHand.
401 OpenedHand developed Poky from the existing
402 OpenEmbedded build system to create a commercially
403 supportable build system for embedded Linux.
404 After Intel Corporation acquired OpenedHand, the
405 poky project became the basis for the Yocto Project's
406 build system.
407 </note>
408 </para></listitem>
409 <listitem><para>
410 <emphasis>Recipe:</emphasis>
411 A set of instructions for building packages.
412 A recipe describes where you get source code, which patches
413 to apply, how to configure the source, how to compile it and so on.
414 Recipes also describe dependencies for libraries or for other
415 recipes.
416 Recipes represent the logical unit of execution, the software
417 to build, the images to build, and use the
418 <filename>.bb</filename> file extension.
419 </para></listitem>
420 <listitem><para id='reference-kit-term'>
421 <emphasis>Reference Kit:</emphasis>
422 A working example of a system, which includes a
423 <link linkend='board-support-package-bsp-term'>BSP</link>
424 as well as a
425 <link linkend='hardware-build-system-term'>build host</link>
426 and other components, that can work on specific hardware.
427 </para></listitem>
428 <listitem>
429 <para id='source-directory'>
430 <emphasis>Source Directory:</emphasis>
431 This term refers to the directory structure created as a result
432 of creating a local copy of the <filename>poky</filename> Git
433 repository <filename>git://git.yoctoproject.org/poky</filename>
434 or expanding a released <filename>poky</filename> tarball.
435 <note>
436 Creating a local copy of the <filename>poky</filename>
437 Git repository is the recommended method for setting up
438 your Source Directory.
439 </note>
440 Sometimes you might hear the term "poky directory" used to refer
441 to this directory structure.
442 <note>
443 The OpenEmbedded build system does not support file or
444 directory names that contain spaces.
445 Be sure that the Source Directory you use does not contain
446 these types of names.
447 </note></para>
448
449 <para>The Source Directory contains BitBake, Documentation,
450 Metadata and other files that all support the Yocto Project.
451 Consequently, you must have the Source Directory in place on
452 your development system in order to do any development using
453 the Yocto Project.</para>
454
455 <para>When you create a local copy of the Git repository, you
456 can name the repository anything you like.
457 Throughout much of the documentation, "poky"
458 is used as the name of the top-level folder of the local copy of
459 the poky Git repository.
460 So, for example, cloning the <filename>poky</filename> Git
461 repository results in a local Git repository whose top-level
462 folder is also named "poky".</para>
463
464 <para>While it is not recommended that you use tarball expansion
465 to set up the Source Directory, if you do, the top-level
466 directory name of the Source Directory is derived from the
467 Yocto Project release tarball.
468 For example, downloading and unpacking
469 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
470 Source Directory whose root folder is named
471 <filename>&YOCTO_POKY;</filename>.</para>
472
473 <para>It is important to understand the differences between the
474 Source Directory created by unpacking a released tarball as
475 compared to cloning
476 <filename>git://git.yoctoproject.org/poky</filename>.
477 When you unpack a tarball, you have an exact copy of the files
478 based on the time of release - a fixed release point.
479 Any changes you make to your local files in the Source Directory
480 are on top of the release and will remain local only.
481 On the other hand, when you clone the <filename>poky</filename>
482 Git repository, you have an active development repository with
483 access to the upstream repository's branches and tags.
484 In this case, any local changes you make to the local
485 Source Directory can be later applied to active development
486 branches of the upstream <filename>poky</filename> Git
487 repository.</para>
488
489 <para>For more information on concepts related to Git
490 repositories, branches, and tags, see the
491 "<ulink url='&YOCTO_DOCS_OM_URL;#repositories-tags-and-branches'>Repositories, Tags, and Branches</ulink>"
492 section in the Yocto Project Overview and Concepts Manual.
493 </para></listitem>
494 <listitem><para><emphasis>Task:</emphasis>
495 A unit of execution for BitBake (e.g.
496 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
497 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>,
498 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>,
499 and so forth).
500 </para></listitem>
501 <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis>
502 A web interface to the Yocto Project's
503 <link linkend='build-system-term'>OpenEmbedded Build System</link>.
504 The interface enables you to configure and run your builds.
505 Information about builds is collected and stored in a database.
506 For information on Toaster, see the
507 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
508 </para></listitem>
509 <listitem><para>
510 <emphasis>Upstream:</emphasis>
511 A reference to source code or repositories
512 that are not local to the development system but located in a
513 master area that is controlled by the maintainer of the source
514 code.
515 For example, in order for a developer to work on a particular
516 piece of code, they need to first get a copy of it from an
517 "upstream" source.
518 </para></listitem>
519 </itemizedlist>
520 </para>
521
522</chapter>
523<!--
524vim: expandtab tw=80 ts=4
525-->
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
deleted file mode 100644
index a5064807e5..0000000000
--- a/documentation/ref-manual/ref-variables.xml
+++ /dev/null
@@ -1,16877 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<!-- Dummy chapter -->
7<chapter id='ref-variables-glos'>
8
9<title>Variables Glossary</title>
10
11<para>
12 This chapter lists common variables used in the OpenEmbedded build system and gives an overview
13 of their function and contents.
14</para>
15
16<glossary id='ref-variables-glossary'>
17
18
19 <para>
20 <link linkend='var-ABIEXTENSION'>A</link>
21 <link linkend='var-B'>B</link>
22 <link linkend='var-CACHE'>C</link>
23 <link linkend='var-D'>D</link>
24 <link linkend='var-EFI_PROVIDER'>E</link>
25 <link linkend='var-FEATURE_PACKAGES'>F</link>
26 <link linkend='var-GCCPIE'>G</link>
27 <link linkend='var-HOMEPAGE'>H</link>
28 <link linkend='var-ICECC_DISABLED'>I</link>
29<!-- <link linkend='var-glossary-j'>J</link> -->
30 <link linkend='var-KARCH'>K</link>
31 <link linkend='var-LABELS'>L</link>
32 <link linkend='var-MACHINE'>M</link>
33 <link linkend='var-NATIVELSBSTRING'>N</link>
34 <link linkend='var-OBJCOPY'>O</link>
35 <link linkend='var-P'>P</link>
36<!-- <link linkend='var-glossary-q'>Q</link> -->
37 <link linkend='var-RANLIB'>R</link>
38 <link linkend='var-S'>S</link>
39 <link linkend='var-T'>T</link>
40 <link linkend='var-UBOOT_CONFIG'>U</link>
41 <link linkend='var-VOLATILE_LOG_DIR'>V</link>
42 <link linkend='var-WARN_QA'>W</link>
43 <link linkend='var-XSERVER'>X</link>
44<!-- <link linkend='var-glossary-y'>Y</link> -->
45<!-- <link linkend='var-glossary-z'>Z</link>-->
46 </para>
47
48 <glossdiv id='var-glossary-a'><title>A</title>
49
50 <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm>
51 <info>
52 ABIEXTENSION[doc] = "Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi")."
53 </info>
54 <glossdef>
55 <para role="glossdeffirst">
56 Extension to the Application Binary Interface (ABI)
57 field of the GNU canonical architecture name
58 (e.g. "eabi").
59 </para>
60
61 <para>
62 ABI extensions are set in the machine include files.
63 For example, the
64 <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>
65 file sets the following extension:
66 <literallayout class='monospaced'>
67 ABIEXTENSION = "eabi"
68 </literallayout>
69 </para>
70 </glossdef>
71 </glossentry>
72
73 <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
74 <info>
75 ALLOW_EMPTY[doc] = "Specifies whether to produce an output package even if it is empty."
76 </info>
77 <glossdef>
78 <para role="glossdeffirst">
79 Specifies whether to produce an output package even if it is
80 empty.
81 By default, BitBake does not produce empty packages.
82 This default behavior can cause issues when there is an
83 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
84 some other hard runtime requirement on the existence of the package.
85 </para>
86
87 <para>
88 Like all package-controlling variables, you must always use them in
89 conjunction with a package name override, as in:
90 <literallayout class='monospaced'>
91 ALLOW_EMPTY_${PN} = "1"
92 ALLOW_EMPTY_${PN}-dev = "1"
93 ALLOW_EMPTY_${PN}-staticdev = "1"
94 </literallayout>
95 </para>
96 </glossdef>
97 </glossentry>
98
99 <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
100 <info>
101 ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme."
102 </info>
103 <glossdef>
104 <para role="glossdeffirst">
105 Lists commands in a package that need an alternative
106 binary naming scheme.
107 Sometimes the same command is provided in multiple packages.
108 When this occurs, the OpenEmbedded build system needs to
109 use the alternatives system to create a different binary
110 naming scheme so the commands can co-exist.
111 </para>
112
113 <para>
114 To use the variable, list out the package's commands
115 that also exist as part of another package.
116 For example, if the <filename>busybox</filename> package
117 has four commands that also exist as part of another
118 package, you identify them as follows:
119 <literallayout class='monospaced'>
120 ALTERNATIVE_busybox = "sh sed test bracket"
121 </literallayout>
122 For more information on the alternatives system, see the
123 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
124 section.
125 </para>
126 </glossdef>
127 </glossentry>
128
129 <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
130 <info>
131 ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations."
132 </info>
133 <glossdef>
134 <para role="glossdeffirst">
135 Used by the alternatives system to map duplicated commands
136 to actual locations.
137 For example, if the <filename>bracket</filename> command
138 provided by the <filename>busybox</filename> package is
139 duplicated through another package, you must use the
140 <filename>ALTERNATIVE_LINK_NAME</filename> variable to
141 specify the actual location:
142 <literallayout class='monospaced'>
143 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
144 </literallayout>
145 </para>
146
147 <para>
148 In this example, the binary for the
149 <filename>bracket</filename> command (i.e.
150 <filename>[</filename>) from the
151 <filename>busybox</filename> package resides in
152 <filename>/usr/bin/</filename>.
153 <note>
154 If <filename>ALTERNATIVE_LINK_NAME</filename> is not
155 defined, it defaults to
156 <filename>${bindir}/<replaceable>name</replaceable></filename>.
157 </note>
158 </para>
159
160 <para>
161 For more information on the alternatives system, see the
162 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
163 section.
164 </para>
165 </glossdef>
166 </glossentry>
167
168 <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
169 <info>
170 ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands."
171 </info>
172 <glossdef>
173 <para role="glossdeffirst">
174 Used by the alternatives system to create default
175 priorities for duplicated commands.
176 You can use the variable to create a single default
177 regardless of the command name or package, a default for
178 specific duplicated commands regardless of the package, or
179 a default for specific commands tied to particular packages.
180 Here are the available syntax forms:
181 <literallayout class='monospaced'>
182 ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>"
183 ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
184 ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>"
185 </literallayout>
186 </para>
187
188 <para>
189 For more information on the alternatives system, see the
190 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
191 section.
192 </para>
193 </glossdef>
194 </glossentry>
195
196 <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
197 <info>
198 ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands."
199 </info>
200 <glossdef>
201 <para role="glossdeffirst">
202 Used by the alternatives system to create default link
203 locations for duplicated commands.
204 You can use the variable to create a single default
205 location for all duplicated commands regardless of the
206 command name or package, a default for
207 specific duplicated commands regardless of the package, or
208 a default for specific commands tied to particular packages.
209 Here are the available syntax forms:
210 <literallayout class='monospaced'>
211 ALTERNATIVE_TARGET = "<replaceable>target</replaceable>"
212 ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
213 ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>"
214 </literallayout>
215 <note>
216 <para>
217 If <filename>ALTERNATIVE_TARGET</filename> is not
218 defined, it inherits the value from the
219 <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
220 variable.
221 </para>
222
223 <para>
224 If <filename>ALTERNATIVE_LINK_NAME</filename> and
225 <filename>ALTERNATIVE_TARGET</filename> are the
226 same, the target for
227 <filename>ALTERNATIVE_TARGET</filename>
228 has "<filename>.{BPN}</filename>" appended to it.
229 </para>
230
231 <para>
232 Finally, if the file referenced has not been
233 renamed, the alternatives system will rename it to
234 avoid the need to rename alternative files in the
235 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
236 task while
237 retaining support for the command if necessary.
238 </para>
239 </note>
240 </para>
241
242 <para>
243 For more information on the alternatives system, see the
244 "<link linkend='ref-classes-update-alternatives'><filename>update-alternatives.bbclass</filename></link>"
245 section.
246 </para>
247 </glossdef>
248 </glossentry>
249
250 <glossentry id='var-APPEND'><glossterm>APPEND</glossterm>
251 <info>
252 APPEND[doc] = "An override list of append strings for target specified using LABELS."
253 </info>
254 <glossdef>
255 <para role="glossdeffirst">
256 An override list of append strings for each target
257 specified with
258 <link linkend='var-LABELS'><filename>LABELS</filename></link>.
259 </para>
260
261 <para>
262 See the
263 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
264 class for more information on how this variable is used.
265 </para>
266 </glossdef>
267 </glossentry>
268
269 <glossentry id='var-AR'><glossterm>AR</glossterm>
270 <info>
271 AR[doc] = "Minimal command and arguments to run 'ar'."
272 </info>
273 <glossdef>
274 <para role="glossdeffirst">
275 The minimal command and arguments used to run
276 <filename>ar</filename>.
277 </para>
278 </glossdef>
279 </glossentry>
280
281 <glossentry id='var-ARCHIVER_MODE'><glossterm>ARCHIVER_MODE</glossterm>
282 <info>
283 ARCHIVER_MODE[doc] = "Controls archive creation used when releasing source files."
284 </info>
285 <glossdef>
286 <para role="glossdeffirst">
287 When used with the
288 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
289 class, determines the type of information used to create
290 a released archive.
291 You can use this variable to create archives of patched
292 source, original source, configured source, and so forth
293 by employing the following variable flags (varflags):
294 <literallayout class='monospaced'>
295 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source
296 # files.
297
298 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is
299 # the default.
300
301 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
302
303 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and
304 # do_patch.
305
306 ARCHIVER_MODE[diff-exclude] ?= "<replaceable>file</replaceable> <replaceable>file</replaceable> ..." # Lists files and directories to
307 # exclude from diff.
308
309 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
310
311 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
312
313 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
314 </literallayout>
315 For information on how the variable works, see the
316 <filename>meta/classes/archiver.bbclass</filename> file
317 in the
318 <link linkend='source-directory'>Source Directory</link>.
319 </para>
320 </glossdef>
321 </glossentry>
322
323 <glossentry id='var-AS'><glossterm>AS</glossterm>
324 <info>
325 AS[doc] = "Minimal command and arguments to run the assembler."
326 </info>
327 <glossdef>
328 <para role="glossdeffirst">
329 Minimal command and arguments needed to run the
330 assembler.
331 </para>
332 </glossdef>
333 </glossentry>
334
335 <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm>
336 <info>
337 ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build."
338 </info>
339 <glossdef>
340 <para role="glossdeffirst">
341 Lists recipe names
342 (<link linkend='var-PN'><filename>PN</filename></link>
343 values) BitBake does not attempt to build.
344 Instead, BitBake assumes these recipes have already been
345 built.
346 </para>
347
348 <para>
349 In OpenEmbedded-Core, <filename>ASSUME_PROVIDED</filename>
350 mostly specifies native tools that should not be built.
351 An example is <filename>git-native</filename>, which when
352 specified, allows for the Git binary from the host to be
353 used rather than building <filename>git-native</filename>.
354 </para>
355 </glossdef>
356 </glossentry>
357
358 <glossentry id='var-ASSUME_SHLIBS'><glossterm>ASSUME_SHLIBS</glossterm>
359 <info>
360 ASSUME_SHLIBS[doc] = "Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system."
361 </info>
362 <glossdef>
363 <para role="glossdeffirst">
364 Provides additional <filename>shlibs</filename> provider
365 mapping information, which adds to or overwrites the
366 information provided automatically by the system.
367 Separate multiple entries using spaces.
368 </para>
369
370 <para>
371 As an example, use the following form to add an
372 <filename>shlib</filename> provider of
373 <replaceable>shlibname</replaceable> in
374 <replaceable>packagename</replaceable> with the optional
375 <replaceable>version</replaceable>:
376 <literallayout class='monospaced'>
377 <replaceable>shlibname:packagename</replaceable>[_<replaceable>version</replaceable>]
378 </literallayout>
379 </para>
380
381 <para>
382 Here is an example that adds a shared library named
383 <filename>libEGL.so.1</filename> as being provided by
384 the <filename>libegl-implementation</filename> package:
385 <literallayout class='monospaced'>
386 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
387 </literallayout>
388 </para>
389 </glossdef>
390 </glossentry>
391
392 <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
393 <info>
394 AUTHOR[doc] = "Email address used to contact the original author or authors in order to send patches and forward bugs."
395 </info>
396 <glossdef>
397 <para role="glossdeffirst">
398 The email address used to contact the original author
399 or authors in order to send patches and forward bugs.
400 </para>
401 </glossdef>
402 </glossentry>
403
404 <glossentry id='var-AUTO_LIBNAME_PKGS'><glossterm>AUTO_LIBNAME_PKGS</glossterm>
405 <info>
406 AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming."
407 </info>
408 <glossdef>
409 <para role="glossdeffirst">
410 When the
411 <link linkend='ref-classes-debian'><filename>debian</filename></link>
412 class is inherited, which is the default behavior,
413 <filename>AUTO_LIBNAME_PKGS</filename> specifies which
414 packages should be checked for libraries and renamed
415 according to Debian library package naming.
416 </para>
417
418 <para>
419 The default value is "${PACKAGES}", which causes the
420 debian class to act on all packages that are
421 explicitly generated by the recipe.
422 </para>
423 </glossdef>
424 </glossentry>
425
426 <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm>
427 <info>
428 AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader."
429 </info>
430 <glossdef>
431 <para role="glossdeffirst">
432 Enables creating an automatic menu for the syslinux
433 bootloader.
434 You must set this variable in your recipe.
435 The
436 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
437 class checks this variable.
438 </para>
439 </glossdef>
440 </glossentry>
441
442 <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
443 <info>
444 AUTOREV[doc] = "When SRCREV is set to the value of this variable, it specifies to use the latest source revision in the repository."
445 </info>
446 <glossdef>
447 <para role="glossdeffirst">
448 When
449 <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
450 is set to the value of this variable, it specifies to use
451 the latest source revision in the repository.
452 Here is an example:
453 <literallayout class='monospaced'>
454 SRCREV = "${AUTOREV}"
455 </literallayout>
456 </para>
457
458 <para>
459 If you use the previous statement to retrieve the latest
460 version of software, you need to be sure
461 <link linkend='var-PV'><filename>PV</filename></link>
462 contains
463 <filename>${</filename><link linkend='var-SRCPV'><filename>SRCPV</filename></link><filename>}</filename>.
464 For example, suppose you have a kernel recipe that
465 inherits the
466 <link linkend='ref-classes-kernel'>kernel</link> class
467 and you use the previous statement.
468 In this example, <filename>${SRCPV}</filename> does not
469 automatically get into <filename>PV</filename>.
470 Consequently, you need to change <filename>PV</filename>
471 in your recipe so that it does contain
472 <filename>${SRCPV}</filename>.
473 </para>
474
475 <para>
476 For more information see the
477 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
478 section in the Yocto Project Development Tasks Manual.
479 </para>
480 </glossdef>
481 </glossentry>
482
483 <glossentry id='var-AVAILABLE_LICENSES'><glossterm>AVAILABLE_LICENSES</glossterm>
484 <info>
485 AVAILABLE_LICENSES[doc] = "List of licenses found in the directories specified by COMMON_LICENSE_DIR and LICENSE_PATH."
486 </info>
487 <glossdef>
488 <para role="glossdeffirst">
489
490 List of licenses found in the directories specified
491 by <link linkend='var-COMMON_LICENSE_DIR'><filename>COMMON_LICENSE_DIR</filename></link>
492 and <link linkend='var-LICENSE_PATH'><filename>LICENSE_PATH</filename></link>.
493
494 <note>
495 It is assumed that all changes
496 to <filename>COMMON_LICENSE_DIR</filename>
497 and <filename>LICENSE_PATH</filename> have been done
498 before <filename>AVAILABLE_LICENSES</filename> is
499 defined
500 (in <link linkend='ref-classes-license'>license.bbclass</link>).
501 </note>
502 </para>
503 </glossdef>
504 </glossentry>
505
506 <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm>
507 <info>
508 AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system."
509 </info>
510 <glossdef>
511 <para role="glossdeffirst">
512 The list of defined CPU and Application Binary Interface
513 (ABI) tunings (i.e. "tunes") available for use by the
514 OpenEmbedded build system.
515 </para>
516
517 <para>
518 The list simply presents the tunes that are available.
519 Not all tunes may be compatible with a particular
520 machine configuration, or with each other in a
521 <ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Multilib</ulink>
522 configuration.
523 </para>
524
525 <para>
526 To add a tune to the list, be sure to append it with
527 spaces using the "+=" BitBake operator.
528 Do not simply replace the list by using the "=" operator.
529 See the
530 "<ulink url='&YOCTO_DOCS_BB_URL;#basic-syntax'>Basic Syntax</ulink>"
531 section in the BitBake User Manual for more information.
532 </para>
533 </glossdef>
534 </glossentry>
535
536 </glossdiv>
537
538 <glossdiv id='var-glossary-b'><title>B</title>
539
540 <glossentry id='var-B'><glossterm>B</glossterm>
541 <info>
542 B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process."
543 </info>
544 <glossdef>
545 <para role="glossdeffirst">
546 The directory within the
547 <link linkend='build-directory'>Build Directory</link>
548 in which the OpenEmbedded build system places generated
549 objects during a recipe's build process.
550 By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
551 directory, which is defined as:
552 <literallayout class='monospaced'>
553 S = "${WORKDIR}/${BP}"
554 </literallayout>
555 </para>
556
557 <para>
558 You can separate the (<filename>S</filename>) directory
559 and the directory pointed to by the <filename>B</filename>
560 variable.
561 Most Autotools-based recipes support separating these
562 directories.
563 The build system defaults to using separate directories for
564 <filename>gcc</filename> and some kernel recipes.
565 </para>
566 </glossdef>
567 </glossentry>
568
569 <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
570 <info>
571 BAD_RECOMMENDATIONS[doc] = "A list of packages not to install despite being recommended by a recipe. Support for this variable exists only when using the IPK packaging backend."
572 </info>
573 <glossdef>
574 <para role="glossdeffirst">
575 Lists "recommended-only" packages to not install.
576 Recommended-only packages are packages installed only
577 through the
578 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
579 variable.
580 You can prevent any of these "recommended" packages from
581 being installed by listing them with the
582 <filename>BAD_RECOMMENDATIONS</filename> variable:
583 <literallayout class='monospaced'>
584 BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
585 </literallayout>
586 </para>
587
588 <para>
589 You can set this variable globally in your
590 <filename>local.conf</filename> file or you can attach it to
591 a specific image recipe by using the recipe name override:
592 <literallayout class='monospaced'>
593 BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
594 </literallayout>
595 </para>
596
597 <para>
598 It is important to realize that if you choose to not install
599 packages using this variable and some other packages are
600 dependent on them (i.e. listed in a recipe's
601 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
602 variable), the OpenEmbedded build system ignores your
603 request and will install the packages to avoid dependency
604 errors.
605 </para>
606
607 <para>
608 Support for this variable exists only when using the
609 IPK and RPM packaging backend.
610 Support does not exist for DEB.
611 </para>
612
613 <para>
614 See the
615 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
616 and the
617 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
618 variables for related information.
619 </para>
620 </glossdef>
621 </glossentry>
622
623 <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm>
624 <info>
625 BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune."
626 </info>
627 <glossdef>
628 <para role="glossdeffirst">
629 The library directory name for the CPU or Application
630 Binary Interface (ABI) tune.
631 The <filename>BASE_LIB</filename> applies only in the
632 Multilib context.
633 See the
634 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
635 section in the Yocto Project Development Tasks Manual for
636 information on Multilib.
637 </para>
638
639 <para>
640 The <filename>BASE_LIB</filename> variable is defined in
641 the machine include files in the
642 <link linkend='source-directory'>Source Directory</link>.
643 If Multilib is not being used, the value defaults to "lib".
644 </para>
645 </glossdef>
646 </glossentry>
647
648 <glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm>
649 <info>
650 BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes."
651 </info>
652 <glossdef>
653 <para role="glossdeffirst">
654 Points to the base of the work directory for all recipes.
655 The default value is "${TMPDIR}/work".
656 </para>
657 </glossdef>
658 </glossentry>
659
660 <glossentry id='var-BB_ALLOWED_NETWORKS'><glossterm>BB_ALLOWED_NETWORKS</glossterm>
661 <info>
662 BB_ALLOWED_NETWORKS[doc] = "A list of hosts that the fetcher is allowed to use to obtain the required source code."
663 </info>
664 <glossdef>
665 <para>
666 Specifies a space-delimited list of hosts that the fetcher
667 is allowed to use to obtain the required source code.
668 Following are considerations surrounding this variable:
669 <itemizedlist>
670 <listitem><para>
671 This host list is only used if
672 <filename>BB_NO_NETWORK</filename> is either not
673 set or set to "0".
674 </para></listitem>
675 <listitem><para>
676 Limited support for wildcard matching against the
677 beginning of host names exists.
678 For example, the following setting matches
679 <filename>git.gnu.org</filename>,
680 <filename>ftp.gnu.org</filename>, and
681 <filename>foo.git.gnu.org</filename>.
682 <literallayout class='monospaced'>
683 BB_ALLOWED_NETWORKS = "*.gnu.org"
684 </literallayout>
685 <note><title>Important</title>
686 <para>The use of the "<filename>*</filename>"
687 character only works at the beginning of
688 a host name and it must be isolated from
689 the remainder of the host name.
690 You cannot use the wildcard character in any
691 other location of the name or combined with
692 the front part of the name.</para>
693
694 <para>For example,
695 <filename>*.foo.bar</filename> is supported,
696 while <filename>*aa.foo.bar</filename> is not.
697 </para>
698 </note>
699 </para></listitem>
700 <listitem><para>
701 Mirrors not in the host list are skipped and
702 logged in debug.
703 </para></listitem>
704 <listitem><para>
705 Attempts to access networks not in the host list
706 cause a failure.
707 </para></listitem>
708 </itemizedlist>
709 Using <filename>BB_ALLOWED_NETWORKS</filename> in
710 conjunction with
711 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
712 is very useful.
713 Adding the host you want to use to
714 <filename>PREMIRRORS</filename> results in the source code
715 being fetched from an allowed location and avoids raising
716 an error when a host that is not allowed is in a
717 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
718 statement.
719 This is because the fetcher does not attempt to use the
720 host listed in <filename>SRC_URI</filename> after a
721 successful fetch from the
722 <filename>PREMIRRORS</filename> occurs.
723 </para>
724 </glossdef>
725 </glossentry>
726
727 <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
728 <info>
729 BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)."
730 </info>
731 <glossdef>
732 <para role="glossdeffirst">
733 Defines how BitBake handles situations where an append
734 file (<filename>.bbappend</filename>) has no
735 corresponding recipe file (<filename>.bb</filename>).
736 This condition often occurs when layers get out of sync
737 (e.g. <filename>oe-core</filename> bumps a
738 recipe version and the old recipe no longer exists and the
739 other layer has not been updated to the new version
740 of the recipe yet).
741 </para>
742
743 <para>
744 The default fatal behavior is safest because it is
745 the sane reaction given something is out of sync.
746 It is important to realize when your changes are no longer
747 being applied.
748 </para>
749
750 <para>
751 You can change the default behavior by setting this
752 variable to "1", "yes", or "true"
753 in your <filename>local.conf</filename> file, which is
754 located in the
755 <link linkend='build-directory'>Build Directory</link>:
756 Here is an example:
757 <literallayout class='monospaced'>
758 BB_DANGLINGAPPENDS_WARNONLY = "1"
759 </literallayout>
760 </para>
761 </glossdef>
762 </glossentry>
763
764 <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
765 <info>
766 BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters."
767 </info>
768 <glossdef>
769 <para role="glossdeffirst">
770 Monitors disk space and available inodes during the build
771 and allows you to control the build based on these
772 parameters.
773 </para>
774
775 <para>
776 Disk space monitoring is disabled by default.
777 To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
778 variable to your <filename>conf/local.conf</filename> file found in the
779 <link linkend='build-directory'>Build Directory</link>.
780 Use the following form:
781 <literallayout class='monospaced'>
782 BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]"
783
784 where:
785
786 <replaceable>action</replaceable> is:
787 ABORT: Immediately abort the build when
788 a threshold is broken.
789 STOPTASKS: Stop the build after the currently
790 executing tasks have finished when
791 a threshold is broken.
792 WARN: Issue a warning but continue the
793 build when a threshold is broken.
794 Subsequent warnings are issued as
795 defined by the BB_DISKMON_WARNINTERVAL
796 variable, which must be defined in
797 the conf/local.conf file.
798
799 <replaceable>dir</replaceable> is:
800 Any directory you choose. You can specify one or
801 more directories to monitor by separating the
802 groupings with a space. If two directories are
803 on the same device, only the first directory
804 is monitored.
805
806 <replaceable>threshold</replaceable> is:
807 Either the minimum available disk space,
808 the minimum number of free inodes, or
809 both. You must specify at least one. To
810 omit one or the other, simply omit the value.
811 Specify the threshold using G, M, K for Gbytes,
812 Mbytes, and Kbytes, respectively. If you do
813 not specify G, M, or K, Kbytes is assumed by
814 default. Do not use GB, MB, or KB.
815 </literallayout>
816 </para>
817
818 <para>
819 Here are some examples:
820 <literallayout class='monospaced'>
821 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
822 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
823 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
824 </literallayout>
825 The first example works only if you also provide
826 the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
827 in the <filename>conf/local.conf</filename>.
828 This example causes the build system to immediately
829 abort when either the disk space in <filename>${TMPDIR}</filename> drops
830 below 1 Gbyte or the available free inodes drops below
831 100 Kbytes.
832 Because two directories are provided with the variable, the
833 build system also issue a
834 warning when the disk space in the
835 <filename>${SSTATE_DIR}</filename> directory drops
836 below 1 Gbyte or the number of free inodes drops
837 below 100 Kbytes.
838 Subsequent warnings are issued during intervals as
839 defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
840 variable.
841 </para>
842
843 <para>
844 The second example stops the build after all currently
845 executing tasks complete when the minimum disk space
846 in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
847 directory drops below 1 Gbyte.
848 No disk monitoring occurs for the free inodes in this case.
849 </para>
850
851 <para>
852 The final example immediately aborts the build when the
853 number of free inodes in the <filename>${TMPDIR}</filename> directory
854 drops below 100 Kbytes.
855 No disk space monitoring for the directory itself occurs
856 in this case.
857 </para>
858 </glossdef>
859 </glossentry>
860
861 <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
862 <info>
863 BB_DISKMON_WARNINTERVAL[doc] = "Defines the disk space and free inode warning intervals. To set these intervals, define the variable in the conf/local.conf file in the Build Directory."
864 </info>
865 <glossdef>
866 <para role="glossdeffirst">
867 Defines the disk space and free inode warning intervals.
868 To set these intervals, define the variable in your
869 <filename>conf/local.conf</filename> file in the
870 <link linkend='build-directory'>Build Directory</link>.
871 </para>
872
873 <para>
874 If you are going to use the
875 <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
876 also use the
877 <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
878 and define its action as "WARN".
879 During the build, subsequent warnings are issued each time
880 disk space or number of free inodes further reduces by
881 the respective interval.
882 </para>
883
884 <para>
885 If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
886 variable and you do use <filename>BB_DISKMON_DIRS</filename> with
887 the "WARN" action, the disk monitoring interval defaults to
888 the following:
889 <literallayout class='monospaced'>
890 BB_DISKMON_WARNINTERVAL = "50M,5K"
891 </literallayout>
892 </para>
893
894 <para>
895 When specifying the variable in your configuration file,
896 use the following form:
897 <literallayout class='monospaced'>
898 BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>"
899
900 where:
901
902 <replaceable>disk_space_interval</replaceable> is:
903 An interval of memory expressed in either
904 G, M, or K for Gbytes, Mbytes, or Kbytes,
905 respectively. You cannot use GB, MB, or KB.
906
907 <replaceable>disk_inode_interval</replaceable> is:
908 An interval of free inodes expressed in either
909 G, M, or K for Gbytes, Mbytes, or Kbytes,
910 respectively. You cannot use GB, MB, or KB.
911 </literallayout>
912 </para>
913
914 <para>
915 Here is an example:
916 <literallayout class='monospaced'>
917 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
918 BB_DISKMON_WARNINTERVAL = "50M,5K"
919 </literallayout>
920 These variables cause the OpenEmbedded build system to
921 issue subsequent warnings each time the available
922 disk space further reduces by 50 Mbytes or the number
923 of free inodes further reduces by 5 Kbytes in the
924 <filename>${SSTATE_DIR}</filename> directory.
925 Subsequent warnings based on the interval occur each time
926 a respective interval is reached beyond the initial warning
927 (i.e. 1 Gbytes and 100 Kbytes).
928 </para>
929 </glossdef>
930 </glossentry>
931
932 <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
933 <info>
934 BB_GENERATE_MIRROR_TARBALLS[doc] = "Causes tarballs of the source control repositories to be placed in the DL_DIR directory."
935 </info>
936 <glossdef>
937 <para role="glossdeffirst">
938 Causes tarballs of the source control repositories
939 (e.g. Git repositories), including metadata, to be placed
940 in the
941 <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
942 directory.
943 </para>
944
945 <para>
946 For performance reasons, creating and placing tarballs of
947 these repositories is not the default action by the
948 OpenEmbedded build system.
949 <literallayout class='monospaced'>
950 BB_GENERATE_MIRROR_TARBALLS = "1"
951 </literallayout>
952 Set this variable in your <filename>local.conf</filename>
953 file in the
954 <link linkend='build-directory'>Build Directory</link>.
955 </para>
956
957 <para>
958 Once you have the tarballs containing your source files,
959 you can clean up your <filename>DL_DIR</filename>
960 directory by deleting any Git or other source control
961 work directories.
962 </para>
963 </glossdef>
964 </glossentry>
965
966 <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
967 <info>
968 BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. This variable is automatically configured to be equal to the number of build system cores."
969 </info>
970 <glossdef>
971 <para role="glossdeffirst">
972 The maximum number of tasks BitBake should run in parallel
973 at any one time.
974 The OpenEmbedded build system automatically configures
975 this variable to be equal to the number of cores on the
976 build system.
977 For example, a system with a dual core processor that
978 also uses hyper-threading causes the
979 <filename>BB_NUMBER_THREADS</filename> variable to default
980 to "4".
981 </para>
982
983 <para>
984 For single socket systems (i.e. one CPU), you should not
985 have to override this variable to gain optimal parallelism
986 during builds.
987 However, if you have very large systems that employ
988 multiple physical CPUs, you might want to make sure the
989 <filename>BB_NUMBER_THREADS</filename> variable is not
990 set higher than "20".
991 </para>
992
993 <para>
994 For more information on speeding up builds, see the
995 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
996 section in the Yocto Project Development Tasks Manual.
997 </para>
998 </glossdef>
999 </glossentry>
1000
1001 <glossentry id='var-BB_SERVER_TIMEOUT'><glossterm>BB_SERVER_TIMEOUT</glossterm>
1002 <info>
1003 BB_SERVER_TIMEOUT [doc] = "Specifies the time (in seconds) after which to unload the BitBake server due to inactivity."
1004 </info>
1005 <glossdef>
1006 <para role="glossdeffirst">
1007 Specifies the time (in seconds) after which to unload the
1008 BitBake server due to inactivity.
1009 Set <filename>BB_SERVER_TIMEOUT</filename> to determine how
1010 long the BitBake server stays resident between invocations.
1011 </para>
1012
1013 <para>
1014 For example, the following statement in your
1015 <filename>local.conf</filename> file instructs the server
1016 to be unloaded after 20 seconds of inactivity:
1017 <literallayout class='monospaced'>
1018 BB_SERVER_TIMEOUT = "20"
1019 </literallayout>
1020 If you want the server to never be unloaded, set
1021 <filename>BB_SERVER_TIMEOUT</filename> to "-1".
1022 </para>
1023 </glossdef>
1024 </glossentry>
1025
1026 <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
1027 <info>
1028 BBCLASSEXTEND[doc] = "Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes are 'native', 'cross', 'nativesdk', and multilibs."
1029 </info>
1030 <glossdef>
1031 <para role="glossdeffirst">
1032 Allows you to extend a recipe so that it builds variants of the software.
1033 Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
1034 which is a copy of Quilt built to run on the build system;
1035 "crosses" such as <filename>gcc-cross</filename>,
1036 which is a compiler built to run on the build machine but produces binaries
1037 that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
1038 "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
1039 and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>".
1040 </para>
1041
1042 <para>
1043 To build a different variant of the recipe with a minimal amount of code, it usually
1044 is as simple as adding the following to your recipe:
1045 <literallayout class='monospaced'>
1046 BBCLASSEXTEND =+ "native nativesdk"
1047 BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>"
1048 </literallayout>
1049 <note>
1050 <para>
1051 Internally, the <filename>BBCLASSEXTEND</filename>
1052 mechanism generates recipe variants by rewriting
1053 variable values and applying overrides such as
1054 <filename>_class-native</filename>.
1055 For example, to generate a native version of a recipe,
1056 a
1057 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
1058 on "foo" is rewritten to a <filename>DEPENDS</filename>
1059 on "foo-native".
1060 </para>
1061
1062 <para>
1063 Even when using <filename>BBCLASSEXTEND</filename>, the
1064 recipe is only parsed once.
1065 Parsing once adds some limitations.
1066 For example, it is not possible to
1067 include a different file depending on the variant,
1068 since <filename>include</filename> statements are
1069 processed when the recipe is parsed.
1070 </para>
1071 </note>
1072 </para>
1073 </glossdef>
1074 </glossentry>
1075
1076 <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
1077 <info>
1078 BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables."
1079 </info>
1080 <glossdef>
1081 <para role="glossdeffirst">
1082 Lists the names of configured layers.
1083 These names are used to find the other <filename>BBFILE_*</filename>
1084 variables.
1085 Typically, each layer will append its name to this variable in its
1086 <filename>conf/layer.conf</filename> file.
1087 </para>
1088 </glossdef>
1089 </glossentry>
1090
1091 <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
1092 <info>
1093 BBFILE_PATTERN[doc] = "Variable that expands to match files from BBFILES in a particular layer. This variable is used in the layer.conf file and must be suffixed with the name of a layer."
1094 </info>
1095 <glossdef>
1096 <para role="glossdeffirst">
1097 Variable that expands to match files from
1098 <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
1099 in a particular layer.
1100 This variable is used in the <filename>conf/layer.conf</filename> file and must
1101 be suffixed with the name of the specific layer (e.g.
1102 <filename>BBFILE_PATTERN_emenlow</filename>).
1103 </para>
1104 </glossdef>
1105 </glossentry>
1106
1107 <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
1108 <info>
1109 BBFILE_PRIORITY[doc] = "Assigns the priority for recipe files in each layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe."
1110 </info>
1111 <glossdef>
1112 <para role="glossdeffirst">
1113 Assigns the priority for recipe files in each layer.
1114 </para>
1115
1116 <para>
1117 This variable is useful in situations where the same recipe appears in
1118 more than one layer.
1119 Setting this variable allows you to prioritize a
1120 layer against other layers that contain the same recipe - effectively
1121 letting you control the precedence for the multiple layers.
1122 The precedence established through this variable stands regardless of a
1123 recipe's version
1124 (<link linkend='var-PV'><filename>PV</filename></link> variable).
1125 For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
1126 which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
1127 lower precedence.
1128 </para>
1129
1130 <para>
1131 A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
1132 precedence.
1133 For example, the value 6 has a higher precedence than the value 5.
1134 If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
1135 dependencies (see the
1136 <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
1137 more information.
1138 The default priority, if unspecified
1139 for a layer with no dependencies, is the lowest defined priority + 1
1140 (or 1 if no priorities are defined).
1141 </para>
1142 <tip>
1143 You can use the command <filename>bitbake-layers show-layers</filename> to list
1144 all configured layers along with their priorities.
1145 </tip>
1146 </glossdef>
1147 </glossentry>
1148
1149 <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
1150 <info>
1151 BBFILES[doc] = "A space-separated list of recipe files BitBake uses to build software."
1152 </info>
1153 <glossdef>
1154 <para role="glossdeffirst">
1155 A space-separated list of recipe files BitBake uses to
1156 build software.
1157 </para>
1158
1159 <para>
1160 When specifying recipe files, you can pattern match using
1161 Python's
1162 <ulink url='https://docs.python.org/3/library/glob.html'><filename>glob</filename></ulink>
1163 syntax.
1164 For details on the syntax, see the documentation by
1165 following the previous link.
1166 </para>
1167 </glossdef>
1168 </glossentry>
1169
1170 <glossentry id='var-BBFILES_DYNAMIC'><glossterm>BBFILES_DYNAMIC</glossterm>
1171 <info>
1172 BBFILES_DYNAMIC[doc] = "Activates content when identified layers are present."
1173 </info>
1174 <glossdef>
1175 <para role="glossdeffirst">
1176 Activates content when identified layers are present.
1177 You identify the layers by the collections that the layers
1178 define.
1179 </para>
1180
1181 <para>
1182 Use the <filename>BBFILES_DYNAMIC</filename> variable to
1183 avoid <filename>.bbappend</filename> files whose
1184 corresponding <filename>.bb</filename> file is in a layer
1185 that attempts to modify other layers through
1186 <filename>.bbappend</filename> but does not want to
1187 introduce a hard dependency on those other layers.
1188 </para>
1189
1190 <para>
1191 Use the following form for
1192 <filename>BBFILES_DYNAMIC</filename>:
1193 <literallayout class='monospaced'>
1194 <replaceable>collection_name</replaceable>:<replaceable>filename_pattern</replaceable>
1195 </literallayout>
1196 The following example identifies two collection names and
1197 two filename patterns:
1198 <literallayout class='monospaced'>
1199 BBFILES_DYNAMIC += " \
1200 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
1201 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
1202 "
1203 </literallayout>
1204 This next example shows an error message that occurs
1205 because invalid entries are found, which cause parsing to
1206 abort:
1207 <literallayout class='monospaced'>
1208 ERROR: BBFILES_DYNAMIC entries must be of the form &lt;collection name&gt;:&lt;filename pattern&gt;, not:
1209 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
1210 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
1211 </literallayout>
1212 </para>
1213 </glossdef>
1214 </glossentry>
1215
1216 <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
1217 <info>
1218 BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure."
1219 </info>
1220 <glossdef>
1221 <para role="glossdeffirst">
1222 Variable that controls how BitBake displays logs on build failure.
1223 </para>
1224 </glossdef>
1225 </glossentry>
1226
1227 <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm>
1228 <info>
1229 BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure."
1230 </info>
1231 <glossdef>
1232 <para role="glossdeffirst">
1233 If
1234 <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link>
1235 is set, specifies the maximum number of lines from the
1236 task log file to print when reporting a failed task.
1237 If you do not set <filename>BBINCLUDELOGS_LINES</filename>,
1238 the entire log is printed.
1239 </para>
1240 </glossdef>
1241 </glossentry>
1242
1243 <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
1244 <info>
1245 BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file."
1246 </info>
1247 <glossdef>
1248 <para role="glossdeffirst">
1249 Lists the layers to enable during the build.
1250 This variable is defined in the <filename>bblayers.conf</filename> configuration
1251 file in the
1252 <link linkend='build-directory'>Build Directory</link>.
1253 Here is an example:
1254 <literallayout class='monospaced'>
1255 BBLAYERS = " \
1256 /home/scottrif/poky/meta \
1257 /home/scottrif/poky/meta-poky \
1258 /home/scottrif/poky/meta-yocto-bsp \
1259 /home/scottrif/poky/meta-mykernel \
1260 "
1261 </literallayout>
1262 </para>
1263
1264 <para>
1265 This example enables four layers, one of which is a custom, user-defined layer
1266 named <filename>meta-mykernel</filename>.
1267 </para>
1268 </glossdef>
1269 </glossentry>
1270
1271 <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
1272 <info>
1273 BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files."
1274 </info>
1275 <glossdef>
1276 <para role="glossdeffirst">
1277 Prevents BitBake from processing recipes and recipe
1278 append files.
1279 </para>
1280
1281 <para>
1282 You can use the <filename>BBMASK</filename> variable
1283 to "hide" these <filename>.bb</filename> and
1284 <filename>.bbappend</filename> files.
1285 BitBake ignores any recipe or recipe append files that
1286 match any of the expressions.
1287 It is as if BitBake does not see them at all.
1288 Consequently, matching files are not parsed or otherwise
1289 used by BitBake.
1290 </para>
1291
1292 <para>
1293 The values you provide are passed to Python's regular
1294 expression compiler.
1295 Consequently, the syntax follows Python's Regular
1296 Expression (re) syntax.
1297 The expressions are compared against the full paths to
1298 the files.
1299 For complete syntax information, see Python's
1300 documentation at
1301 <ulink url='http://docs.python.org/3/library/re.html#re'></ulink>.
1302 </para>
1303
1304 <para>
1305 The following example uses a complete regular expression
1306 to tell BitBake to ignore all recipe and recipe append
1307 files in the <filename>meta-ti/recipes-misc/</filename>
1308 directory:
1309 <literallayout class='monospaced'>
1310 BBMASK = "meta-ti/recipes-misc/"
1311 </literallayout>
1312 If you want to mask out multiple directories or recipes,
1313 you can specify multiple regular expression fragments.
1314 This next example masks out multiple directories and
1315 individual recipes:
1316 <literallayout class='monospaced'>
1317 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
1318 BBMASK += "/meta-oe/recipes-support/"
1319 BBMASK += "/meta-foo/.*/openldap"
1320 BBMASK += "opencv.*\.bbappend"
1321 BBMASK += "lzma"
1322 </literallayout>
1323 <note>
1324 When specifying a directory name, use the trailing
1325 slash character to ensure you match just that directory
1326 name.
1327 </note>
1328 </para>
1329 </glossdef>
1330 </glossentry>
1331
1332 <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm>
1333 <info>
1334 BBMULTICONFIG[doc] = "Specifies each additional separate configuration when you are building targets with multiple configurations."
1335 </info>
1336 <glossdef>
1337 <para role="glossdeffirst">
1338 Specifies each additional separate configuration when you
1339 are building targets with multiple configurations.
1340 Use this variable in your
1341 <filename>conf/local.conf</filename> configuration file.
1342 Specify a <replaceable>multiconfigname</replaceable> for
1343 each configuration file you are using.
1344 For example, the following line specifies three
1345 configuration files:
1346 <literallayout class='monospaced'>
1347 BBMULTICONFIG = "configA configB configC"
1348 </literallayout>
1349 Each configuration file you use must reside in the
1350 <link linkend='build-directory'>Build Directory</link>
1351 <filename>conf/multiconfig</filename> directory
1352 (e.g.
1353 <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>).
1354 </para>
1355
1356 <para>
1357 For information on how to use
1358 <filename>BBMULTICONFIG</filename> in an environment that
1359 supports building targets with multiple configurations,
1360 see the
1361 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-building-images-for-multiple-targets-using-multiple-configurations'>Building Images for Multiple Targets Using Multiple Configurations</ulink>"
1362 section in the Yocto Project Development Tasks Manual.
1363 </para>
1364 </glossdef>
1365 </glossentry>
1366
1367 <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
1368 <info>
1369 BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable."
1370 </info>
1371 <glossdef>
1372 <para role="glossdeffirst">
1373 Used by BitBake to locate
1374 <filename>.bbclass</filename> and configuration files.
1375 This variable is analogous to the
1376 <filename>PATH</filename> variable.
1377 <note>
1378 If you run BitBake from a directory outside of the
1379 <link linkend='build-directory'>Build Directory</link>,
1380 you must be sure to set
1381 <filename>BBPATH</filename> to point to the
1382 Build Directory.
1383 Set the variable as you would any environment variable
1384 and then run BitBake:
1385 <literallayout class='monospaced'>
1386 $ BBPATH = "<replaceable>build_directory</replaceable>"
1387 $ export BBPATH
1388 $ bitbake <replaceable>target</replaceable>
1389 </literallayout>
1390 </note>
1391 </para>
1392 </glossdef>
1393 </glossentry>
1394
1395 <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
1396 <info>
1397 BBSERVER[doc] = "Points to the BitBake remote server."
1398 </info>
1399 <glossdef>
1400 <para role="glossdeffirst">
1401 If defined in the BitBake environment,
1402 <filename>BBSERVER</filename> points to the BitBake
1403 remote server.
1404 </para>
1405
1406 <para>
1407 Use the following format to export the variable to the
1408 BitBake environment:
1409 <literallayout class='monospaced'>
1410 export BBSERVER=localhost:$port
1411 </literallayout>
1412 </para>
1413
1414 <para>
1415 By default, <filename>BBSERVER</filename> also appears in
1416 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>.
1417 Consequently, <filename>BBSERVER</filename> is excluded
1418 from checksum and dependency data.
1419 </para>
1420 </glossdef>
1421 </glossentry>
1422
1423 <glossentry id='var-BINCONFIG'><glossterm>BINCONFIG</glossterm>
1424 <info>
1425 BINCONFIG[doc] = "When inheriting the binconfig-disabled class, this variable specifies binary configuration scripts to disable in favor of using pkg-config to query the information."
1426 </info>
1427 <glossdef>
1428 <para role="glossdeffirst">
1429 When inheriting the
1430 <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link>
1431 class, this variable specifies binary configuration
1432 scripts to disable in favor of using
1433 <filename>pkg-config</filename> to query the information.
1434 The <filename>binconfig-disabled</filename> class will
1435 modify the specified scripts to return an error so that
1436 calls to them can be easily found and replaced.
1437 </para>
1438
1439 <para>
1440 To add multiple scripts, separate them by spaces.
1441 Here is an example from the <filename>libpng</filename>
1442 recipe:
1443 <literallayout class='monospaced'>
1444 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
1445 </literallayout>
1446 </para>
1447 </glossdef>
1448 </glossentry>
1449
1450 <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
1451 <info>
1452 BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing."
1453 </info>
1454 <glossdef>
1455 <para role="glossdeffirst">
1456 When inheriting the
1457 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
1458 class, this variable specifies a wildcard for
1459 configuration scripts that need editing.
1460 The scripts are edited to correct any paths that have been
1461 set up during compilation so that they are correct for
1462 use when installed into the sysroot and called by the
1463 build processes of other recipes.
1464 <note>
1465 The <filename>BINCONFIG_GLOB</filename> variable
1466 uses
1467 <ulink url='http://tldp.org/LDP/abs/html/globbingref.html'>shell globbing</ulink>,
1468 which is recognition and expansion of wildcards during
1469 pattern matching.
1470 Shell globbing is very similar to
1471 <ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>
1472 and
1473 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>.
1474 </note>
1475 </para>
1476
1477 <para>
1478 For more information on how this variable works, see
1479 <filename>meta/classes/binconfig.bbclass</filename> in the
1480 <link linkend='source-directory'>Source Directory</link>.
1481 You can also find general information on the class in the
1482 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
1483 section.
1484 </para>
1485 </glossdef>
1486 </glossentry>
1487
1488 <glossentry id='var-BP'><glossterm>BP</glossterm>
1489 <info>
1490 BP[doc] = "The base recipe name and version but without any special recipe name suffix (i.e. -native, lib64-, and so forth). BP is comprised of ${BPN}-${PV}"
1491 </info>
1492 <glossdef>
1493 <para role="glossdeffirst">
1494 The base recipe name and version but without any special
1495 recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
1496 and so forth).
1497 <filename>BP</filename> is comprised of the following:
1498 <literallayout class="monospaced">
1499 ${BPN}-${PV}
1500 </literallayout>
1501 </para>
1502 </glossdef>
1503 </glossentry>
1504
1505 <glossentry id='var-BPN'><glossterm>BPN</glossterm>
1506 <info>
1507 BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes."
1508 </info>
1509 <glossdef>
1510 <para role="glossdeffirst">
1511 This variable is a version of the
1512 <link linkend='var-PN'><filename>PN</filename></link>
1513 variable with common prefixes and suffixes
1514 removed, such as <filename>nativesdk-</filename>,
1515 <filename>-cross</filename>,
1516 <filename>-native</filename>, and multilib's
1517 <filename>lib64-</filename> and
1518 <filename>lib32-</filename>.
1519 The exact lists of prefixes and suffixes removed are
1520 specified by the
1521 <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link>
1522 and
1523 <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link>
1524 variables, respectively.
1525 </para>
1526 </glossdef>
1527 </glossentry>
1528
1529 <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm>
1530 <info>
1531 BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe."
1532 </info>
1533 <glossdef>
1534 <para role="glossdeffirst">
1535 Specifies a URL for an upstream bug tracking website for
1536 a recipe.
1537 The OpenEmbedded build system does not use this variable.
1538 Rather, the variable is a useful pointer in case a bug
1539 in the software being built needs to be manually reported.
1540 </para>
1541 </glossdef>
1542 </glossentry>
1543
1544 <glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm>
1545 <info>
1546 BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)."
1547 </info>
1548 <glossdef>
1549 <para role="glossdeffirst">
1550 Specifies the architecture of the build host
1551 (e.g. <filename>i686</filename>).
1552 The OpenEmbedded build system sets the value of
1553 <filename>BUILD_ARCH</filename> from the machine name
1554 reported by the <filename>uname</filename> command.
1555 </para>
1556 </glossdef>
1557 </glossentry>
1558
1559 <glossentry id='var-BUILD_AS_ARCH'><glossterm>BUILD_AS_ARCH</glossterm>
1560 <info>
1561 BUILD_AS_ARCH[doc] = "Specifies the architecture-specific assembler flags for the build host."
1562 </info>
1563 <glossdef>
1564 <para role="glossdeffirst">
1565 Specifies the architecture-specific assembler flags for
1566 the build host. By default, the value of
1567 <filename>BUILD_AS_ARCH</filename> is empty.
1568 </para>
1569 </glossdef>
1570 </glossentry>
1571
1572 <glossentry id='var-BUILD_CC_ARCH'><glossterm>BUILD_CC_ARCH</glossterm>
1573 <info>
1574 BUILD_CC_ARCH[doc] = "Specifies the architecture-specific C compiler flags for the build host."
1575 </info>
1576 <glossdef>
1577 <para role="glossdeffirst">
1578 Specifies the architecture-specific C compiler flags for
1579 the build host. By default, the value of
1580 <filename>BUILD_CC_ARCH</filename> is empty.
1581 </para>
1582 </glossdef>
1583 </glossentry>
1584
1585 <glossentry id='var-BUILD_CCLD'><glossterm>BUILD_CCLD</glossterm>
1586 <info>
1587 BUILD_CCLD[doc] = "Specifies the linker command to be used for the build host when the C compiler is being used as the linker."
1588 </info>
1589 <glossdef>
1590 <para role="glossdeffirst">
1591 Specifies the linker command to be used for the build host
1592 when the C compiler is being used as the linker. By default,
1593 <filename>BUILD_CCLD</filename> points to GCC and passes as
1594 arguments the value of
1595 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1596 assuming <filename>BUILD_CC_ARCH</filename> is set.
1597 </para>
1598 </glossdef>
1599 </glossentry>
1600
1601 <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm>
1602 <info>
1603 BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host."
1604 </info>
1605 <glossdef>
1606 <para role="glossdeffirst">
1607 Specifies the flags to pass to the C compiler when building
1608 for the build host.
1609 When building in the <filename>-native</filename> context,
1610 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
1611 is set to the value of this variable by default.
1612 </para>
1613 </glossdef>
1614 </glossentry>
1615
1616 <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm>
1617 <info>
1618 BUILD_CPPFLAGS[doc] = "Specifies the flags to pass to the C preprocessor (i.e. to both the C and the C++ compilers) when building for the build host."
1619 </info>
1620 <glossdef>
1621 <para role="glossdeffirst">
1622 Specifies the flags to pass to the C preprocessor
1623 (i.e. to both the C and the C++ compilers) when building
1624 for the build host.
1625 When building in the <filename>-native</filename> context,
1626 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
1627 is set to the value of this variable by default.
1628 </para>
1629 </glossdef>
1630 </glossentry>
1631
1632 <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm>
1633 <info>
1634 BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host."
1635 </info>
1636 <glossdef>
1637 <para role="glossdeffirst">
1638 Specifies the flags to pass to the C++ compiler when
1639 building for the build host.
1640 When building in the <filename>-native</filename> context,
1641 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
1642 is set to the value of this variable by default.
1643 </para>
1644 </glossdef>
1645 </glossentry>
1646
1647 <glossentry id='var-BUILD_FC'><glossterm>BUILD_FC</glossterm>
1648 <info>
1649 BUILD_FC[doc] = "Specifies the Fortran compiler command for the build host."
1650 </info>
1651 <glossdef>
1652 <para role="glossdeffirst">
1653 Specifies the Fortran compiler command for the build host.
1654 By default, <filename>BUILD_FC</filename> points to
1655 Gfortran and passes as arguments the value of
1656 <link linkend='var-BUILD_CC_ARCH'><filename>BUILD_CC_ARCH</filename></link>,
1657 assuming <filename>BUILD_CC_ARCH</filename> is set.
1658 </para>
1659 </glossdef>
1660 </glossentry>
1661
1662 <glossentry id='var-BUILD_LD'><glossterm>BUILD_LD</glossterm>
1663 <info>
1664 BUILD_LD[doc] = "Specifies the linker command for the build host."
1665 </info>
1666 <glossdef>
1667 <para role="glossdeffirst">
1668 Specifies the linker command for the build host. By default,
1669 <filename>BUILD_LD</filename> points to the GNU linker (ld)
1670 and passes as arguments the value of
1671 <link linkend='var-BUILD_LD_ARCH'><filename>BUILD_LD_ARCH</filename></link>,
1672 assuming <filename>BUILD_LD_ARCH</filename> is set.
1673 </para>
1674 </glossdef>
1675 </glossentry>
1676
1677 <glossentry id='var-BUILD_LD_ARCH'><glossterm>BUILD_LD_ARCH</glossterm>
1678 <info>
1679 BUILD_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the build."
1680 </info>
1681 <glossdef>
1682 <para role="glossdeffirst">
1683 Specifies architecture-specific linker flags for the build
1684 host. By default, the value of
1685 <filename>BUILD_LD_ARCH</filename> is empty.
1686 </para>
1687 </glossdef>
1688 </glossentry>
1689
1690 <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm>
1691 <info>
1692 BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host."
1693 </info>
1694 <glossdef>
1695 <para role="glossdeffirst">
1696 Specifies the flags to pass to the linker when building
1697 for the build host.
1698 When building in the <filename>-native</filename> context,
1699 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1700 is set to the value of this variable by default.
1701 </para>
1702 </glossdef>
1703 </glossentry>
1704
1705 <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm>
1706 <info>
1707 BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK."
1708 </info>
1709 <glossdef>
1710 <para role="glossdeffirst">
1711 Specifies the optimization flags passed to the C compiler
1712 when building for the build host or the SDK.
1713 The flags are passed through the
1714 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
1715 and
1716 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
1717 default values.
1718 </para>
1719
1720 <para>
1721 The default value of the
1722 <filename>BUILD_OPTIMIZATION</filename> variable is
1723 "-O2 -pipe".
1724 </para>
1725 </glossdef>
1726 </glossentry>
1727
1728 <glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm>
1729 <info>
1730 BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)."
1731 </info>
1732 <glossdef>
1733 <para role="glossdeffirst">
1734 Specifies the operating system in use on the build
1735 host (e.g. "linux").
1736 The OpenEmbedded build system sets the value of
1737 <filename>BUILD_OS</filename> from the OS reported by
1738 the <filename>uname</filename> command - the first word,
1739 converted to lower-case characters.
1740 </para>
1741 </glossdef>
1742 </glossentry>
1743
1744 <glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm>
1745 <info>
1746 BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes."
1747 </info>
1748 <glossdef>
1749 <para role="glossdeffirst">
1750 The toolchain binary prefix used for native recipes.
1751 The OpenEmbedded build system uses the
1752 <filename>BUILD_PREFIX</filename> value to set the
1753 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
1754 when building for <filename>native</filename> recipes.
1755 </para>
1756 </glossdef>
1757 </glossentry>
1758
1759 <glossentry id='var-BUILD_STRIP'><glossterm>BUILD_STRIP</glossterm>
1760 <info>
1761 BUILD_STRIP[doc] = "Specifies the command to be used to strip debugging symbols from binaries produced for the build host."
1762 </info>
1763 <glossdef>
1764 <para role="glossdeffirst">
1765 Specifies the command to be used to strip debugging symbols
1766 from binaries produced for the build host. By default,
1767 <filename>BUILD_STRIP</filename> points to
1768 <filename>${</filename><link linkend='var-BUILD_PREFIX'><filename>BUILD_PREFIX</filename></link><filename>}strip</filename>.
1769 </para>
1770 </glossdef>
1771 </glossentry>
1772
1773 <glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm>
1774 <info>
1775 BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes."
1776 </info>
1777 <glossdef>
1778 <para role="glossdeffirst">
1779 Specifies the system, including the architecture and
1780 the operating system, to use when building for the build
1781 host (i.e. when building <filename>native</filename>
1782 recipes).
1783 </para>
1784
1785 <para>
1786 The OpenEmbedded build system automatically sets this
1787 variable based on
1788 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>,
1789 <link linkend='var-BUILD_VENDOR'><filename>BUILD_VENDOR</filename></link>,
1790 and
1791 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
1792 You do not need to set the <filename>BUILD_SYS</filename>
1793 variable yourself.
1794 </para>
1795 </glossdef>
1796 </glossentry>
1797
1798 <glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm>
1799 <info>
1800 BUILD_VENDOR[doc] = "The vendor name to use when building for the build host."
1801 </info>
1802 <glossdef>
1803 <para role="glossdeffirst">
1804 Specifies the vendor name to use when building for the
1805 build host.
1806 The default value is an empty string ("").
1807 </para>
1808 </glossdef>
1809 </glossentry>
1810
1811 <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
1812 <info>
1813 BUILDDIR[doc] = "Points to the location of the Build Directory."
1814 </info>
1815 <glossdef>
1816 <para role="glossdeffirst">
1817 Points to the location of the
1818 <link linkend='build-directory'>Build Directory</link>.
1819 You can define this directory indirectly through the
1820 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
1821 script by passing in a Build Directory path when you run
1822 the script.
1823 If you run the script and do not provide a Build Directory
1824 path, the <filename>BUILDDIR</filename> defaults to
1825 <filename>build</filename> in the current directory.
1826 </para>
1827 </glossdef>
1828 </glossentry>
1829
1830 <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm>
1831 <info>
1832 BUILDHISTORY_COMMIT[doc] = "When inheriting the buildhistory class, this variable specifies whether or not to commit the build history output in a local Git repository."
1833 </info>
1834 <glossdef>
1835 <para role="glossdeffirst">
1836 When inheriting the
1837 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1838 class, this variable specifies whether or not to commit the
1839 build history output in a local Git repository.
1840 If set to "1", this local repository will be maintained
1841 automatically by the
1842 <filename>buildhistory</filename>
1843 class and a commit will be created on every
1844 build for changes to each top-level subdirectory of the
1845 build history output (images, packages, and sdk).
1846 If you want to track changes to build history over
1847 time, you should set this value to "1".
1848 </para>
1849
1850 <para>
1851 By default, the <filename>buildhistory</filename> class
1852 does not commit the build history output in a local
1853 Git repository:
1854 <literallayout class='monospaced'>
1855 BUILDHISTORY_COMMIT ?= "0"
1856 </literallayout>
1857 </para>
1858 </glossdef>
1859 </glossentry>
1860
1861 <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm>
1862 <info>
1863 BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit."
1864 </info>
1865 <glossdef>
1866 <para role="glossdeffirst">
1867 When inheriting the
1868 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1869 class, this variable specifies the author to use for each
1870 Git commit.
1871 In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename>
1872 variable to work, the
1873 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
1874 variable must be set to "1".
1875 </para>
1876
1877 <para>
1878 Git requires that the value you provide for the
1879 <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable
1880 takes the form of "name <replaceable>email@host</replaceable>".
1881 Providing an email address or host that is not valid does
1882 not produce an error.
1883 </para>
1884
1885 <para>
1886 By default, the <filename>buildhistory</filename> class
1887 sets the variable as follows:
1888 <literallayout class='monospaced'>
1889 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory &lt;buildhistory@${DISTRO}&gt;"
1890 </literallayout>
1891 </para>
1892 </glossdef>
1893 </glossentry>
1894
1895 <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm>
1896 <info>
1897 BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept."
1898 </info>
1899 <glossdef>
1900 <para role="glossdeffirst">
1901 When inheriting the
1902 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1903 class, this variable specifies the directory in which
1904 build history information is kept.
1905 For more information on how the variable works, see the
1906 <filename>buildhistory.class</filename>.
1907 </para>
1908
1909 <para>
1910 By default, the <filename>buildhistory</filename> class
1911 sets the directory as follows:
1912 <literallayout class='monospaced'>
1913 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1914 </literallayout>
1915 </para>
1916 </glossdef>
1917 </glossentry>
1918
1919 <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm>
1920 <info>
1921 BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled."
1922 </info>
1923 <glossdef>
1924 <para role="glossdeffirst">
1925 When inheriting the
1926 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1927 class, this variable specifies the build history features
1928 to be enabled.
1929 For more information on how build history works, see the
1930 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
1931 section in the Yocto Project Development Tasks Manual.
1932 </para>
1933
1934 <para>
1935 You can specify these features in the form of a
1936 space-separated list:
1937 <itemizedlist>
1938 <listitem><para><emphasis>image:</emphasis>
1939 Analysis of the contents of images, which
1940 includes the list of installed packages among other
1941 things.
1942 </para></listitem>
1943 <listitem><para><emphasis>package:</emphasis>
1944 Analysis of the contents of individual packages.
1945 </para></listitem>
1946 <listitem><para><emphasis>sdk:</emphasis>
1947 Analysis of the contents of the software
1948 development kit (SDK).
1949 </para></listitem>
1950 <listitem><para><emphasis>task:</emphasis>
1951 Save output file signatures for
1952 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state</ulink>
1953 (sstate) tasks.
1954 This saves one file per task and lists the SHA-256
1955 checksums for each file staged (i.e. the output of
1956 the task).
1957 </para></listitem>
1958 </itemizedlist>
1959 </para>
1960
1961 <para>
1962 By default, the <filename>buildhistory</filename> class
1963 enables the following features:
1964 <literallayout class='monospaced'>
1965 BUILDHISTORY_FEATURES ?= "image package sdk"
1966 </literallayout>
1967 </para>
1968 </glossdef>
1969 </glossentry>
1970
1971 <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm>
1972 <info>
1973 BUILDHISTORY_IMAGE_FILES[doc] = "When inheriting the buildhistory class, this variable specifies a list of paths to files copied from the image contents into the build history directory under an "image-files" directory in the directory for the image, so that you can track the contents of each file."
1974 </info>
1975 <glossdef>
1976 <para role="glossdeffirst">
1977 When inheriting the
1978 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
1979 class, this variable specifies a list of paths to files
1980 copied from the
1981 image contents into the build history directory under
1982 an "image-files" directory in the directory for
1983 the image, so that you can track the contents of each file.
1984 The default is to copy <filename>/etc/passwd</filename>
1985 and <filename>/etc/group</filename>, which allows you to
1986 monitor for changes in user and group entries.
1987 You can modify the list to include any file.
1988 Specifying an invalid path does not produce an error.
1989 Consequently, you can include files that might
1990 not always be present.
1991 </para>
1992
1993 <para>
1994 By default, the <filename>buildhistory</filename> class
1995 provides paths to the following files:
1996 <literallayout class='monospaced'>
1997 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1998 </literallayout>
1999 </para>
2000 </glossdef>
2001 </glossentry>
2002
2003 <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm>
2004 <info>
2005 BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes."
2006 </info>
2007 <glossdef>
2008 <para role="glossdeffirst">
2009 When inheriting the
2010 <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link>
2011 class, this variable optionally specifies a remote
2012 repository to which build history pushes Git changes.
2013 In order for <filename>BUILDHISTORY_PUSH_REPO</filename>
2014 to work,
2015 <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link>
2016 must be set to "1".
2017 </para>
2018
2019 <para>
2020 The repository should correspond to a remote
2021 address that specifies a repository as understood by
2022 Git, or alternatively to a remote name that you have
2023 set up manually using <filename>git remote</filename>
2024 within the local repository.
2025 </para>
2026
2027 <para>
2028 By default, the <filename>buildhistory</filename> class
2029 sets the variable as follows:
2030 <literallayout class='monospaced'>
2031 BUILDHISTORY_PUSH_REPO ?= ""
2032 </literallayout>
2033 </para>
2034 </glossdef>
2035 </glossentry>
2036
2037 <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm>
2038 <info>
2039 BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK."
2040 </info>
2041 <glossdef>
2042 <para role="glossdeffirst">
2043 Specifies the flags to pass to the C compiler when building
2044 for the SDK.
2045 When building in the <filename>nativesdk-</filename>
2046 context,
2047 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
2048 is set to the value of this variable by default.
2049 </para>
2050 </glossdef>
2051 </glossentry>
2052
2053 <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm>
2054 <info>
2055 BUILDSDK_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the SDK."
2056 </info>
2057 <glossdef>
2058 <para role="glossdeffirst">
2059 Specifies the flags to pass to the C pre-processor
2060 (i.e. to both the C and the C++ compilers) when building
2061 for the SDK.
2062 When building in the <filename>nativesdk-</filename>
2063 context,
2064 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
2065 is set to the value of this variable by default.
2066 </para>
2067 </glossdef>
2068 </glossentry>
2069
2070 <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm>
2071 <info>
2072 BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK."
2073 </info>
2074 <glossdef>
2075 <para role="glossdeffirst">
2076 Specifies the flags to pass to the C++ compiler when
2077 building for the SDK.
2078 When building in the <filename>nativesdk-</filename>
2079 context,
2080 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
2081 is set to the value of this variable by default.
2082 </para>
2083 </glossdef>
2084 </glossentry>
2085
2086 <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm>
2087 <info>
2088 BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK."
2089 </info>
2090 <glossdef>
2091 <para role="glossdeffirst">
2092 Specifies the flags to pass to the linker when building
2093 for the SDK.
2094 When building in the <filename>nativesdk-</filename>
2095 context,
2096 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
2097 is set to the value of this variable by default.
2098 </para>
2099 </glossdef>
2100 </glossentry>
2101
2102 <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm>
2103 <info>
2104 BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class."
2105 </info>
2106 <glossdef>
2107 <para role="glossdeffirst">
2108 Points to the location of the directory that holds build
2109 statistics when you use and enable the
2110 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
2111 class.
2112 The <filename>BUILDSTATS_BASE</filename> directory defaults
2113 to
2114 <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/buildstats/</filename>.
2115 </para>
2116 </glossdef>
2117 </glossentry>
2118
2119 <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
2120 <info>
2121 BUSYBOX_SPLIT_SUID[doc] = "For the BusyBox recipe, specifies whether to split the output executable file into two parts: one for features that require setuid root, and one for the remaining features."
2122 </info>
2123 <glossdef>
2124 <para role="glossdeffirst">
2125 For the BusyBox recipe, specifies whether to split the
2126 output executable file into two parts: one for features
2127 that require <filename>setuid root</filename>, and one for
2128 the remaining features (i.e. those that do not require
2129 <filename>setuid root</filename>).
2130 </para>
2131
2132 <para>
2133 The <filename>BUSYBOX_SPLIT_SUID</filename> variable
2134 defaults to "1", which results in splitting the output
2135 executable file.
2136 Set the variable to "0" to get a single output executable
2137 file.
2138 </para>
2139 </glossdef>
2140 </glossentry>
2141
2142 </glossdiv>
2143
2144 <glossdiv id='var-glossary-c'><title>C</title>
2145
2146 <glossentry id='var-CACHE'><glossterm>CACHE</glossterm>
2147 <info>
2148 CACHE[doc] = "The directory BitBake uses to store a cache of the metadata."
2149 </info>
2150 <glossdef>
2151 <para role="glossdeffirst">
2152 Specifies the directory BitBake uses to store a cache
2153 of the
2154 <link linkend='metadata'>Metadata</link>
2155 so it does not need to be parsed every time BitBake is
2156 started.
2157 </para>
2158 </glossdef>
2159 </glossentry>
2160
2161 <glossentry id='var-CC'><glossterm>CC</glossterm>
2162 <info>
2163 CC[doc] = "Minimum command and arguments to run the C compiler."
2164 </info>
2165 <glossdef>
2166 <para role="glossdeffirst">
2167 The minimal command and arguments used to run the C
2168 compiler.
2169 </para>
2170 </glossdef>
2171 </glossentry>
2172
2173 <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
2174 <info>
2175 CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS."
2176 </info>
2177 <glossdef>
2178 <para role="glossdeffirst">
2179 Specifies the flags to pass to the C compiler.
2180 This variable is exported to an environment
2181 variable and thus made visible to the software being
2182 built during the compilation step.
2183 </para>
2184
2185 <para>
2186 Default initialization for <filename>CFLAGS</filename>
2187 varies depending on what is being built:
2188 <itemizedlist>
2189 <listitem><para>
2190 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
2191 when building for the target
2192 </para></listitem>
2193 <listitem><para>
2194 <link linkend='var-BUILD_CFLAGS'><filename>BUILD_CFLAGS</filename></link>
2195 when building for the build host (i.e.
2196 <filename>-native</filename>)
2197 </para></listitem>
2198 <listitem><para>
2199 <link linkend='var-BUILDSDK_CFLAGS'><filename>BUILDSDK_CFLAGS</filename></link>
2200 when building for an SDK (i.e.
2201 <filename>nativesdk-</filename>)
2202 </para></listitem>
2203 </itemizedlist>
2204 </para>
2205 </glossdef>
2206 </glossentry>
2207
2208 <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm>
2209 <info>
2210 CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)."
2211 </info>
2212 <glossdef>
2213 <para role="glossdeffirst">
2214 An internal variable specifying the special class override
2215 that should currently apply (e.g. "class-target",
2216 "class-native", and so forth).
2217 The classes that use this variable (e.g.
2218 <link linkend='ref-classes-native'><filename>native</filename></link>,
2219 <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>,
2220 and so forth) set the variable to appropriate values.
2221 <note>
2222 <filename>CLASSOVERRIDE</filename> gets its default
2223 "class-target" value from the
2224 <filename>bitbake.conf</filename> file.
2225 </note>
2226 </para>
2227
2228 <para>
2229 As an example, the following override allows you to install
2230 extra files, but only when building for the target:
2231 <literallayout class='monospaced'>
2232 do_install_append_class-target() {
2233 install my-extra-file ${D}${sysconfdir}
2234 }
2235 </literallayout>
2236 Here is an example where <filename>FOO</filename>
2237 is set to "native" when building for the build host, and
2238 to "other" when not building for the build host:
2239 <literallayout class='monospaced'>
2240 FOO_class-native = "native"
2241 FOO = "other"
2242 </literallayout>
2243 The underlying mechanism behind
2244 <filename>CLASSOVERRIDE</filename> is simply that it is
2245 included in the default value of
2246 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
2247 </para>
2248 </glossdef>
2249 </glossentry>
2250
2251 <glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm>
2252 <info>
2253 CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task."
2254 </info>
2255 <glossdef>
2256 <para role="glossdeffirst">
2257 If set to "1" within a recipe,
2258 <filename>CLEANBROKEN</filename> specifies that
2259 the <filename>make clean</filename> command does
2260 not work for the software being built.
2261 Consequently, the OpenEmbedded build system will not try
2262 to run <filename>make clean</filename> during the
2263 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2264 task, which is the default behavior.
2265 </para>
2266 </glossdef>
2267 </glossentry>
2268
2269 <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
2270 <info>
2271 COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES."
2272 </info>
2273 <glossdef>
2274 <para role="glossdeffirst">
2275 Provides a list of hardware features that are enabled in
2276 both
2277 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
2278 and
2279 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2280 This select list of features contains features that make
2281 sense to be controlled both at the machine and distribution
2282 configuration level.
2283 For example, the "bluetooth" feature requires hardware
2284 support but should also be optional at the distribution
2285 level, in case the hardware supports Bluetooth but you
2286 do not ever intend to use it.
2287 </para>
2288 </glossdef>
2289 </glossentry>
2290
2291 <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
2292 <info>
2293 COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside."
2294 </info>
2295 <glossdef>
2296 <para role="glossdeffirst">
2297 Points to <filename>meta/files/common-licenses</filename>
2298 in the
2299 <link linkend='source-directory'>Source Directory</link>,
2300 which is where generic license files reside.
2301 </para>
2302 </glossdef>
2303 </glossentry>
2304
2305 <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
2306 <info>
2307 COMPATIBLE_HOST[doc] = "A regular expression that resolves to one or more hosts (when the recipe is native) or one or more targets (when the recipe is non-native) with which a recipe is compatible."
2308 </info>
2309 <glossdef>
2310 <para role="glossdeffirst">
2311 A regular expression that resolves to one or more hosts
2312 (when the recipe is native) or one or more targets (when
2313 the recipe is non-native) with which a recipe is compatible.
2314 The regular expression is matched against
2315 <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
2316 You can use the variable to stop recipes from being built
2317 for classes of systems with which the recipes are not
2318 compatible.
2319 Stopping these builds is particularly useful with kernels.
2320 The variable also helps to increase parsing speed
2321 since the build system skips parsing recipes not
2322 compatible with the current system.
2323 </para>
2324 </glossdef>
2325 </glossentry>
2326
2327 <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
2328 <info>
2329 COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible."
2330 </info>
2331 <glossdef>
2332 <para role="glossdeffirst">
2333 A regular expression that resolves to one or more
2334 target machines with which a recipe is compatible.
2335 The regular expression is matched against
2336 <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
2337 You can use the variable to stop recipes from being built
2338 for machines with which the recipes are not compatible.
2339 Stopping these builds is particularly useful with kernels.
2340 The variable also helps to increase parsing speed
2341 since the build system skips parsing recipes not
2342 compatible with the current machine.
2343 </para>
2344 </glossdef>
2345 </glossentry>
2346
2347 <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
2348 <info>
2349 COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image."
2350 </info>
2351 <glossdef>
2352 <para role="glossdeffirst">
2353 Defines wildcards to match when installing a list of
2354 complementary packages for all the packages explicitly
2355 (or implicitly) installed in an image.
2356 <note>
2357 The <filename>COMPLEMENTARY_GLOB</filename> variable
2358 uses Unix filename pattern matching
2359 (<ulink url='https://docs.python.org/2/library/fnmatch.html#module-fnmatch'><filename>fnmatch</filename></ulink>),
2360 which is similar to the Unix style pathname pattern
2361 expansion
2362 (<ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>).
2363 </note>
2364 The resulting list of complementary packages is associated
2365 with an item that can be added to
2366 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
2367 An example usage of this is the "dev-pkgs" item that when
2368 added to <filename>IMAGE_FEATURES</filename> will
2369 install -dev packages (containing headers and other
2370 development files) for every package in the image.
2371 </para>
2372
2373 <para>
2374 To add a new feature item pointing to a wildcard, use a
2375 variable flag to specify the feature item name and
2376 use the value to specify the wildcard.
2377 Here is an example:
2378 <literallayout class='monospaced'>
2379 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
2380 </literallayout>
2381 </para>
2382 </glossdef>
2383 </glossentry>
2384
2385 <glossentry id='var-COMPONENTS_DIR'><glossterm>COMPONENTS_DIR</glossterm>
2386 <info>
2387 COMPONENTS_DIR[doc] = "Stores sysroot components for each recipe."
2388 </info>
2389 <glossdef>
2390 <para role="glossdeffirst">
2391 Stores sysroot components for each recipe.
2392 The OpenEmbedded build system uses
2393 <filename>COMPONENTS_DIR</filename> when constructing
2394 recipe-specific sysroots for other recipes.
2395 </para>
2396
2397 <para>
2398 The default is
2399 "<filename>${</filename><link linkend='var-STAGING_DIR'><filename>STAGING_DIR</filename></link><filename>}-components</filename>."
2400 (i.e. "<filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots-components</filename>").
2401 </para>
2402 </glossdef>
2403 </glossentry>
2404
2405 <glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm>
2406 <info>
2407 CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly."
2408 </info>
2409 <glossdef>
2410 <para role="glossdeffirst">
2411 Tracks the version of the local configuration file
2412 (i.e. <filename>local.conf</filename>).
2413 The value for <filename>CONF_VERSION</filename>
2414 increments each time <filename>build/conf/</filename>
2415 compatibility changes.
2416 </para>
2417 </glossdef>
2418 </glossentry>
2419
2420 <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
2421 <info>
2422 CONFFILES[doc] = "Identifies editable or configurable files that are part of a package."
2423 </info>
2424 <glossdef>
2425 <para role="glossdeffirst">
2426 Identifies editable or configurable files that are part of a package.
2427 If the Package Management System (PMS) is being used to update
2428 packages on the target system, it is possible that
2429 configuration files you have changed after the original installation
2430 and that you now want to remain unchanged are overwritten.
2431 In other words, editable files might exist in the package that you do not
2432 want reset as part of the package update process.
2433 You can use the <filename>CONFFILES</filename> variable to list the files in the
2434 package that you wish to prevent the PMS from overwriting during this update process.
2435 </para>
2436
2437 <para>
2438 To use the <filename>CONFFILES</filename> variable, provide a package name
2439 override that identifies the resulting package.
2440 Then, provide a space-separated list of files.
2441 Here is an example:
2442 <literallayout class='monospaced'>
2443 CONFFILES_${PN} += "${sysconfdir}/file1 \
2444 ${sysconfdir}/file2 ${sysconfdir}/file3"
2445 </literallayout>
2446 </para>
2447
2448 <para>
2449 A relationship exists between the <filename>CONFFILES</filename> and
2450 <filename><link linkend='var-FILES'>FILES</link></filename> variables.
2451 The files listed within <filename>CONFFILES</filename> must be a subset of
2452 the files listed within <filename>FILES</filename>.
2453 Because the configuration files you provide with <filename>CONFFILES</filename>
2454 are simply being identified so that the PMS will not overwrite them,
2455 it makes sense that
2456 the files must already be included as part of the package through the
2457 <filename>FILES</filename> variable.
2458 </para>
2459
2460 <note>
2461 When specifying paths as part of the <filename>CONFFILES</filename> variable,
2462 it is good practice to use appropriate path variables.
2463 For example, <filename>${sysconfdir}</filename> rather than
2464 <filename>/etc</filename> or <filename>${bindir}</filename> rather
2465 than <filename>/usr/bin</filename>.
2466 You can find a list of these variables at the top of the
2467 <filename>meta/conf/bitbake.conf</filename> file in the
2468 <link linkend='source-directory'>Source Directory</link>.
2469 </note>
2470 </glossdef>
2471 </glossentry>
2472
2473 <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm>
2474 <info>
2475 CONFIG_INITRAMFS_SOURCE[doc] = "Identifies the initial RAM filesystem (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable."
2476 </info>
2477 <glossdef>
2478 <para role="glossdeffirst">
2479 Identifies the initial RAM filesystem (initramfs) source
2480 files.
2481 The OpenEmbedded build system receives and uses
2482 this kernel Kconfig variable as an environment variable.
2483 By default, the variable is set to null ("").
2484 </para>
2485
2486 <para>
2487 The <filename>CONFIG_INITRAMFS_SOURCE</filename> can be
2488 either a single cpio archive with a
2489 <filename>.cpio</filename> suffix or a
2490 space-separated list of directories and files for building
2491 the initramfs image.
2492 A cpio archive should contain a filesystem archive
2493 to be used as an initramfs image.
2494 Directories should contain a filesystem layout to be
2495 included in the initramfs image.
2496 Files should contain entries according to the format
2497 described by the
2498 <filename>usr/gen_init_cpio</filename> program in the
2499 kernel tree.
2500 </para>
2501
2502 <para>
2503 If you specify multiple directories and files, the
2504 initramfs image will be the aggregate of all of them.
2505 </para>
2506
2507 <para>
2508 For information on creating an initramfs, see the
2509 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
2510 section in the Yocto Project Development Tasks Manual.
2511 </para>
2512 </glossdef>
2513 </glossentry>
2514
2515 <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
2516 <info>
2517 CONFIG_SITE[doc] = "A list of files that contains autoconf test results relevant to the current build. This variable is used by the Autotools utilities when running configure."
2518 </info>
2519 <glossdef>
2520 <para role="glossdeffirst">
2521 A list of files that contains <filename>autoconf</filename> test results relevant
2522 to the current build.
2523 This variable is used by the Autotools utilities when running
2524 <filename>configure</filename>.
2525 </para>
2526 </glossdef>
2527 </glossentry>
2528
2529 <glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm>
2530 <info>
2531 CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure."
2532 </info>
2533 <glossdef>
2534 <para role="glossdeffirst">
2535 The minimal arguments for GNU configure.
2536 </para>
2537 </glossdef>
2538 </glossentry>
2539
2540 <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm>
2541 <info>
2542 CONFLICT_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that would be in conflict should the recipe be built."
2543 </info>
2544 <glossdef>
2545 <para role="glossdeffirst">
2546 When inheriting the
2547 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
2548 class, this
2549 variable identifies distribution features that would
2550 be in conflict should the recipe
2551 be built.
2552 In other words, if the
2553 <filename>CONFLICT_DISTRO_FEATURES</filename> variable
2554 lists a feature that also appears in
2555 <filename>DISTRO_FEATURES</filename> within the
2556 current configuration, an error occurs and the
2557 build stops.
2558 </para>
2559 </glossdef>
2560 </glossentry>
2561
2562 <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm>
2563 <info>
2564 COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class."
2565 </info>
2566 <glossdef>
2567 <para role="glossdeffirst">
2568 A space-separated list of licenses to exclude from the
2569 source archived by the
2570 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2571 class.
2572 In other words, if a license in a recipe's
2573 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2574 value is in the value of
2575 <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its
2576 source is not archived by the class.
2577 <note>
2578 The <filename>COPYLEFT_LICENSE_EXCLUDE</filename>
2579 variable takes precedence over the
2580 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2581 variable.
2582 </note>
2583 The default value, which is "CLOSED Proprietary", for
2584 <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set
2585 by the
2586 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2587 class, which is inherited by the
2588 <filename>archiver</filename> class.
2589 </para>
2590 </glossdef>
2591 </glossentry>
2592
2593 <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm>
2594 <info>
2595 COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class."
2596 </info>
2597 <glossdef>
2598 <para role="glossdeffirst">
2599 A space-separated list of licenses to include in the
2600 source archived by the
2601 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2602 class.
2603 In other words, if a license in a recipe's
2604 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
2605 value is in the value of
2606 <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its
2607 source is archived by the class.
2608 </para>
2609
2610 <para>
2611 The default value is set by the
2612 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2613 class, which is inherited by the
2614 <filename>archiver</filename> class.
2615 The default value includes "GPL*", "LGPL*", and "AGPL*".
2616 </para>
2617 </glossdef>
2618 </glossentry>
2619
2620 <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm>
2621 <info>
2622 COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class."
2623 </info>
2624 <glossdef>
2625 <para role="glossdeffirst">
2626 A list of recipes to exclude in the source archived
2627 by the
2628 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2629 class.
2630 The <filename>COPYLEFT_PN_EXCLUDE</filename> variable
2631 overrides the license inclusion and exclusion caused
2632 through the
2633 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2634 and
2635 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2636 variables, respectively.
2637 </para>
2638
2639 <para>
2640 The default value, which is "" indicating to not explicitly
2641 exclude any recipes by name, for
2642 <filename>COPYLEFT_PN_EXCLUDE</filename> is set
2643 by the
2644 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2645 class, which is inherited by the
2646 <filename>archiver</filename> class.
2647 </para>
2648 </glossdef>
2649 </glossentry>
2650
2651 <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm>
2652 <info>
2653 COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class."
2654 </info>
2655 <glossdef>
2656 <para role="glossdeffirst">
2657 A list of recipes to include in the source archived
2658 by the
2659 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2660 class.
2661 The <filename>COPYLEFT_PN_INCLUDE</filename> variable
2662 overrides the license inclusion and exclusion caused
2663 through the
2664 <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link>
2665 and
2666 <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link>
2667 variables, respectively.
2668 </para>
2669
2670 <para>
2671 The default value, which is "" indicating to not explicitly
2672 include any recipes by name, for
2673 <filename>COPYLEFT_PN_INCLUDE</filename> is set
2674 by the
2675 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2676 class, which is inherited by the
2677 <filename>archiver</filename> class.
2678 </para>
2679 </glossdef>
2680 </glossentry>
2681
2682 <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm>
2683 <info>
2684 COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class."
2685 </info>
2686 <glossdef>
2687 <para role="glossdeffirst">
2688 A space-separated list of recipe types to include
2689 in the source archived by the
2690 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
2691 class.
2692 Recipe types are <filename>target</filename>,
2693 <filename>native</filename>,
2694 <filename>nativesdk</filename>,
2695 <filename>cross</filename>,
2696 <filename>crosssdk</filename>, and
2697 <filename>cross-canadian</filename>.
2698 </para>
2699
2700 <para>
2701 The default value, which is "target*", for
2702 <filename>COPYLEFT_RECIPE_TYPES</filename> is set
2703 by the
2704 <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link>
2705 class, which is inherited by the
2706 <filename>archiver</filename> class.
2707 </para>
2708 </glossdef>
2709 </glossentry>
2710
2711 <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm>
2712 <info>
2713 COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package."
2714 </info>
2715 <glossdef>
2716 <para role="glossdeffirst">
2717 If set to "1" along with the
2718 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
2719 variable, the OpenEmbedded build system copies
2720 into the image the license files, which are located in
2721 <filename>/usr/share/common-licenses</filename>,
2722 for each package.
2723 The license files are placed
2724 in directories within the image itself during build time.
2725 <note>
2726 The <filename>COPY_LIC_DIRS</filename> does not
2727 offer a path for adding licenses for newly installed
2728 packages to an image, which might be most suitable
2729 for read-only filesystems that cannot be upgraded.
2730 See the
2731 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2732 variable for additional information.
2733 You can also reference the
2734 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
2735 section in the Yocto Project Development Tasks Manual
2736 for information on providing license text.
2737 </note>
2738 </para>
2739 </glossdef>
2740 </glossentry>
2741
2742 <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm>
2743 <info>
2744 COPY_LIC_MANIFEST[doc] = "If set to "1", the OpenEmbedded build system copies the license manifest for the image to /usr/share/common-licenses/license.manifest within the image itself."
2745 </info>
2746 <glossdef>
2747 <para role="glossdeffirst">
2748 If set to "1", the OpenEmbedded build system copies
2749 the license manifest for the image to
2750 <filename>/usr/share/common-licenses/license.manifest</filename>
2751 within the image itself during build time.
2752 <note>
2753 The <filename>COPY_LIC_MANIFEST</filename> does not
2754 offer a path for adding licenses for newly installed
2755 packages to an image, which might be most suitable
2756 for read-only filesystems that cannot be upgraded.
2757 See the
2758 <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link>
2759 variable for additional information.
2760 You can also reference the
2761 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
2762 section in the Yocto Project Development Tasks Manual
2763 for information on providing license text.
2764 </note>
2765 </para>
2766 </glossdef>
2767 </glossentry>
2768
2769 <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
2770 <info>
2771 CORE_IMAGE_EXTRA_INSTALL[doc] = "Specifies the list of packages to be added to the image. You should only set this variable in the conf/local.conf file in the Build Directory."
2772 </info>
2773 <glossdef>
2774 <para role="glossdeffirst">
2775 Specifies the list of packages to be added to the image.
2776 You should only set this variable in the
2777 <filename>local.conf</filename> configuration file found
2778 in the
2779 <link linkend='build-directory'>Build Directory</link>.
2780 </para>
2781
2782 <para>
2783 This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
2784 </para>
2785 </glossdef>
2786 </glossentry>
2787
2788 <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
2789 <info>
2790 COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded-Core Metadata layer (i.e. meta)."
2791 </info>
2792 <glossdef>
2793 <para role="glossdeffirst">
2794 Specifies the parent directory of the OpenEmbedded-Core
2795 Metadata layer (i.e. <filename>meta</filename>).
2796 </para>
2797
2798 <para>
2799 It is an important distinction that
2800 <filename>COREBASE</filename> points to the parent of this
2801 layer and not the layer itself.
2802 Consider an example where you have cloned the Poky Git
2803 repository and retained the <filename>poky</filename>
2804 name for your local copy of the repository.
2805 In this case, <filename>COREBASE</filename> points to
2806 the <filename>poky</filename> folder because it is the
2807 parent directory of the <filename>poky/meta</filename>
2808 layer.
2809 </para>
2810 </glossdef>
2811 </glossentry>
2812
2813 <glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm>
2814 <info>
2815 COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file."
2816 </info>
2817 <glossdef>
2818 <para role="glossdeffirst">
2819 Lists files from the
2820 <link linkend='var-COREBASE'><filename>COREBASE</filename></link>
2821 directory that should be copied other than the layers
2822 listed in the <filename>bblayers.conf</filename> file.
2823 The <filename>COREBASE_FILES</filename> variable exists
2824 for the purpose of copying metadata from the
2825 OpenEmbedded build system into the extensible
2826 SDK.
2827 </para>
2828
2829 <para>
2830 Explicitly listing files in <filename>COREBASE</filename>
2831 is needed because it typically contains build
2832 directories and other files that should not normally
2833 be copied into the extensible SDK.
2834 Consequently, the value of
2835 <filename>COREBASE_FILES</filename> is used in order to
2836 only copy the files that are actually needed.
2837 </para>
2838 </glossdef>
2839 </glossentry>
2840
2841 <glossentry id='var-CPP'><glossterm>CPP</glossterm>
2842 <info>
2843 CPP[doc] = "Minimum command and arguments to run the C preprocessor."
2844 </info>
2845 <glossdef>
2846 <para role="glossdeffirst">
2847 The minimal command and arguments used to run the C
2848 preprocessor.
2849 </para>
2850 </glossdef>
2851 </glossentry>
2852
2853 <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm>
2854 <info>
2855 CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)."
2856 </info>
2857 <glossdef>
2858 <para role="glossdeffirst">
2859 Specifies the flags to pass to the C pre-processor
2860 (i.e. to both the C and the C++ compilers).
2861 This variable is exported to an environment
2862 variable and thus made visible to the software being
2863 built during the compilation step.
2864 </para>
2865
2866 <para>
2867 Default initialization for <filename>CPPFLAGS</filename>
2868 varies depending on what is being built:
2869 <itemizedlist>
2870 <listitem><para>
2871 <link linkend='var-TARGET_CPPFLAGS'><filename>TARGET_CPPFLAGS</filename></link>
2872 when building for the target
2873 </para></listitem>
2874 <listitem><para>
2875 <link linkend='var-BUILD_CPPFLAGS'><filename>BUILD_CPPFLAGS</filename></link>
2876 when building for the build host (i.e.
2877 <filename>-native</filename>)
2878 </para></listitem>
2879 <listitem><para>
2880 <link linkend='var-BUILDSDK_CPPFLAGS'><filename>BUILDSDK_CPPFLAGS</filename></link>
2881 when building for an SDK (i.e.
2882 <filename>nativesdk-</filename>)
2883 </para></listitem>
2884 </itemizedlist>
2885 </para>
2886 </glossdef>
2887 </glossentry>
2888
2889 <glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm>
2890 <info>
2891 CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools."
2892 </info>
2893 <glossdef>
2894 <para role="glossdeffirst">
2895 The toolchain binary prefix for the target tools.
2896 The <filename>CROSS_COMPILE</filename> variable is the
2897 same as the
2898 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
2899 variable.
2900 <note>
2901 The OpenEmbedded build system sets the
2902 <filename>CROSS_COMPILE</filename> variable only in
2903 certain contexts (e.g. when building for kernel
2904 and kernel module recipes).
2905 </note>
2906 </para>
2907 </glossdef>
2908 </glossentry>
2909
2910 <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm>
2911 <info>
2912 CVSDIR[doc] = "The directory where cvs checkouts will be stored in."
2913 </info>
2914 <glossdef>
2915 <para role="glossdeffirst">
2916 The directory in which files checked out under the
2917 CVS system are stored.
2918 </para>
2919 </glossdef>
2920 </glossentry>
2921
2922 <glossentry id='var-CXX'><glossterm>CXX</glossterm>
2923 <info>
2924 CXX[doc] = "Minimum command and arguments to run the C++ compiler."
2925 </info>
2926 <glossdef>
2927 <para role="glossdeffirst">
2928 The minimal command and arguments used to run the C++
2929 compiler.
2930 </para>
2931 </glossdef>
2932 </glossentry>
2933
2934 <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm>
2935 <info>
2936 CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler."
2937 </info>
2938 <glossdef>
2939 <para role="glossdeffirst">
2940 Specifies the flags to pass to the C++ compiler.
2941 This variable is exported to an environment
2942 variable and thus made visible to the software being
2943 built during the compilation step.
2944 </para>
2945
2946 <para>
2947 Default initialization for <filename>CXXFLAGS</filename>
2948 varies depending on what is being built:
2949 <itemizedlist>
2950 <listitem><para>
2951 <link linkend='var-TARGET_CXXFLAGS'><filename>TARGET_CXXFLAGS</filename></link>
2952 when building for the target
2953 </para></listitem>
2954 <listitem><para>
2955 <link linkend='var-BUILD_CXXFLAGS'><filename>BUILD_CXXFLAGS</filename></link>
2956 when building for the build host (i.e.
2957 <filename>-native</filename>)
2958 </para></listitem>
2959 <listitem><para>
2960 <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link>
2961 when building for an SDK (i.e.
2962 <filename>nativesdk-</filename>)
2963 </para></listitem>
2964 </itemizedlist>
2965 </para>
2966 </glossdef>
2967 </glossentry>
2968
2969 </glossdiv>
2970
2971 <glossdiv id='var-glossary-d'><title>D</title>
2972
2973 <glossentry id='var-D'><glossterm>D</glossterm>
2974 <info>
2975 D[doc] = "The destination directory."
2976 </info>
2977 <glossdef>
2978 <para role="glossdeffirst">
2979 The destination directory.
2980 The location in the
2981 <link linkend='build-directory'>Build Directory</link>
2982 where components are installed by the
2983 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2984 task.
2985 This location defaults to:
2986 <literallayout class='monospaced'>
2987 ${WORKDIR}/image
2988 </literallayout>
2989 <note><title>Caution</title>
2990 Tasks that read from or write to this directory should
2991 run under
2992 <ulink url='&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo'>fakeroot</ulink>.
2993 </note>
2994 </para>
2995 </glossdef>
2996 </glossentry>
2997
2998 <glossentry id='var-DATE'><glossterm>DATE</glossterm>
2999 <info>
3000 DATE[doc] = "The date the build was started using YMD format."
3001 </info>
3002 <glossdef>
3003 <para role="glossdeffirst">
3004 The date the build was started.
3005 Dates appear using the year, month, and day (YMD) format
3006 (e.g. "20150209" for February 9th, 2015).
3007 </para>
3008 </glossdef>
3009 </glossentry>
3010
3011 <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
3012 <info>
3013 DATETIME[doc] = "The date and time the build was started."
3014 </info>
3015 <glossdef>
3016 <para role="glossdeffirst">
3017 The date and time on which the current build started.
3018 The format is suitable for timestamps.
3019 </para>
3020 </glossdef>
3021 </glossentry>
3022
3023 <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm>
3024 <info>
3025 DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming."
3026 </info>
3027 <glossdef>
3028 <para role="glossdeffirst">
3029 When the
3030 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3031 class is inherited, which is the default behavior,
3032 <filename>DEBIAN_NOAUTONAME</filename> specifies a
3033 particular package should not be renamed according to
3034 Debian library package naming.
3035 You must use the package name as an override when you
3036 set this variable.
3037 Here is an example from the <filename>fontconfig</filename>
3038 recipe:
3039 <literallayout class='monospaced'>
3040 DEBIAN_NOAUTONAME_fontconfig-utils = "1"
3041 </literallayout>
3042 </para>
3043 </glossdef>
3044 </glossentry>
3045
3046 <glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm>
3047 <info>
3048 DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming."
3049 </info>
3050 <glossdef>
3051 <para role="glossdeffirst">
3052 When the
3053 <link linkend='ref-classes-debian'><filename>debian</filename></link>
3054 class is inherited, which is the default behavior,
3055 <filename>DEBIANNAME</filename> allows you to override the
3056 library name for an individual package.
3057 Overriding the library name in these cases is rare.
3058 You must use the package name as an override when you
3059 set this variable.
3060 Here is an example from the <filename>dbus</filename>
3061 recipe:
3062 <literallayout class='monospaced'>
3063 DEBIANNAME_${PN} = "dbus-1"
3064 </literallayout>
3065 </para>
3066 </glossdef>
3067 </glossentry>
3068
3069 <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
3070 <info>
3071 DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable."
3072 </info>
3073 <glossdef>
3074 <para role="glossdeffirst">
3075 Specifies to build packages with debugging information.
3076 This influences the value of the
3077 <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
3078 variable.
3079 </para>
3080 </glossdef>
3081 </glossentry>
3082
3083 <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
3084 <info>
3085 DEBUG_OPTIMIZATION[doc] = "The options to pass in TARGET_CFLAGS and CFLAGS when compiling a system for debugging. This variable defaults to '-O -fno-omit-frame-pointer -g'."
3086 </info>
3087 <glossdef>
3088 <para role="glossdeffirst">
3089 The options to pass in
3090 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
3091 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
3092 a system for debugging.
3093 This variable defaults to "-O -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
3094 </para>
3095 </glossdef>
3096 </glossentry>
3097
3098 <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
3099 <info>
3100 DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority."
3101 </info>
3102 <glossdef>
3103 <para role="glossdeffirst">
3104 Specifies a weak bias for recipe selection priority.
3105 </para>
3106
3107 <para>
3108 The most common usage of this is variable is to set
3109 it to "-1" within a recipe for a development version of a
3110 piece of software.
3111 Using the variable in this way causes the stable version
3112 of the recipe to build by default in the absence of
3113 <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
3114 being used to build the development version.
3115 </para>
3116
3117 <note>
3118 The bias provided by <filename>DEFAULT_PREFERENCE</filename>
3119 is weak and is overridden by
3120 <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
3121 if that variable is different between two layers
3122 that contain different versions of the same recipe.
3123 </note>
3124 </glossdef>
3125 </glossentry>
3126
3127 <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm>
3128 <info>
3129 DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system."
3130 </info>
3131 <glossdef>
3132 <para role="glossdeffirst">
3133 The default CPU and Application Binary Interface (ABI)
3134 tunings (i.e. the "tune") used by the OpenEmbedded build
3135 system.
3136 The <filename>DEFAULTTUNE</filename> helps define
3137 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
3138 </para>
3139
3140 <para>
3141 The default tune is either implicitly or explicitly set
3142 by the machine
3143 (<link linkend='var-MACHINE'><filename>MACHINE</filename></link>).
3144 However, you can override the setting using available tunes
3145 as defined with
3146 <link linkend='var-AVAILTUNES'><filename>AVAILTUNES</filename></link>.
3147 </para>
3148 </glossdef>
3149 </glossentry>
3150
3151 <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
3152 <info>
3153 DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)."
3154 </info>
3155 <glossdef>
3156 <para role="glossdeffirst">
3157 Lists a recipe's build-time dependencies.
3158 These are dependencies on other recipes whose
3159 contents (e.g. headers and shared libraries) are needed
3160 by the recipe at build time.
3161 </para>
3162
3163 <para>
3164 As an example, consider a recipe <filename>foo</filename>
3165 that contains the following assignment:
3166 <literallayout class='monospaced'>
3167 DEPENDS = "bar"
3168 </literallayout>
3169 The practical effect of the previous assignment is that
3170 all files installed by bar will be available in the
3171 appropriate staging sysroot, given by the
3172 <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link>
3173 variables, by the time the
3174 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3175 task for <filename>foo</filename> runs.
3176 This mechanism is implemented by having
3177 <filename>do_configure</filename> depend on the
3178 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
3179 task of each recipe listed in <filename>DEPENDS</filename>,
3180 through a
3181 <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename>
3182 declaration in the
3183 <link linkend='ref-classes-base'><filename>base</filename></link>
3184 class.
3185 <note>
3186 It seldom is necessary to reference, for example,
3187 <filename>STAGING_DIR_HOST</filename> explicitly.
3188 The standard classes and build-related variables are
3189 configured to automatically use the appropriate staging
3190 sysroots.
3191 </note>
3192 As another example, <filename>DEPENDS</filename> can also
3193 be used to add utilities that run on the build machine
3194 during the build.
3195 For example, a recipe that makes use of a code generator
3196 built by the recipe <filename>codegen</filename> might have
3197 the following:
3198 <literallayout class='monospaced'>
3199 DEPENDS = "codegen-native"
3200 </literallayout>
3201 For more information, see the
3202 <link linkend='ref-classes-native'><filename>native</filename></link>
3203 class and the
3204 <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link>
3205 variable.
3206 <note>
3207 <title>Notes</title>
3208 <itemizedlist>
3209 <listitem><para>
3210 <filename>DEPENDS</filename> is a list of
3211 recipe names.
3212 Or, to be more precise, it is a list of
3213 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
3214 names, which usually match recipe names.
3215 Putting a package name such as "foo-dev" in
3216 <filename>DEPENDS</filename> does not make
3217 sense.
3218 Use "foo" instead, as this will put files
3219 from all the packages that make up
3220 <filename>foo</filename>, which includes
3221 those from <filename>foo-dev</filename>, into
3222 the sysroot.
3223 </para></listitem>
3224 <listitem><para>
3225 One recipe having another recipe in
3226 <filename>DEPENDS</filename> does not by itself
3227 add any runtime dependencies between the
3228 packages produced by the two recipes.
3229 However, as explained in the
3230 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
3231 section in the Yocto Project Overview and
3232 Concepts Manual, runtime dependencies will
3233 often be added automatically, meaning
3234 <filename>DEPENDS</filename> alone is
3235 sufficient for most recipes.
3236 </para></listitem>
3237 <listitem><para>
3238 Counterintuitively,
3239 <filename>DEPENDS</filename> is often necessary
3240 even for recipes that install precompiled
3241 components.
3242 For example, if <filename>libfoo</filename>
3243 is a precompiled library that links against
3244 <filename>libbar</filename>, then
3245 linking against <filename>libfoo</filename>
3246 requires both <filename>libfoo</filename>
3247 and <filename>libbar</filename> to be available
3248 in the sysroot.
3249 Without a <filename>DEPENDS</filename> from the
3250 recipe that installs <filename>libfoo</filename>
3251 to the recipe that installs
3252 <filename>libbar</filename>, other recipes might
3253 fail to link against
3254 <filename>libfoo</filename>.
3255 </para></listitem>
3256 </itemizedlist>
3257 </note>
3258 </para>
3259
3260 <para>
3261 For information on runtime dependencies, see the
3262 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
3263 variable.
3264 You can also see the
3265 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
3266 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
3267 sections in the BitBake User Manual for additional
3268 information on tasks and dependencies.
3269 </para>
3270 </glossdef>
3271 </glossentry>
3272
3273 <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
3274 <info>
3275 DEPLOY_DIR[doc] = "Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3276 </info>
3277 <glossdef>
3278 <para role="glossdeffirst">
3279 Points to the general area that the OpenEmbedded build
3280 system uses to place images, packages, SDKs, and other output
3281 files that are ready to be used outside of the build system.
3282 By default, this directory resides within the
3283 <link linkend='build-directory'>Build Directory</link>
3284 as <filename>${TMPDIR}/deploy</filename>.
3285 </para>
3286
3287 <para>
3288 For more information on the structure of the Build
3289 Directory, see
3290 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3291 section.
3292 For more detail on the contents of the
3293 <filename>deploy</filename> directory, see the
3294 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>",
3295 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>",
3296 and
3297 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3298 sections all in the Yocto Project Overview and Concepts
3299 Manual.
3300 </para>
3301 </glossdef>
3302 </glossentry>
3303
3304 <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm>
3305 <info>
3306 DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3307 </info>
3308 <glossdef>
3309 <para role="glossdeffirst">
3310 Points to the area that the OpenEmbedded build system uses
3311 to place Debian packages that are ready to be used outside
3312 of the build system.
3313 This variable applies only when
3314 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3315 contains "package_deb".
3316 </para>
3317
3318 <para>
3319 The BitBake configuration file initially defines the
3320 <filename>DEPLOY_DIR_DEB</filename> variable as a
3321 sub-folder of
3322 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3323 <literallayout class='monospaced'>
3324 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
3325 </literallayout>
3326 </para>
3327
3328 <para>
3329 The
3330 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>
3331 class uses the
3332 <filename>DEPLOY_DIR_DEB</filename> variable to make sure
3333 the
3334 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>
3335 task writes Debian packages into the appropriate folder.
3336 For more information on how packaging works, see the
3337 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3338 section in the Yocto Project Overview and Concepts Manual.
3339 </para>
3340 </glossdef>
3341 </glossentry>
3342
3343 <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
3344 <info>
3345 DEPLOY_DIR_IMAGE[doc] = "Points to the area that the OpenEmbedded build system uses to place images and other associated output files that are ready to be deployed onto the target machine."
3346 </info>
3347 <glossdef>
3348 <para role="glossdeffirst">
3349 Points to the area that the OpenEmbedded build system uses
3350 to place images and other associated output files that are
3351 ready to be deployed onto the target machine.
3352 The directory is machine-specific as it contains the
3353 <filename>${MACHINE}</filename> name.
3354 By default, this directory resides within the
3355 <link linkend='build-directory'>Build Directory</link>
3356 as <filename>${DEPLOY_DIR}/images/${MACHINE}/</filename>.
3357 </para>
3358
3359 <para>
3360 For more information on the structure of the Build
3361 Directory, see
3362 "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
3363 section.
3364 For more detail on the contents of the
3365 <filename>deploy</filename> directory, see the
3366 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
3367 and
3368 "<ulink url='&YOCTO_DOCS_OM_URL;#sdk-dev-environment'>Application Development SDK</ulink>"
3369 sections both in the Yocto Project Overview and Concepts
3370 Manual.
3371 </para>
3372 </glossdef>
3373 </glossentry>
3374
3375 <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm>
3376 <info>
3377 DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3378 </info>
3379 <glossdef>
3380 <para role="glossdeffirst">
3381 Points to the area that the OpenEmbedded build system uses
3382 to place IPK packages that are ready to be used outside of
3383 the build system.
3384 This variable applies only when
3385 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3386 contains "package_ipk".
3387 </para>
3388
3389 <para>
3390 The BitBake configuration file initially defines this
3391 variable as a sub-folder of
3392 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3393 <literallayout class='monospaced'>
3394 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
3395 </literallayout>
3396 </para>
3397
3398 <para>
3399 The
3400 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>
3401 class uses the
3402 <filename>DEPLOY_DIR_IPK</filename> variable to make sure
3403 the
3404 <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link>
3405 task writes IPK packages into the appropriate folder.
3406 For more information on how packaging works, see the
3407 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3408 section in the Yocto Project Overview and Concepts Manual.
3409 </para>
3410 </glossdef>
3411 </glossentry>
3412
3413 <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm>
3414 <info>
3415 DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3416 </info>
3417 <glossdef>
3418 <para role="glossdeffirst">
3419 Points to the area that the OpenEmbedded build system uses
3420 to place RPM packages that are ready to be used outside
3421 of the build system.
3422 This variable applies only when
3423 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3424 contains "package_rpm".
3425 </para>
3426
3427 <para>
3428 The BitBake configuration file initially defines this
3429 variable as a sub-folder of
3430 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3431 <literallayout class='monospaced'>
3432 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
3433 </literallayout>
3434 </para>
3435
3436 <para>
3437 The
3438 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>
3439 class uses the
3440 <filename>DEPLOY_DIR_RPM</filename> variable to make sure
3441 the
3442 <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link>
3443 task writes RPM packages into the appropriate folder.
3444 For more information on how packaging works, see the
3445 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3446 section in the Yocto Project Overview and Concepts Manual.
3447 </para>
3448 </glossdef>
3449 </glossentry>
3450
3451 <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm>
3452 <info>
3453 DEPLOY_DIR_TAR[doc] = "Points to a tarball area that the OpenEmbedded build system uses to place images, packages, SDKs, and other output files that are ready to be used outside of the build system."
3454 </info>
3455 <glossdef>
3456 <para role="glossdeffirst">
3457 Points to the area that the OpenEmbedded build system uses
3458 to place tarballs that are ready to be used outside of
3459 the build system.
3460 This variable applies only when
3461 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3462 contains "package_tar".
3463 </para>
3464
3465 <para>
3466 The BitBake configuration file initially defines this
3467 variable as a sub-folder of
3468 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
3469 <literallayout class='monospaced'>
3470 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
3471 </literallayout>
3472 </para>
3473
3474 <para>
3475 The
3476 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
3477 class uses the
3478 <filename>DEPLOY_DIR_TAR</filename> variable to make sure
3479 the
3480 <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>
3481 task writes TAR packages into the appropriate folder.
3482 For more information on how packaging works, see the
3483 "<ulink url='&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment'>Package Feeds</ulink>"
3484 section in the Yocto Project Overview and Concepts Manual.
3485 </para>
3486 </glossdef>
3487 </glossentry>
3488
3489 <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm>
3490 <info>
3491 DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files."
3492 </info>
3493 <glossdef>
3494 <para role="glossdeffirst">
3495 When inheriting the
3496 <link linkend='ref-classes-deploy'><filename>deploy</filename></link>
3497 class, the <filename>DEPLOYDIR</filename> points to a
3498 temporary work area for deployed files that is set in the
3499 <filename>deploy</filename> class as follows:
3500 <literallayout class='monospaced'>
3501 DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}"
3502 </literallayout>
3503 </para>
3504
3505 <para>
3506 Recipes inheriting the <filename>deploy</filename> class
3507 should copy files to be deployed into
3508 <filename>DEPLOYDIR</filename>, and the class will take
3509 care of copying them into
3510 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
3511 afterwards.
3512 </para>
3513 </glossdef>
3514 </glossentry>
3515
3516 <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
3517 <info>
3518 DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable."
3519 </info>
3520 <glossdef>
3521 <para role="glossdeffirst">
3522 The package description used by package managers.
3523 If not set, <filename>DESCRIPTION</filename> takes
3524 the value of the
3525 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
3526 variable.
3527 </para>
3528 </glossdef>
3529 </glossentry>
3530
3531 <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
3532 <info>
3533 DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used."
3534 </info>
3535 <glossdef>
3536 <para role="glossdeffirst">
3537 The short name of the distribution.
3538 For information on the long name of the distribution, see
3539 the
3540 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
3541 variable.
3542 </para>
3543
3544 <para>
3545 The <filename>DISTRO</filename> variable corresponds to a
3546 distribution configuration file whose root name is the
3547 same as the variable's argument and whose filename
3548 extension is <filename>.conf</filename>.
3549 For example, the distribution configuration file for the
3550 Poky distribution is named <filename>poky.conf</filename>
3551 and resides in the
3552 <filename>meta-poky/conf/distro</filename> directory of
3553 the
3554 <link linkend='source-directory'>Source Directory</link>.
3555 </para>
3556
3557 <para>
3558 Within that <filename>poky.conf</filename> file, the
3559 <filename>DISTRO</filename> variable is set as follows:
3560 <literallayout class='monospaced'>
3561 DISTRO = "poky"
3562 </literallayout>
3563 </para>
3564
3565 <para>
3566 Distribution configuration files are located in a
3567 <filename>conf/distro</filename> directory within the
3568 <link linkend='metadata'>Metadata</link>
3569 that contains the distribution configuration.
3570 The value for <filename>DISTRO</filename> must not contain
3571 spaces, and is typically all lower-case.
3572 <note>
3573 If the <filename>DISTRO</filename> variable is blank,
3574 a set of default configurations are used, which are
3575 specified within
3576 <filename>meta/conf/distro/defaultsetup.conf</filename>
3577 also in the Source Directory.
3578 </note>
3579 </para>
3580 </glossdef>
3581 </glossentry>
3582
3583 <glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm>
3584 <info>
3585 DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built."
3586 </info>
3587 <glossdef>
3588 <para role="glossdeffirst">
3589 Specifies a codename for the distribution being built.
3590 </para>
3591 </glossdef>
3592 </glossentry>
3593
3594 <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
3595 <info>
3596 DISTRO_EXTRA_RDEPENDS[doc] = "Specifies a list of distro-specific packages to add to all images. The variable only applies to the images that include packagegroup-base."
3597 </info>
3598 <glossdef>
3599 <para role="glossdeffirst">
3600 Specifies a list of distro-specific packages to add to all images.
3601 This variable takes affect through
3602 <filename>packagegroup-base</filename> so the
3603 variable only really applies to the more full-featured
3604 images that include <filename>packagegroup-base</filename>.
3605 You can use this variable to keep distro policy out of
3606 generic images.
3607 As with all other distro variables, you set this variable
3608 in the distro <filename>.conf</filename> file.
3609 </para>
3610 </glossdef>
3611 </glossentry>
3612
3613 <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
3614 <info>
3615 DISTRO_EXTRA_RRECOMMENDS[doc] = "Specifies a list of distro-specific packages to add to all images if the packages exist. The list of packages are automatically installed but you can remove them."
3616 </info>
3617 <glossdef>
3618 <para role="glossdeffirst">
3619 Specifies a list of distro-specific packages to add to all images
3620 if the packages exist.
3621 The packages might not exist or be empty (e.g. kernel modules).
3622 The list of packages are automatically installed but you can
3623 remove them.
3624 </para>
3625 </glossdef>
3626 </glossentry>
3627
3628 <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
3629 <info>
3630 DISTRO_FEATURES[doc] = "The features enabled for the distribution."
3631 </info>
3632 <glossdef>
3633 <para role="glossdeffirst">
3634 The software support you want in your distribution for
3635 various features.
3636 You define your distribution features in the distribution
3637 configuration file.
3638 </para>
3639
3640 <para>
3641 In most cases, the presence or absence of a feature in
3642 <filename>DISTRO_FEATURES</filename> is translated to the
3643 appropriate option supplied to the configure script
3644 during the
3645 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3646 task for recipes that optionally support the feature.
3647 For example, specifying "x11" in
3648 <filename>DISTRO_FEATURES</filename>, causes
3649 every piece of software built for the target that can
3650 optionally support X11 to have its X11 support enabled.
3651 </para>
3652
3653 <para>
3654 Two more examples are Bluetooth and NFS support.
3655 For a more complete list of features that ships with the
3656 Yocto Project and that you can provide with this variable,
3657 see the
3658 "<link linkend='ref-features-distro'>Distro Features</link>"
3659 section.
3660 </para>
3661 </glossdef>
3662 </glossentry>
3663
3664 <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
3665 <info>
3666 DISTRO_FEATURES_BACKFILL[doc] = "Features to be added to DISTRO_FEATURES if not also present in DISTRO_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and it is not intended to be user-configurable."
3667 </info>
3668 <glossdef>
3669 <para role="glossdeffirst">
3670 Features to be added to
3671 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
3672 if not also present in
3673 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
3674 </para>
3675
3676 <para>
3677 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
3678 It is not intended to be user-configurable.
3679 It is best to just reference the variable to see which distro features are
3680 being backfilled for all distro configurations.
3681 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
3682 more information.
3683 </para>
3684 </glossdef>
3685 </glossentry>
3686
3687 <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
3688 <info>
3689 DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build."
3690 </info>
3691 <glossdef>
3692 <para role="glossdeffirst">
3693 Features from
3694 <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
3695 that should not be backfilled (i.e. added to
3696 <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
3697 during the build.
3698 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
3699 more information.
3700 </para>
3701 </glossdef>
3702 </glossentry>
3703
3704 <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm>
3705 <info>
3706 DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features."
3707 </info>
3708 <glossdef>
3709 <para role="glossdeffirst">
3710 A convenience variable that gives you the default
3711 list of distro features with the exception of any
3712 features specific to the C library
3713 (<filename>libc</filename>).
3714 </para>
3715
3716 <para>
3717 When creating a custom distribution, you might find it
3718 useful to be able to reuse the default
3719 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3720 options without the need to write out the full set.
3721 Here is an example that uses
3722 <filename>DISTRO_FEATURES_DEFAULT</filename> from a
3723 custom distro configuration file:
3724 <literallayout class='monospaced'>
3725 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
3726 </literallayout>
3727 </para>
3728 </glossdef>
3729 </glossentry>
3730
3731 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm>
3732 <info>
3733 DISTRO_FEATURES_FILTER_NATIVE[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building native recipes."
3734 </info>
3735 <glossdef>
3736 <para role="glossdeffirst">
3737 Specifies a list of features that if present in
3738 the target
3739 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3740 value should be included in
3741 <filename>DISTRO_FEATURES</filename> when building native
3742 recipes.
3743 This variable is used in addition to the features
3744 filtered using the
3745 <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link>
3746 variable.
3747 </para>
3748 </glossdef>
3749 </glossentry>
3750
3751 <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm>
3752 <info>
3753 DISTRO_FEATURES_FILTER_NATIVESDK[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building nativesdk recipes."
3754 </info>
3755 <glossdef>
3756 <para role="glossdeffirst">
3757 Specifies a list of features that if present in the target
3758 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3759 value should be included in
3760 <filename>DISTRO_FEATURES</filename> when building
3761 nativesdk recipes.
3762 This variable is used in addition to the features
3763 filtered using the
3764 <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link>
3765 variable.
3766 </para>
3767 </glossdef>
3768 </glossentry>
3769
3770<!--
3771 <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm>
3772 <info>
3773 DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)."
3774 </info>
3775 <glossdef>
3776 <para role="glossdeffirst">
3777 A convenience variable that specifies the list of distro
3778 features that are specific to the C library
3779 (<filename>libc</filename>).
3780 Typically, these features are prefixed with "libc-" and
3781 control which features are enabled at during the build
3782 within the C library itself.
3783 </para>
3784 </glossdef>
3785 </glossentry>
3786-->
3787
3788 <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm>
3789 <info>
3790 DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes."
3791 </info>
3792 <glossdef>
3793 <para role="glossdeffirst">
3794 Specifies a list of features that should be included in
3795 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3796 when building native recipes.
3797 This variable is used in addition to the features
3798 filtered using the
3799 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>
3800 variable.
3801 </para>
3802 </glossdef>
3803 </glossentry>
3804
3805 <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm>
3806 <info>
3807 DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes."
3808 </info>
3809 <glossdef>
3810 <para role="glossdeffirst">
3811 Specifies a list of features that should be included in
3812 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
3813 when building nativesdk recipes.
3814 This variable is used in addition to the features
3815 filtered using the
3816 <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>
3817 variable.
3818 </para>
3819 </glossdef>
3820 </glossentry>
3821
3822 <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
3823 <info>
3824 DISTRO_NAME[doc] = "The long name of the distribution."
3825 </info>
3826 <glossdef>
3827 <para role="glossdeffirst">
3828 The long name of the distribution.
3829 For information on the short name of the distribution, see
3830 the
3831 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
3832 variable.
3833 </para>
3834
3835 <para>
3836 The <filename>DISTRO_NAME</filename> variable corresponds
3837 to a distribution configuration file whose root name is the
3838 same as the variable's argument and whose filename
3839 extension is <filename>.conf</filename>.
3840 For example, the distribution configuration file for the
3841 Poky distribution is named <filename>poky.conf</filename>
3842 and resides in the
3843 <filename>meta-poky/conf/distro</filename> directory of
3844 the
3845 <link linkend='source-directory'>Source Directory</link>.
3846 </para>
3847
3848 <para>
3849 Within that <filename>poky.conf</filename> file, the
3850 <filename>DISTRO_NAME</filename> variable is set as
3851 follows:
3852 <literallayout class='monospaced'>
3853 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
3854 </literallayout>
3855 </para>
3856
3857 <para>
3858 Distribution configuration files are located in a
3859 <filename>conf/distro</filename> directory within the
3860 <link linkend='metadata'>Metadata</link>
3861 that contains the distribution configuration.
3862 <note>
3863 If the <filename>DISTRO_NAME</filename> variable is
3864 blank, a set of default configurations are used, which
3865 are specified within
3866 <filename>meta/conf/distro/defaultsetup.conf</filename>
3867 also in the Source Directory.
3868 </note>
3869 </para>
3870 </glossdef>
3871 </glossentry>
3872
3873 <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
3874 <info>
3875 DISTRO_VERSION[doc] = "The version of the distribution."
3876 </info>
3877 <glossdef>
3878 <para role="glossdeffirst">
3879 The version of the distribution.
3880 </para>
3881 </glossdef>
3882 </glossentry>
3883
3884 <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
3885 <info>
3886 DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution."
3887 </info>
3888 <glossdef>
3889 <para role="glossdeffirst">
3890 A colon-separated list of overrides specific to the
3891 current distribution.
3892 By default, this list includes the value of
3893 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>.
3894 </para>
3895
3896 <para>
3897 You can extend <filename>DISTROOVERRIDES</filename>
3898 to add extra overrides that should apply to
3899 the distribution.
3900 </para>
3901
3902 <para>
3903 The underlying mechanism behind
3904 <filename>DISTROOVERRIDES</filename> is simply that it
3905 is included in the default value of
3906 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
3907 </para>
3908 </glossdef>
3909 </glossentry>
3910
3911 <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
3912 <info>
3913 DL_DIR[doc] = "The central download directory used by the build process to store downloads. By default, the directory is 'downloads' in the Build Directory."
3914 </info>
3915 <glossdef>
3916 <para role="glossdeffirst">
3917 The central download directory used by the build process to
3918 store downloads.
3919 By default, <filename>DL_DIR</filename> gets files
3920 suitable for mirroring for everything except Git
3921 repositories.
3922 If you want tarballs of Git repositories, use the
3923 <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
3924 variable.
3925 </para>
3926
3927 <para>
3928 You can set this directory by defining the
3929 <filename>DL_DIR</filename> variable in the
3930 <filename>conf/local.conf</filename> file.
3931 This directory is self-maintaining and you should not have
3932 to touch it.
3933 By default, the directory is <filename>downloads</filename>
3934 in the
3935 <link linkend='build-directory'>Build Directory</link>.
3936 <literallayout class='monospaced'>
3937 #DL_DIR ?= "${TOPDIR}/downloads"
3938 </literallayout>
3939 To specify a different download directory, simply remove
3940 the comment from the line and provide your directory.
3941 </para>
3942
3943 <para>
3944 During a first build, the system downloads many different
3945 source code tarballs from various upstream projects.
3946 Downloading can take a while, particularly if your network
3947 connection is slow.
3948 Tarballs are all stored in the directory defined by
3949 <filename>DL_DIR</filename> and the build system looks there
3950 first to find source tarballs.
3951 <note>
3952 When wiping and rebuilding, you can preserve this
3953 directory to speed up this part of subsequent
3954 builds.
3955 </note>
3956 </para>
3957
3958 <para>
3959 You can safely share this directory between multiple builds
3960 on the same development machine.
3961 For additional information on how the build process gets
3962 source files when working behind a firewall or proxy server,
3963 see this specific question in the
3964 "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
3965 chapter.
3966 You can also refer to the
3967 "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>"
3968 Wiki page.
3969 </para>
3970 </glossdef>
3971 </glossentry>
3972
3973 <glossentry id='var-DOC_COMPRESS'><glossterm>DOC_COMPRESS</glossterm>
3974 <info>
3975 DOC_COMPRESS[doc] = "When inheriting the compress_doc class, this variable sets the compression policy used when the OpenEmbedded build system compresses man pages and info pages."
3976 </info>
3977 <glossdef>
3978 <para role="glossdeffirst">
3979 When inheriting the
3980 <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link>
3981 class, this variable sets the compression policy used when
3982 the OpenEmbedded build system compresses man pages and info
3983 pages.
3984 By default, the compression method used is gz (gzip).
3985 Other policies available are xz and bz2.
3986 </para>
3987
3988 <para>
3989 For information on policies and on how to use this
3990 variable, see the comments in the
3991 <filename>meta/classes/compress_doc.bbclass</filename> file.
3992 </para>
3993 </glossdef>
3994 </glossentry>
3995
3996 </glossdiv>
3997
3998 <glossdiv id='var-glossary-e'><title>E</title>
3999
4000 <glossentry id='var-EFI_PROVIDER'><glossterm>EFI_PROVIDER</glossterm>
4001 <info>
4002 EFI_PROVIDER[doc] = "When building bootable images (i.e. where hddimg, iso, or wic.vmdk is in IMAGE_FSTYPES), the EFI_PROVIDER variable specifies the EFI bootloader to use."
4003 </info>
4004 <glossdef>
4005 <para role="glossdeffirst">
4006 When building bootable images (i.e. where
4007 <filename>hddimg</filename>, <filename>iso</filename>,
4008 or <filename>wic.vmdk</filename> is in
4009 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>),
4010 the <filename>EFI_PROVIDER</filename> variable specifies
4011 the EFI bootloader to use.
4012 The default is "grub-efi", but "systemd-boot" can be used
4013 instead.
4014 </para>
4015
4016 <para>
4017 See the
4018 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
4019 and
4020 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
4021 classes for more information.
4022 </para>
4023 </glossdef>
4024 </glossentry>
4025
4026 <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
4027 <info>
4028 ENABLE_BINARY_LOCALE_GENERATION[doc] = "Controls which locales for glibc are generated during the build. The variable is useful if the target device has 64Mbytes of RAM or less."
4029 </info>
4030 <glossdef>
4031 <para role="glossdeffirst">
4032 Variable that controls which locales for
4033 <filename>glibc</filename> are generated during the
4034 build (useful if the target device has 64Mbytes
4035 of RAM or less).
4036 </para>
4037 </glossdef>
4038 </glossentry>
4039
4040 <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm>
4041 <info>
4042 ERR_REPORT_DIR[doc] = "When used with the report-error class, specifies the path used for storing the debug files created by the error reporting tool, which allows you to submit build errors you encounter to a central database."
4043 </info>
4044 <glossdef>
4045 <para role="glossdeffirst">
4046 When used with the
4047 <link linkend='ref-classes-report-error'><filename>report-error</filename></link>
4048 class, specifies the path used for storing the debug files
4049 created by the
4050 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
4051 which allows you to submit build errors you encounter to a
4052 central database.
4053 By default, the value of this variable is
4054 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
4055 </para>
4056
4057 <para>
4058 You can set <filename>ERR_REPORT_DIR</filename> to the path
4059 you want the error reporting tool to store the debug files
4060 as follows in your <filename>local.conf</filename> file:
4061 <literallayout class='monospaced'>
4062 ERR_REPORT_DIR = "<replaceable>path</replaceable>"
4063 </literallayout>
4064 </para>
4065 </glossdef>
4066 </glossentry>
4067
4068 <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
4069 <info>
4070 ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system."
4071 </info>
4072 <glossdef>
4073 <para role="glossdeffirst">
4074 Specifies the quality assurance checks whose failures are
4075 reported as errors by the OpenEmbedded build system.
4076 You set this variable in your distribution configuration
4077 file.
4078 For a list of the checks you can control with this variable,
4079 see the
4080 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
4081 section.
4082 </para>
4083 </glossdef>
4084 </glossentry>
4085
4086 <glossentry id='var-EXCLUDE_FROM_SHLIBS'><glossterm>EXCLUDE_FROM_SHLIBS</glossterm>
4087 <info>
4088 EXCLUDE_FROM_SHLIBS[doc] = "Causes the OpenEmbedded build system's shared libraries resolver to exclude an entire package when scanning for shared libraries."
4089 </info>
4090 <glossdef>
4091 <para role="glossdeffirst">
4092 Triggers the OpenEmbedded build system's shared libraries
4093 resolver to exclude an entire package when scanning for
4094 shared libraries.
4095 <note>
4096 The shared libraries resolver's functionality results
4097 in part from the internal function
4098 <filename>package_do_shlibs</filename>, which is part of
4099 the
4100 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
4101 task.
4102 You should be aware that the shared libraries resolver
4103 might implicitly define some dependencies between
4104 packages.
4105 </note>
4106 The <filename>EXCLUDE_FROM_SHLIBS</filename> variable is
4107 similar to the
4108 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
4109 variable, which excludes a package's particular libraries
4110 only and not the whole package.
4111 </para>
4112
4113 <para>
4114 Use the
4115 <filename>EXCLUDE_FROM_SHLIBS</filename> variable by
4116 setting it to "1" for a particular package:
4117 <literallayout class='monospaced'>
4118 EXCLUDE_FROM_SHLIBS = "1"
4119 </literallayout>
4120 </para>
4121 </glossdef>
4122 </glossentry>
4123
4124 <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
4125 <info>
4126 EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)."
4127 </info>
4128 <glossdef>
4129 <para role="glossdeffirst">
4130 Directs BitBake to exclude a recipe from world builds (i.e.
4131 <filename>bitbake world</filename>).
4132 During world builds, BitBake locates, parses and builds all
4133 recipes found in every layer exposed in the
4134 <filename>bblayers.conf</filename> configuration file.
4135 </para>
4136
4137 <para>
4138 To exclude a recipe from a world build using this variable,
4139 set the variable to "1" in the recipe.
4140 </para>
4141
4142 <note>
4143 Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
4144 may still be built during a world build in order to satisfy
4145 dependencies of other recipes.
4146 Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
4147 only ensures that the recipe is not explicitly added
4148 to the list of build targets in a world build.
4149 </note>
4150 </glossdef>
4151 </glossentry>
4152
4153 <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
4154 <info>
4155 EXTENDPE[doc] = "Used with file and pathnames to create a prefix for a recipe's version based on the recipe's PE value. If PE is set and greater than zero for a recipe, EXTENDPE becomes that value."
4156 </info>
4157 <glossdef>
4158 <para role="glossdeffirst">
4159 Used with file and pathnames to create a prefix for a recipe's
4160 version based on the recipe's
4161 <link linkend='var-PE'><filename>PE</filename></link> value.
4162 If <filename>PE</filename> is set and greater than zero for a recipe,
4163 <filename>EXTENDPE</filename> becomes that value (e.g if
4164 <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
4165 becomes "1_").
4166 If a recipe's <filename>PE</filename> is not set (the default) or is equal to
4167 zero, <filename>EXTENDPE</filename> becomes "".</para>
4168 <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
4169 variable for an example.
4170 </para>
4171 </glossdef>
4172 </glossentry>
4173
4174 <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
4175 <info>
4176 EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe."
4177 </info>
4178 <glossdef>
4179 <para role="glossdeffirst">
4180 The full package version specification as it appears on the
4181 final packages produced by a recipe.
4182 The variable's value is normally used to fix a runtime
4183 dependency to the exact same version of another package
4184 in the same recipe:
4185 <literallayout class='monospaced'>
4186 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
4187 </literallayout>
4188 </para>
4189
4190 <para>
4191 The dependency relationships are intended to force the
4192 package manager to upgrade these types of packages in
4193 lock-step.
4194 </para>
4195 </glossdef>
4196 </glossentry>
4197
4198 <glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm>
4199 <info>
4200 EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree."
4201 </info>
4202 <glossdef>
4203 <para role="glossdeffirst">
4204 When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4205 variable indicates that these tools are not in the
4206 source tree.
4207 </para>
4208
4209 <para>
4210 When kernel tools are available in the tree, they are
4211 preferred over any externally installed tools.
4212 Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename>
4213 variable tells the OpenEmbedded build system to prefer
4214 the installed external tools.
4215 See the
4216 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
4217 class in <filename>meta/classes</filename> to see how
4218 the variable is used.
4219 </para>
4220 </glossdef>
4221 </glossentry>
4222
4223 <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
4224 <info>
4225 EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system."
4226 </info>
4227 <glossdef>
4228 <para role="glossdeffirst">
4229 When inheriting the
4230 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4231 class, this variable points to the source tree, which is
4232 outside of the OpenEmbedded build system.
4233 When set, this variable sets the
4234 <link linkend='var-S'><filename>S</filename></link>
4235 variable, which is what the OpenEmbedded build system uses
4236 to locate unpacked recipe source code.
4237 </para>
4238
4239 <para>
4240 For more information on
4241 <filename>externalsrc.bbclass</filename>, see the
4242 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4243 section.
4244 You can also find information on how to use this variable
4245 in the
4246 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
4247 section in the Yocto Project Development Tasks Manual.
4248 </para>
4249 </glossdef>
4250 </glossentry>
4251
4252 <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
4253 <info>
4254 EXTERNALSRC_BUILD[doc] = "If externalsrc.bbclass is inherited, this variable points to the directory in which the recipe's source code is built, which is outside of the OpenEmbedded build system."
4255 </info>
4256 <glossdef>
4257 <para role="glossdeffirst">
4258 When inheriting the
4259 <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link>
4260 class, this variable points to the directory in which the
4261 recipe's source code is built, which is outside of the
4262 OpenEmbedded build system.
4263 When set, this variable sets the
4264 <link linkend='var-B'><filename>B</filename></link>
4265 variable, which is what the OpenEmbedded build system uses
4266 to locate the Build Directory.
4267 </para>
4268
4269 <para>
4270 For more information on
4271 <filename>externalsrc.bbclass</filename>, see the
4272 "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
4273 section.
4274 You can also find information on how to use this variable
4275 in the
4276 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
4277 section in the Yocto Project Development Tasks Manual.
4278 </para>
4279 </glossdef>
4280 </glossentry>
4281
4282 <glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm>
4283 <info>
4284 EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure."
4285 </info>
4286 <glossdef>
4287 <para role="glossdeffirst">
4288 For recipes inheriting the
4289 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
4290 class, you can use <filename>EXTRA_AUTORECONF</filename> to
4291 specify extra options to pass to the
4292 <filename>autoreconf</filename> command that is
4293 executed during the
4294 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
4295 task.
4296 </para>
4297
4298 <para>
4299 The default value is "--exclude=autopoint".
4300 </para>
4301 </glossdef>
4302 </glossentry>
4303
4304 <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
4305 <info>
4306 EXTRA_IMAGE_FEATURES[doc] = "The list of additional features to include in an image. Configure this variable in the conf/local.conf file in the Build Directory."
4307 </info>
4308 <glossdef>
4309 <para role="glossdeffirst">
4310 A list of additional features to include in an image.
4311 When listing more than one feature, separate them with
4312 a space.
4313 </para>
4314
4315 <para>
4316 Typically, you configure this variable in your
4317 <filename>local.conf</filename> file, which is found in the
4318 <link linkend='build-directory'>Build Directory</link>.
4319 Although you can use this variable from within a recipe,
4320 best practices dictate that you do not.
4321 <note>
4322 To enable primary features from within the image
4323 recipe, use the
4324 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
4325 variable.
4326 </note>
4327 </para>
4328
4329 <para>
4330 Here are some examples of features you can add:
4331 <literallayout class='monospaced'>
4332"dbg-pkgs" - Adds -dbg packages for all installed packages
4333 including symbol information for debugging and
4334 profiling.
4335
4336"debug-tweaks" - Makes an image suitable for debugging.
4337 For example, allows root logins without
4338 passwords and enables post-installation
4339 logging. See the 'allow-empty-password'
4340 and 'post-install-logging' features in
4341 the "<link linkend='ref-features-image'>Image Features</link>" section for
4342 more information.
4343
4344"dev-pkgs" - Adds -dev packages for all installed packages.
4345 This is useful if you want to develop against
4346 the libraries in the image.
4347
4348"read-only-rootfs" - Creates an image whose root
4349 filesystem is read-only. See the
4350 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
4351 section in the Yocto Project
4352 Development Tasks Manual for
4353 more information
4354
4355"tools-debug" - Adds debugging tools such as gdb and
4356 strace.
4357
4358"tools-sdk" - Adds development tools such as gcc, make,
4359 pkgconfig and so forth.
4360
4361"tools-testapps" - Adds useful testing tools such as
4362 ts_print, aplay, arecord and so
4363 forth.
4364
4365 </literallayout>
4366 </para>
4367
4368 <para>
4369 For a complete list of image features that ships with the
4370 Yocto Project, see the
4371 "<link linkend="ref-features-image">Image Features</link>"
4372 section.
4373 </para>
4374
4375 <para>
4376 For an example that shows how to customize your image by
4377 using this variable, see the
4378 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
4379 section in the Yocto Project Development Tasks Manual.
4380 </para>
4381 </glossdef>
4382 </glossentry>
4383
4384 <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm>
4385 <info>
4386 EXTRA_IMAGECMD[doc] = "Specifies additional options for the image creation command that has been specified in IMAGE_CMD. When setting this variable, you should use an override for the associated image type."
4387 </info>
4388 <glossdef>
4389 <para role="glossdeffirst">
4390 Specifies additional options for the image
4391 creation command that has been specified in
4392 <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>.
4393 When setting this variable, use an override for the
4394 associated image type.
4395 Here is an example:
4396 <literallayout class='monospaced'>
4397 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
4398 </literallayout>
4399 </para>
4400 </glossdef>
4401 </glossentry>
4402
4403 <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
4404 <info>
4405 EXTRA_IMAGEDEPENDS[doc] = "A list of recipes to build that do not provide packages for installing into the root filesystem. Use this variable to list recipes that are required to build the final image, but not needed in the root filesystem."
4406 </info>
4407 <glossdef>
4408 <para role="glossdeffirst">
4409 A list of recipes to build that do not provide packages
4410 for installing into the root filesystem.
4411 </para>
4412
4413 <para>
4414 Sometimes a recipe is required to build the final image but is not
4415 needed in the root filesystem.
4416 You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
4417 list these recipes and thus specify the dependencies.
4418 A typical example is a required bootloader in a machine configuration.
4419 </para>
4420
4421 <note>
4422 To add packages to the root filesystem, see the various
4423 <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
4424 and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
4425 variables.
4426 </note>
4427 </glossdef>
4428 </glossentry>
4429
4430 <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm>
4431 <info>
4432 EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH."
4433 </info>
4434 <glossdef>
4435 <para role="glossdeffirst">
4436 A list of subdirectories of
4437 <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename>
4438 added to the beginning of the environment variable
4439 <filename>PATH</filename>.
4440 As an example, the following prepends
4441 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:"
4442 to <filename>PATH</filename>:
4443 <literallayout class='monospaced'>
4444 EXTRANATIVEPATH = "foo bar"
4445 </literallayout>
4446 </para>
4447 </glossdef>
4448 </glossentry>
4449
4450 <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
4451 <info>
4452 EXTRA_OECMAKE[doc] = "Additional cmake options."
4453 </info>
4454 <glossdef>
4455 <para role="glossdeffirst">
4456 Additional
4457 <ulink url='https://cmake.org/overview/'>CMake</ulink>
4458 options.
4459 See the
4460 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
4461 class for additional information.
4462 </para>
4463 </glossdef>
4464 </glossentry>
4465
4466 <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
4467 <info>
4468 EXTRA_OECONF[doc] = "Additional configure script options."
4469 </info>
4470 <glossdef>
4471 <para role="glossdeffirst">
4472 Additional <filename>configure</filename> script options.
4473 See
4474 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
4475 for additional information on passing configure script
4476 options.
4477 </para>
4478 </glossdef>
4479 </glossentry>
4480
4481 <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
4482 <info>
4483 EXTRA_OEMAKE[doc] = "Additional GNU make options."
4484 </info>
4485 <glossdef>
4486 <para role="glossdeffirst">
4487 Additional GNU <filename>make</filename> options.
4488 </para>
4489
4490 <para>
4491 Because the <filename>EXTRA_OEMAKE</filename> defaults to
4492 "", you need to set the variable to specify any required
4493 GNU options.
4494 </para>
4495
4496 <para>
4497 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
4498 and
4499 <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link>
4500 also make use of
4501 <filename>EXTRA_OEMAKE</filename> to pass the required
4502 flags.
4503 </para>
4504 </glossdef>
4505 </glossentry>
4506
4507 <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm>
4508 <info>
4509 EXTRA_OESCONS[doc] = "When a recipe inherits the scons class, this variable specifies additional configuration options you want to pass to the scons command line."
4510 </info>
4511 <glossdef>
4512 <para role="glossdeffirst">
4513 When inheriting the
4514 <link linkend='ref-classes-scons'><filename>scons</filename></link>
4515 class, this variable specifies additional configuration
4516 options you want to pass to the
4517 <filename>scons</filename> command line.
4518 </para>
4519 </glossdef>
4520 </glossentry>
4521
4522 <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm>
4523 <info>
4524 EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations."
4525 </info>
4526 <glossdef>
4527 <para role="glossdeffirst">
4528 When inheriting the
4529 <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link>
4530 class, this variable provides image level user and group
4531 operations.
4532 This is a more global method of providing user and group
4533 configuration as compared to using the
4534 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
4535 class, which ties user and group configurations to a
4536 specific recipe.
4537 </para>
4538
4539 <para>
4540 The set list of commands you can configure using the
4541 <filename>EXTRA_USERS_PARAMS</filename> is shown in the
4542 <filename>extrausers</filename> class.
4543 These commands map to the normal Unix commands of the same
4544 names:
4545 <literallayout class='monospaced'>
4546 # EXTRA_USERS_PARAMS = "\
4547 # useradd -p '' tester; \
4548 # groupadd developers; \
4549 # userdel nobody; \
4550 # groupdel -g video; \
4551 # groupmod -g 1020 developers; \
4552 # usermod -s /bin/sh tester; \
4553 # "
4554 </literallayout>
4555 </para>
4556 </glossdef>
4557 </glossentry>
4558
4559 </glossdiv>
4560
4561 <glossdiv id='var-glossary-f'><title>F</title>
4562
4563 <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm>
4564 <info>
4565 FEATURE_PACKAGES[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES. When setting the value, FEATURE_PACKAGES should have the name of the feature item as an override."
4566 </info>
4567 <glossdef>
4568 <para role="glossdeffirst">
4569 Defines one or more packages to include in an image when
4570 a specific item is included in
4571 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
4572 When setting the value, <filename>FEATURE_PACKAGES</filename>
4573 should have the name of the feature item as an override.
4574 Here is an example:
4575 <literallayout class='monospaced'>
4576 FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>"
4577 </literallayout>
4578 </para>
4579
4580 <para>
4581 In this example, if "widget" were added to
4582 <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and
4583 <replaceable>package2</replaceable> would be included in the image.
4584 <note>
4585 Packages installed by features defined through
4586 <filename>FEATURE_PACKAGES</filename> are often package
4587 groups.
4588 While similarly named, you should not confuse the
4589 <filename>FEATURE_PACKAGES</filename> variable with
4590 package groups, which are discussed elsewhere in the
4591 documentation.
4592 </note>
4593 </para>
4594 </glossdef>
4595 </glossentry>
4596
4597 <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm>
4598 <info>
4599 FEED_DEPLOYDIR_BASE_URI[doc] = "Allow to serve ipk deploy directory as an ad hoc feed (bogofeed). Set to base URL of the directory as exported by HTTP. Set of ad hoc feed configs will be generated in the image."
4600 </info>
4601 <glossdef>
4602 <para role="glossdeffirst">
4603 Points to the base URL of the server and location within
4604 the document-root that provides the metadata and
4605 packages required by OPKG to support runtime package
4606 management of IPK packages.
4607 You set this variable in your
4608 <filename>local.conf</filename> file.
4609 </para>
4610
4611 <para>
4612 Consider the following example:
4613 <literallayout class='monospaced'>
4614 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
4615 </literallayout>
4616 This example assumes you are serving your packages over
4617 HTTP and your databases are located in a directory
4618 named <filename>BOARD-dir</filename>, which is underneath
4619 your HTTP server's document-root.
4620 In this case, the OpenEmbedded build system generates a set
4621 of configuration files for you in your target that work
4622 with the feed.
4623 </para>
4624 </glossdef>
4625 </glossentry>
4626
4627 <glossentry id='var-FILES'><glossterm>FILES</glossterm>
4628 <info>
4629 FILES[doc] = "The list of directories or files that are placed in a package."
4630 </info>
4631 <glossdef>
4632 <para role="glossdeffirst">
4633 The list of files and directories that are placed in a
4634 package.
4635 The
4636 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
4637 variable lists the packages generated by a recipe.
4638 </para>
4639
4640 <para>
4641 To use the <filename>FILES</filename> variable, provide a
4642 package name override that identifies the resulting package.
4643 Then, provide a space-separated list of files or paths
4644 that identify the files you want included as part of the
4645 resulting package.
4646 Here is an example:
4647 <literallayout class='monospaced'>
4648 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
4649 </literallayout>
4650 <note><title>Notes</title>
4651 <itemizedlist>
4652 <listitem><para>
4653 When specifying files or paths, you can pattern
4654 match using Python's
4655 <ulink url='https://docs.python.org/2/library/glob.html'><filename>glob</filename></ulink>
4656 syntax.
4657 For details on the syntax, see the
4658 documentation by following the previous link.
4659 </para></listitem>
4660 <listitem><para>
4661 When specifying paths as part of the
4662 <filename>FILES</filename> variable, it is
4663 good practice to use appropriate path
4664 variables.
4665 For example, use <filename>${sysconfdir}</filename>
4666 rather than <filename>/etc</filename>, or
4667 <filename>${bindir}</filename> rather than
4668 <filename>/usr/bin</filename>.
4669 You can find a list of these variables at the
4670 top of the
4671 <filename>meta/conf/bitbake.conf</filename>
4672 file in the
4673 <link linkend='source-directory'>Source Directory</link>.
4674 You will also find the default values of the
4675 various <filename>FILES_*</filename> variables
4676 in this file.
4677 </para></listitem>
4678 </itemizedlist>
4679 </note>
4680 </para>
4681
4682 <para>
4683 If some of the files you provide with the
4684 <filename>FILES</filename> variable are editable and you
4685 know they should not be overwritten during the package
4686 update process by the Package Management System (PMS), you
4687 can identify these files so that the PMS will not
4688 overwrite them.
4689 See the
4690 <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link>
4691 variable for information on how to identify these files to
4692 the PMS.
4693 </para>
4694 </glossdef>
4695 </glossentry>
4696
4697 <glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm>
4698 <info>
4699 FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform."
4700 </info>
4701 <glossdef>
4702 <para role="glossdeffirst">
4703 Defines the file specification to match
4704 <link linkend='var-SOLIBSDEV'><filename>SOLIBSDEV</filename></link>.
4705 In other words, <filename>FILES_SOLIBSDEV</filename>
4706 defines the full path name of the development symbolic link
4707 (symlink) for shared libraries on the target platform.
4708 </para>
4709
4710 <para>
4711 The following statement from the
4712 <filename>bitbake.conf</filename> shows how it is set:
4713 <literallayout class='monospaced'>
4714 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
4715 </literallayout>
4716 </para>
4717 </glossdef>
4718 </glossentry>
4719
4720 <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
4721 <info>
4722 FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files."
4723 </info>
4724 <glossdef>
4725 <para role="glossdeffirst">
4726 Extends the search path the OpenEmbedded build system uses
4727 when looking for files and patches as it processes recipes
4728 and append files.
4729 The default directories BitBake uses when it processes
4730 recipes are initially defined by the
4731 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4732 variable.
4733 You can extend <filename>FILESPATH</filename> variable
4734 by using <filename>FILESEXTRAPATHS</filename>.
4735 </para>
4736
4737 <para>
4738 Best practices dictate that you accomplish this by using
4739 <filename>FILESEXTRAPATHS</filename> from within a
4740 <filename>.bbappend</filename> file and that you prepend
4741 paths as follows:
4742 <literallayout class='monospaced'>
4743 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
4744 </literallayout>
4745 In the above example, the build system first looks for files
4746 in a directory that has the same name as the corresponding
4747 append file.
4748 <note>
4749 <para>When extending
4750 <filename>FILESEXTRAPATHS</filename>,
4751 be sure to use the immediate expansion
4752 (<filename>:=</filename>) operator.
4753 Immediate expansion makes sure that BitBake evaluates
4754 <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
4755 at the time the directive is encountered rather than at
4756 some later time when expansion might result in a
4757 directory that does not contain the files you need.
4758 </para>
4759
4760 <para>Also, include the trailing separating colon
4761 character if you are prepending.
4762 The trailing colon character is necessary because you
4763 are directing BitBake to extend the path by prepending
4764 directories to the search path.</para>
4765 </note>
4766 Here is another common use:
4767 <literallayout class='monospaced'>
4768 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
4769 </literallayout>
4770 In this example, the build system extends the
4771 <filename>FILESPATH</filename> variable to include a
4772 directory named <filename>files</filename> that is in the
4773 same directory as the corresponding append file.
4774 </para>
4775
4776 <para>
4777 This next example specifically adds three paths:
4778 <literallayout class='monospaced'>
4779 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
4780 </literallayout>
4781 </para>
4782
4783 <para>
4784 A final example shows how you can extend the search path
4785 and include a
4786 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>-specific
4787 override, which is useful in a BSP layer:
4788 <literallayout class='monospaced'>
4789 FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
4790 </literallayout>
4791 The previous statement appears in the
4792 <filename>linux-yocto-dev.bbappend</filename> file, which
4793 is found in the Yocto Project
4794 <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
4795 in
4796 <filename>meta-intel/common/recipes-kernel/linux</filename>.
4797 Here, the machine override is a special
4798 <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
4799 definition for multiple <filename>meta-intel</filename>
4800 machines.
4801 <note>
4802 For a layer that supports a single BSP, the override
4803 could just be the value of <filename>MACHINE</filename>.
4804 </note>
4805 </para>
4806
4807 <para>
4808 By prepending paths in <filename>.bbappend</filename>
4809 files, you allow multiple append files that reside in
4810 different layers but are used for the same recipe to
4811 correctly extend the path.
4812 </para>
4813 </glossdef>
4814 </glossentry>
4815
4816 <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
4817 <info>
4818 FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH."
4819 </info>
4820 <glossdef>
4821 <para role="glossdeffirst">
4822 A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
4823 used by the OpenEmbedded build system for creating
4824 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
4825 The <filename>FILESOVERRIDES</filename> variable uses
4826 overrides to automatically extend the
4827 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4828 variable.
4829 For an example of how that works, see the
4830 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
4831 variable description.
4832 Additionally, you find more information on how overrides
4833 are handled in the
4834 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
4835 section of the BitBake User Manual.
4836 </para>
4837
4838 <para>
4839 By default, the <filename>FILESOVERRIDES</filename>
4840 variable is defined as:
4841 <literallayout class='monospaced'>
4842 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
4843 </literallayout>
4844
4845 <note>
4846 Do not hand-edit the <filename>FILESOVERRIDES</filename>
4847 variable.
4848 The values match up with expected overrides and are
4849 used in an expected manner by the build system.
4850 </note>
4851 </para>
4852 </glossdef>
4853 </glossentry>
4854
4855 <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
4856 <info>
4857 FILESPATH[doc] = "The default set of directories the OpenEmbedded build system uses when searching for patches and files. It is defined in the base.bbclass class found in meta/classes in the Source Directory. Do not hand-edit the FILESPATH variable."
4858 </info>
4859 <glossdef>
4860 <para role="glossdeffirst">
4861 The default set of directories the OpenEmbedded build
4862 system uses when searching for patches and files.
4863 </para>
4864
4865 <para>
4866 During the build process, BitBake searches each directory
4867 in <filename>FILESPATH</filename> in the specified order
4868 when looking for files and patches specified by each
4869 <filename>file://</filename> URI in a recipe's
4870 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
4871 statements.
4872 </para>
4873
4874 <para>
4875 The default value for the <filename>FILESPATH</filename>
4876 variable is defined in the <filename>base.bbclass</filename>
4877 class found in <filename>meta/classes</filename> in the
4878 <link linkend='source-directory'>Source Directory</link>:
4879 <literallayout class='monospaced'>
4880 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
4881 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
4882 </literallayout>
4883 The <filename>FILESPATH</filename> variable is automatically
4884 extended using the overrides from the
4885 <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
4886 variable.
4887 <note><title>Notes</title>
4888 <itemizedlist>
4889 <listitem><para>
4890 Do not hand-edit the
4891 <filename>FILESPATH</filename> variable.
4892 If you want the build system to look in
4893 directories other than the defaults, extend the
4894 <filename>FILESPATH</filename> variable by
4895 using the
4896 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
4897 variable.
4898 </para></listitem>
4899 <listitem><para>
4900 Be aware that the default
4901 <filename>FILESPATH</filename> directories do
4902 not map to directories in custom layers
4903 where append files
4904 (<filename>.bbappend</filename>) are used.
4905 If you want the build system to find patches
4906 or files that reside with your append files,
4907 you need to extend the
4908 <filename>FILESPATH</filename> variable by
4909 using the <filename>FILESEXTRAPATHS</filename>
4910 variable.
4911 </para></listitem>
4912 </itemizedlist>
4913 </note>
4914 </para>
4915
4916 <para>
4917 You can take advantage of this searching behavior in
4918 useful ways.
4919 For example, consider a case where the following
4920 directory structure exists for general and machine-specific
4921 configurations:
4922 <literallayout class='monospaced'>
4923 files/defconfig
4924 files/MACHINEA/defconfig
4925 files/MACHINEB/defconfig
4926 </literallayout>
4927 Also in the example, the <filename>SRC_URI</filename>
4928 statement contains "file://defconfig".
4929 Given this scenario, you can set
4930 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
4931 to "MACHINEA" and cause the build system to use files
4932 from <filename>files/MACHINEA</filename>.
4933 Set <filename>MACHINE</filename> to "MACHINEB" and the
4934 build system uses files from
4935 <filename>files/MACHINEB</filename>.
4936 Finally, for any machine other than "MACHINEA" and
4937 "MACHINEB", the build system uses files from
4938 <filename>files/defconfig</filename>.
4939 </para>
4940
4941 <para>
4942 You can find out more about the patching process in the
4943 "<ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>Patching</ulink>"
4944 section in the Yocto Project Overview and Concepts Manual
4945 and the
4946 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code'>Patching Code</ulink>"
4947 section in the Yocto Project Development Tasks Manual.
4948 See the
4949 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
4950 task as well.
4951 </para>
4952 </glossdef>
4953 </glossentry>
4954
4955 <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
4956 <info>
4957 FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process."
4958 </info>
4959 <glossdef>
4960 <para role="glossdeffirst">
4961 Allows you to define your own file permissions settings table as part of
4962 your configuration for the packaging process.
4963 For example, suppose you need a consistent set of custom permissions for
4964 a set of groups and users across an entire work project.
4965 It is best to do this in the packages themselves but this is not always
4966 possible.
4967 </para>
4968
4969 <para>
4970 By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
4971 is located in the <filename>meta/files</filename> folder in the
4972 <link linkend='source-directory'>Source Directory</link>.
4973 If you create your own file permissions setting table, you should place it in your
4974 layer or the distro's layer.
4975 </para>
4976
4977 <para>
4978 You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
4979 <filename>conf/local.conf</filename> file, which is found in the
4980 <link linkend='build-directory'>Build Directory</link>, to
4981 point to your custom <filename>fs-perms.txt</filename>.
4982 You can specify more than a single file permissions setting table.
4983 The paths you specify to these files must be defined within the
4984 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
4985 </para>
4986
4987 <para>
4988 For guidance on how to create your own file permissions settings table file,
4989 examine the existing <filename>fs-perms.txt</filename>.
4990 </para>
4991 </glossdef>
4992 </glossentry>
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
5018 <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm>
5019 <info>
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'."
5021 </info>
5022 <glossdef>
5023 <para role="glossdeffirst">
5024 When inheriting the
5025 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5026 class, this variable specifies the runtime dependencies
5027 for font packages.
5028 By default, the <filename>FONT_EXTRA_RDEPENDS</filename>
5029 is set to "fontconfig-utils".
5030 </para>
5031 </glossdef>
5032 </glossentry>
5033
5034 <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm>
5035 <info>
5036 FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig."
5037 </info>
5038 <glossdef>
5039 <para role="glossdeffirst">
5040 When inheriting the
5041 <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link>
5042 class, this variable identifies packages containing font
5043 files that need to be cached by Fontconfig.
5044 By default, the <filename>fontcache</filename> class assumes
5045 that fonts are in the recipe's main package
5046 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5047 Use this variable if fonts you need are in a package
5048 other than that main package.
5049 </para>
5050 </glossdef>
5051 </glossentry>
5052
5053 <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm>
5054 <info>
5055 FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem."
5056 </info>
5057 <glossdef>
5058 <para role="glossdeffirst">
5059 Forces the removal of the packages listed in
5060 <filename>ROOTFS_RO_UNNEEDED</filename> during the
5061 generation of the root filesystem.
5062 </para>
5063
5064 <para>
5065 Set the variable to "1" to force the removal of these
5066 packages.
5067 </para>
5068 </glossdef>
5069 </glossentry>
5070
5071 <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
5072 <info>
5073 FULL_OPTIMIZATION[doc]= "The options to pass in TARGET_CFLAGS and CFLAGS when compiling an optimized system. This variable defaults to '-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2'."
5074 </info>
5075 <glossdef>
5076 <para role="glossdeffirst">
5077 The options to pass in
5078 <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
5079 and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
5080 when compiling an optimized system.
5081 This variable defaults to
5082 "-O2 -pipe ${DEBUG_FLAGS}".
5083 </para>
5084 </glossdef>
5085 </glossentry>
5086 </glossdiv>
5087
5088 <glossdiv id='var-glossary-g'><title>G</title>
5089
5090 <glossentry id='var-GCCPIE'><glossterm>GCCPIE</glossterm>
5091 <info>
5092 GCCPIE[doc] = "Enables Position Independent Executables (PIE) within the GNU C Compiler (GCC)."
5093 </info>
5094 <glossdef>
5095 <para role="glossdeffirst">
5096 Enables Position Independent Executables (PIE) within the
5097 GNU C Compiler (GCC).
5098 Enabling PIE in the GCC makes Return Oriented Programming
5099 (ROP) attacks much more difficult to
5100 execute.
5101 </para>
5102
5103 <para>
5104 By default the <filename>security_flags.inc</filename>
5105 file enables PIE by setting the variable as follows:
5106 <literallayout class='monospaced'>
5107 GCCPIE ?= "--enable-default-pie"
5108 </literallayout>
5109 </para>
5110 </glossdef>
5111 </glossentry>
5112
5113 <glossentry id='var-GCCVERSION'><glossterm>GCCVERSION</glossterm>
5114 <info>
5115 GCCVERSION[doc] = "Specifies the default version of the GNU C Compiler (GCC) to use."
5116 </info>
5117 <glossdef>
5118 <para role="glossdeffirst">
5119 Specifies the default version of the GNU C Compiler (GCC)
5120 used for compilation.
5121 By default, <filename>GCCVERSION</filename> is set to
5122 "8.x" in the
5123 <filename>meta/conf/distro/include/tcmode-default.inc</filename>
5124 include file:
5125 <literallayout class='monospaced'>
5126 GCCVERSION ?= "8.%"
5127 </literallayout>
5128 You can override this value by setting it in a configuration
5129 file such as the <filename>local.conf</filename>.
5130 </para>
5131 </glossdef>
5132 </glossentry>
5133
5134 <glossentry id='var-GDB'><glossterm>GDB</glossterm>
5135 <info>
5136 GDB[doc] = "The minimal command and arguments to run the GNU Debugger."
5137 </info>
5138 <glossdef>
5139 <para role="glossdeffirst">
5140 The minimal command and arguments to run the GNU Debugger.
5141 </para>
5142 </glossdef>
5143 </glossentry>
5144
5145 <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm>
5146 <info>
5147 GITDIR[doc] = "The directory where Git clones will be stored."
5148 </info>
5149 <glossdef>
5150 <para role="glossdeffirst">
5151 The directory in which a local copy of a Git repository
5152 is stored when it is cloned.
5153 </para>
5154 </glossdef>
5155 </glossentry>
5156
5157 <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>GLIBC_GENERATE_LOCALES</glossterm>
5158 <info>
5159 GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish to generate all LIBC locals, which can be time consuming."
5160 </info>
5161 <glossdef>
5162 <para role="glossdeffirst">
5163 Specifies the list of GLIBC locales to generate should you
5164 not wish to generate all LIBC locals, which can be time
5165 consuming.
5166 <note>
5167 If you specifically remove the locale
5168 <filename>en_US.UTF-8</filename>, you must set
5169 <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>
5170 appropriately.
5171 </note>
5172 </para>
5173
5174 <para>
5175 You can set <filename>GLIBC_GENERATE_LOCALES</filename>
5176 in your <filename>local.conf</filename> file.
5177 By default, all locales are generated.
5178 <literallayout class='monospaced'>
5179 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
5180 </literallayout>
5181 </para>
5182 </glossdef>
5183 </glossentry>
5184
5185 <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm>
5186 <info>
5187 GROUPADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupadd command if you wish to add a group to the system when the package is installed."
5188 </info>
5189 <glossdef>
5190 <para role="glossdeffirst">
5191 When inheriting the
5192 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5193 class, this variable
5194 specifies for a package what parameters should be passed
5195 to the <filename>groupadd</filename> command
5196 if you wish to add a group to the system when the package
5197 is installed.
5198 </para>
5199
5200 <para>
5201 Here is an example from the <filename>dbus</filename>
5202 recipe:
5203 <literallayout class='monospaced'>
5204 GROUPADD_PARAM_${PN} = "-r netdev"
5205 </literallayout>
5206 For information on the standard Linux shell command
5207 <filename>groupadd</filename>, see
5208 <ulink url='http://linux.die.net/man/8/groupadd'></ulink>.
5209 </para>
5210 </glossdef>
5211 </glossentry>
5212
5213 <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm>
5214 <info>
5215 GROUPMEMS_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupmems command if you wish to modify the members of a group when the package is installed."
5216 </info>
5217 <glossdef>
5218 <para role="glossdeffirst">
5219 When inheriting the
5220 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
5221 class, this variable
5222 specifies for a package what parameters should be passed
5223 to the <filename>groupmems</filename> command
5224 if you wish to modify the members of a group when the
5225 package is installed.
5226 </para>
5227
5228 <para>
5229 For information on the standard Linux shell command
5230 <filename>groupmems</filename>, see
5231 <ulink url='http://linux.die.net/man/8/groupmems'></ulink>.
5232 </para>
5233 </glossdef>
5234 </glossentry>
5235
5236 <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm>
5237 <info>
5238 GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu."
5239 </info>
5240 <glossdef>
5241 <para role="glossdeffirst">
5242 Configures the GNU GRand Unified Bootloader (GRUB) to have
5243 graphics and serial in the boot menu.
5244 Set this variable to "1" in your
5245 <filename>local.conf</filename> or distribution
5246 configuration file to enable graphics and serial
5247 in the menu.
5248 </para>
5249
5250 <para>
5251 See the
5252 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5253 class for more information on how this variable is used.
5254 </para>
5255 </glossdef>
5256 </glossentry>
5257
5258 <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm>
5259 <info>
5260 GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration."
5261 </info>
5262 <glossdef>
5263 <para role="glossdeffirst">
5264 Additional options to add to the GNU GRand Unified
5265 Bootloader (GRUB) configuration.
5266 Use a semi-colon character (<filename>;</filename>) to
5267 separate multiple options.
5268 </para>
5269
5270 <para>
5271 The <filename>GRUB_OPTS</filename> variable is optional.
5272 See the
5273 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5274 class for more information on how this variable is used.
5275 </para>
5276 </glossdef>
5277 </glossentry>
5278
5279 <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm>
5280 <info>
5281 GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)."
5282 </info>
5283 <glossdef>
5284 <para role="glossdeffirst">
5285 Specifies the timeout before executing the default
5286 <filename>LABEL</filename> in the GNU GRand Unified
5287 Bootloader (GRUB).
5288 </para>
5289
5290 <para>
5291 The <filename>GRUB_TIMEOUT</filename> variable is optional.
5292 See the
5293 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
5294 class for more information on how this variable is used.
5295 </para>
5296 </glossdef>
5297 </glossentry>
5298
5299 <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm>
5300 <info>
5301 GTKIMMODULES_PACKAGES[doc] = "For recipes that inherit the gtk-immodules-cache class, this variable specifies the packages that contain the GTK+ input method modules being installed when the modules are in packages other than the main package."
5302 </info>
5303 <glossdef>
5304 <para role="glossdeffirst">
5305 When inheriting the
5306 <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link>
5307 class, this variable specifies the packages that contain the
5308 GTK+ input method modules being installed when the modules
5309 are in packages other than the main package.
5310 </para>
5311 </glossdef>
5312 </glossentry>
5313
5314 </glossdiv>
5315
5316 <glossdiv id='var-glossary-h'><title>H</title>
5317
5318 <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
5319 <info>
5320 HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found."
5321 </info>
5322 <glossdef>
5323 <para role="glossdeffirst">
5324 Website where more information about the software the recipe is building
5325 can be found.
5326 </para>
5327 </glossdef>
5328 </glossentry>
5329
5330 <glossentry id='var-HOST_ARCH'><glossterm>HOST_ARCH</glossterm>
5331 <info>
5332 HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH."
5333
5334 </info>
5335 <glossdef>
5336 <para role="glossdeffirst">
5337 The name of the target architecture, which is normally
5338 the same as
5339 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
5340 The OpenEmbedded build system supports many
5341 architectures.
5342 Here is an example list of architectures supported.
5343 This list is by no means complete as the architecture
5344 is configurable:
5345 <literallayout class='monospaced'>
5346 arm
5347 i586
5348 x86_64
5349 powerpc
5350 powerpc64
5351 mips
5352 mipsel
5353 </literallayout>
5354 </para>
5355 </glossdef>
5356 </glossentry>
5357
5358 <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm>
5359 <info>
5360 HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH."
5361 </info>
5362 <glossdef>
5363 <para role="glossdeffirst">
5364 Specifies architecture-specific compiler flags that are
5365 passed to the C compiler.
5366 </para>
5367
5368 <para>
5369 Default initialization for <filename>HOST_CC_ARCH</filename>
5370 varies depending on what is being built:
5371 <itemizedlist>
5372 <listitem><para>
5373 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
5374 when building for the target
5375 </para></listitem>
5376 <listitem><para>
5377 <filename>BUILD_CC_ARCH</filename>
5378 when building for the build host (i.e.
5379 <filename>-native</filename>)
5380 </para></listitem>
5381 <listitem><para>
5382 <filename>BUILDSDK_CC_ARCH</filename>
5383 when building for an SDK (i.e.
5384 <filename>nativesdk-</filename>)
5385 </para></listitem>
5386 </itemizedlist>
5387 </para>
5388 </glossdef>
5389 </glossentry>
5390
5391 <glossentry id='var-HOST_OS'><glossterm>HOST_OS</glossterm>
5392 <info>
5393 HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS."
5394 </info>
5395 <glossdef>
5396 <para role="glossdeffirst">
5397 Specifies the name of the target operating system, which
5398 is normally the same as the
5399 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>.
5400 The variable can be set to "linux" for <filename>glibc</filename>-based systems and
5401 to "linux-musl" for <filename>musl</filename>.
5402 For ARM/EABI targets, there are also "linux-gnueabi" and
5403 "linux-musleabi" values possible.
5404 </para>
5405 </glossdef>
5406 </glossentry>
5407
5408 <glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm>
5409 <info>
5410 HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX."
5411 </info>
5412 <glossdef>
5413 <para role="glossdeffirst">
5414 Specifies the prefix for the cross-compile toolchain.
5415 <filename>HOST_PREFIX</filename> is normally the same as
5416 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>.
5417 </para>
5418 </glossdef>
5419 </glossentry>
5420
5421 <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
5422 <info>
5423 HOST_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the build is occurring in the context of the current recipe."
5424 </info>
5425 <glossdef>
5426 <para role="glossdeffirst">
5427 Specifies the system, including the architecture and the
5428 operating system, for which the build is occurring
5429 in the context of the current recipe.
5430 </para>
5431
5432 <para>
5433 The OpenEmbedded build system automatically sets this
5434 variable based on
5435 <link linkend='var-HOST_ARCH'><filename>HOST_ARCH</filename></link>,
5436 <link linkend='var-HOST_VENDOR'><filename>HOST_VENDOR</filename></link>,
5437 and
5438 <link linkend='var-HOST_OS'><filename>HOST_OS</filename></link>
5439 variables.
5440 <note>
5441 You do not need to set the variable yourself.
5442 </note>
5443 </para>
5444
5445 <para>
5446 Consider these two examples:
5447 <itemizedlist>
5448 <listitem><para>Given a native recipe on a 32-bit
5449 x86 machine running Linux, the value is
5450 "i686-linux".
5451 </para></listitem>
5452 <listitem><para>Given a recipe being built for a
5453 little-endian MIPS target running Linux,
5454 the value might be "mipsel-linux".
5455 </para></listitem>
5456 </itemizedlist>
5457 </para>
5458 </glossdef>
5459 </glossentry>
5460
5461 <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm>
5462 <info>
5463 HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
5464 </info>
5465 <glossdef>
5466 <para role="glossdeffirst">
5467 A space-separated list (filter) of tools on the build host
5468 that should be allowed to be called from within build tasks.
5469 Using this filter helps reduce the possibility of host
5470 contamination.
5471 If a tool specified in the value of
5472 <filename>HOSTTOOLS</filename> is not found on the
5473 build host, the OpenEmbedded build system produces
5474 an error and the build is not started.
5475 </para>
5476
5477 <para>
5478 For additional information, see
5479 <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>.
5480 </para>
5481 </glossdef>
5482 </glossentry>
5483
5484 <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm>
5485 <info>
5486 HOSTTOOLS_NONFATAL[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks."
5487 </info>
5488 <glossdef>
5489 <para role="glossdeffirst">
5490 A space-separated list (filter) of tools on the build host
5491 that should be allowed to be called from within build tasks.
5492 Using this filter helps reduce the possibility of host
5493 contamination.
5494 Unlike
5495 <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>,
5496 the OpenEmbedded build system does not produce an error
5497 if a tool specified in the value of
5498 <filename>HOSTTOOLS_NONFATAL</filename> is not found on the
5499 build host.
5500 Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename>
5501 to filter optional host tools.
5502 </para>
5503 </glossdef>
5504 </glossentry>
5505
5506 <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm>
5507 <info>
5508 HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR."
5509 </info>
5510 <glossdef>
5511 <para role="glossdeffirst">
5512 Specifies the name of the vendor.
5513 <filename>HOST_VENDOR</filename> is normally the same as
5514 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>.
5515 </para>
5516 </glossdef>
5517 </glossentry>
5518
5519 </glossdiv>
5520
5521 <glossdiv id='var-glossary-i'><title>I</title>
5522
5523 <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm>
5524 <info>
5525 ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function."
5526 </info>
5527 <glossdef>
5528 <para role="glossdeffirst">
5529 Disables or enables the <filename>icecc</filename>
5530 (Icecream) function.
5531 For more information on this function and best practices
5532 for using this variable, see the
5533 "<link linkend='ref-classes-icecc'><filename>icecc.bbclass</filename></link>"
5534 section.
5535 </para>
5536
5537 <para>
5538 Setting this variable to "1" in your
5539 <filename>local.conf</filename> disables the function:
5540 <literallayout class='monospaced'>
5541 ICECC_DISABLED ??= "1"
5542 </literallayout>
5543 To enable the function, set the variable as follows:
5544 <literallayout class='monospaced'>
5545 ICECC_DISABLED = ""
5546 </literallayout>
5547 </para>
5548 </glossdef>
5549 </glossentry>
5550
5551 <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm>
5552 <info>
5553 ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide."
5554 </info>
5555 <glossdef>
5556 <para role="glossdeffirst">
5557 Points to the <filename>icecc-create-env</filename> script
5558 that you provide.
5559 This variable is used by the
5560 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5561 class.
5562 You set this variable in your
5563 <filename>local.conf</filename> file.
5564 </para>
5565
5566 <para>
5567 If you do not point to a script that you provide, the
5568 OpenEmbedded build system uses the default script provided
5569 by the <filename>icecc-create-env.bb</filename> recipe,
5570 which is a modified version and not the one that comes with
5571 <filename>icecc</filename>.
5572 </para>
5573 </glossdef>
5574 </glossentry>
5575
5576 <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm>
5577 <info>
5578 ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation."
5579 </info>
5580 <glossdef>
5581 <para role="glossdeffirst">
5582 Extra options passed to the <filename>make</filename>
5583 command during the
5584 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
5585 task that specify parallel compilation.
5586 This variable usually takes the form of
5587 "-j <replaceable>x</replaceable>", where
5588 <replaceable>x</replaceable> represents the maximum
5589 number of parallel threads <filename>make</filename> can
5590 run.
5591 <note>
5592 The options passed affect builds on all enabled
5593 machines on the network, which are machines running the
5594 <filename>iceccd</filename> daemon.
5595 </note>
5596 </para>
5597
5598 <para>
5599 If your enabled machines support multiple cores,
5600 coming up with the maximum number of parallel threads
5601 that gives you the best performance could take some
5602 experimentation since machine speed, network lag,
5603 available memory, and existing machine loads can all
5604 affect build time.
5605 Consequently, unlike the
5606 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5607 variable, there is no rule-of-thumb for setting
5608 <filename>ICECC_PARALLEL_MAKE</filename> to achieve
5609 optimal performance.
5610 </para>
5611
5612 <para>
5613 If you do not set <filename>ICECC_PARALLEL_MAKE</filename>,
5614 the build system does not use it (i.e. the system does
5615 not detect and assign the number of cores as is done with
5616 <filename>PARALLEL_MAKE</filename>).
5617 </para>
5618 </glossdef>
5619 </glossentry>
5620
5621 <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm>
5622 <info>
5623 ICECC_PATH[doc] = "The location of the icecc binary."
5624 </info>
5625 <glossdef>
5626 <para role="glossdeffirst">
5627 The location of the <filename>icecc</filename> binary.
5628 You can set this variable in your
5629 <filename>local.conf</filename> file.
5630 If your <filename>local.conf</filename> file does not define
5631 this variable, the
5632 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5633 class attempts to define it by locating
5634 <filename>icecc</filename> using <filename>which</filename>.
5635 </para>
5636 </glossdef>
5637 </glossentry>
5638
5639 <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm>
5640 <info>
5641 ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider."
5642 </info>
5643 <glossdef>
5644 <para role="glossdeffirst">
5645 Identifies user classes that you do not want the
5646 Icecream distributed compile support to consider.
5647 This variable is used by the
5648 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5649 class.
5650 You set this variable in your
5651 <filename>local.conf</filename> file.
5652 </para>
5653
5654 <para>
5655 When you list classes using this variable, you are
5656 "blacklisting" them from distributed compilation across
5657 remote hosts.
5658 Any classes you list will be distributed and compiled
5659 locally.
5660 </para>
5661 </glossdef>
5662 </glossentry>
5663
5664 <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm>
5665 <info>
5666 ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider."
5667 </info>
5668 <glossdef>
5669 <para role="glossdeffirst">
5670 Identifies user recipes that you do not want the
5671 Icecream distributed compile support to consider.
5672 This variable is used by the
5673 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5674 class.
5675 You set this variable in your
5676 <filename>local.conf</filename> file.
5677 </para>
5678
5679 <para>
5680 When you list packages using this variable, you are
5681 "blacklisting" them from distributed compilation across
5682 remote hosts.
5683 Any packages you list will be distributed and compiled
5684 locally.
5685 </para>
5686 </glossdef>
5687 </glossentry>
5688
5689 <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm>
5690 <info>
5691 ICECC_USER_PACKAGE_WL[doc] = "Identifies user recipes that use an empty PARALLEL_MAKE variable that you want to force remote distributed compilation on using the Icecream distributed compile support."
5692 </info>
5693 <glossdef>
5694 <para role="glossdeffirst">
5695 Identifies user recipes that use an empty
5696 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
5697 variable that you want to force remote distributed
5698 compilation on using the Icecream distributed compile
5699 support.
5700 This variable is used by the
5701 <link linkend='ref-classes-icecc'><filename>icecc</filename></link>
5702 class.
5703 You set this variable in your
5704 <filename>local.conf</filename> file.
5705 </para>
5706 </glossdef>
5707 </glossentry>
5708
5709 <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
5710 <info>
5711 IMAGE_BASENAME[doc] = "The base name of image output files."
5712 </info>
5713 <glossdef>
5714 <para role="glossdeffirst">
5715 The base name of image output files.
5716 This variable defaults to the recipe name
5717 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
5718 </para>
5719 </glossdef>
5720 </glossentry>
5721
5722 <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>IMAGE_BOOT_FILES</glossterm>
5723 <info>
5724 IMAGE_BOOT_FILES[doc] = "A space-separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition."
5725 </info>
5726 <glossdef>
5727 <para role="glossdeffirst">
5728 A space-separated list of files installed into the
5729 boot partition when preparing an image using the Wic tool
5730 with the <filename>bootimg-partition</filename> or <filename>bootimg-efi</filename> source
5731 plugin.
5732 By default, the files are installed under the same name as
5733 the source files.
5734 To change the installed name, separate it from the
5735 original name with a semi-colon (;).
5736 Source files need to be located in
5737 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>.
5738 Here are two examples:
5739
5740 <literallayout class="monospaced">
5741 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
5742 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
5743 </literallayout>
5744 </para>
5745
5746 <para>
5747 Alternatively, source files can be picked up using
5748 a glob pattern.
5749 In this case, the destination file must have the same name
5750 as the base name of the source file path.
5751 To install files into a directory within the
5752 target location, pass its name after a semi-colon
5753 (;).
5754 Here are two examples:
5755 <literallayout class="monospaced">
5756 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
5757 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
5758 </literallayout>
5759 The first example installs all files from
5760 <filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename>
5761 into the root of the target partition.
5762 The second example installs the same files into a
5763 <filename>boot</filename> directory within the
5764 target partition.
5765 </para>
5766
5767 <para>
5768 You can find information on how to use the Wic tool in the
5769 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
5770 section of the Yocto Project Development Tasks Manual.
5771 Reference material for Wic is located in the
5772 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (.wks) Reference</ulink>"
5773 chapter.
5774 </para>
5775 </glossdef>
5776 </glossentry>
5777
5778 <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
5779 <info>
5780 IMAGE_CLASSES[doc] = "A list of classes that all images should inherit."
5781 </info>
5782 <glossdef>
5783 <para role="glossdeffirst">
5784 A list of classes that all images should inherit.
5785 You typically use this variable to specify the list of
5786 classes that register the different types of images
5787 the OpenEmbedded build system creates.
5788 </para>
5789
5790 <para>
5791 The default value for <filename>IMAGE_CLASSES</filename> is
5792 <filename>image_types</filename>.
5793 You can set this variable in your
5794 <filename>local.conf</filename> or in a distribution
5795 configuration file.
5796 </para>
5797
5798 <para>
5799 For more information, see
5800 <filename>meta/classes/image_types.bbclass</filename> in the
5801 <link linkend='source-directory'>Source Directory</link>.
5802 </para>
5803 </glossdef>
5804 </glossentry>
5805
5806 <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm>
5807 <info>
5808 IMAGE_CMD[doc] = "Specifies the command to create the image file for a specific image type, which corresponds to the value set set in IMAGE_FSTYPES, (e.g. ext3, btrfs, and so forth)."
5809 </info>
5810 <glossdef>
5811 <para role="glossdeffirst">
5812 Specifies the command to create the image file for a
5813 specific image type, which corresponds to the value set
5814 set in
5815 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>,
5816 (e.g. <filename>ext3</filename>,
5817 <filename>btrfs</filename>, and so forth).
5818 When setting this variable, you should use
5819 an override for the associated type.
5820 Here is an example:
5821 <literallayout class='monospaced'>
5822 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
5823 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
5824 ${EXTRA_IMAGECMD}"
5825 </literallayout>
5826 </para>
5827
5828 <para>
5829 You typically do not need to set this variable unless
5830 you are adding support for a new image type.
5831 For more examples on how to set this variable, see the
5832 <link linkend='ref-classes-image_types'><filename>image_types</filename></link>
5833 class file, which is
5834 <filename>meta/classes/image_types.bbclass</filename>.
5835 </para>
5836 </glossdef>
5837 </glossentry>
5838
5839 <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm>
5840 <info>
5841 IMAGE_DEVICE_TABLES[doc] = "Specifies one or more files that contain custom device tables that are passed to the makedevs command as part of creating an image."
5842 </info>
5843 <glossdef>
5844 <para role="glossdeffirst">
5845 Specifies one or more files that contain custom device
5846 tables that are passed to the
5847 <filename>makedevs</filename> command as part of creating
5848 an image.
5849 These files list basic device nodes that should be
5850 created under <filename>/dev</filename> within the image.
5851 If <filename>IMAGE_DEVICE_TABLES</filename> is not set,
5852 <filename>files/device_table-minimal.txt</filename> is
5853 used, which is located by
5854 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
5855 For details on how you should write device table files,
5856 see <filename>meta/files/device_table-minimal.txt</filename>
5857 as an example.
5858 </para>
5859 </glossdef>
5860 </glossentry>
5861
5862 <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
5863 <info>
5864 IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe."
5865 </info>
5866 <glossdef>
5867 <para role="glossdeffirst">
5868 The primary list of features to include in an image.
5869 Typically, you configure this variable in an image recipe.
5870 Although you can use this variable from your
5871 <filename>local.conf</filename> file, which is found in the
5872 <link linkend='build-directory'>Build Directory</link>,
5873 best practices dictate that you do not.
5874 <note>
5875 To enable extra features from outside the image recipe,
5876 use the
5877 <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
5878 </note>
5879 </para>
5880
5881 <para>
5882 For a list of image features that ships with the Yocto
5883 Project, see the
5884 "<link linkend="ref-features-image">Image Features</link>"
5885 section.
5886 </para>
5887
5888 <para>
5889 For an example that shows how to customize your image by
5890 using this variable, see the
5891 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
5892 section in the Yocto Project Development Tasks Manual.
5893 </para>
5894 </glossdef>
5895 </glossentry>
5896
5897 <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
5898 <info>
5899 IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created."
5900 </info>
5901 <glossdef>
5902 <para role="glossdeffirst">
5903 Specifies the formats the OpenEmbedded build system uses
5904 during the build when creating the root filesystem.
5905 For example, setting <filename>IMAGE_FSTYPES</filename>
5906 as follows causes the build system to create root
5907 filesystems using two formats: <filename>.ext3</filename>
5908 and <filename>.tar.bz2</filename>:
5909 <literallayout class='monospaced'>
5910 IMAGE_FSTYPES = "ext3 tar.bz2"
5911 </literallayout>
5912 </para>
5913
5914 <para>
5915 For the complete list of supported image formats from which
5916 you can choose, see
5917 <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
5918 </para>
5919
5920 <note><title>Notes</title>
5921 <itemizedlist>
5922 <listitem><para>
5923 If an image recipe uses the "inherit image" line
5924 and you are setting
5925 <filename>IMAGE_FSTYPES</filename> inside the
5926 recipe, you must set
5927 <filename>IMAGE_FSTYPES</filename> prior to
5928 using the "inherit image" line.
5929 </para></listitem>
5930 <listitem><para>
5931 Due to the way the OpenEmbedded build system
5932 processes this variable, you cannot update its
5933 contents by using <filename>_append</filename> or
5934 <filename>_prepend</filename>.
5935 You must use the <filename>+=</filename>
5936 operator to add one or more options to the
5937 <filename>IMAGE_FSTYPES</filename> variable.
5938 </para></listitem>
5939 </itemizedlist>
5940 </note>
5941 </glossdef>
5942 </glossentry>
5943
5944 <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
5945 <info>
5946 IMAGE_INSTALL[doc] = "Used by recipes to specify the packages to install into an image through image.bbclass."
5947 </info>
5948 <glossdef>
5949 <para role="glossdeffirst">
5950 Used by recipes to specify the packages to install into an
5951 image through the
5952 <link linkend='ref-classes-image'><filename>image</filename></link>
5953 class.
5954 Use the <filename>IMAGE_INSTALL</filename> variable with
5955 care to avoid ordering issues.
5956 </para>
5957
5958 <para>
5959 Image recipes set <filename>IMAGE_INSTALL</filename>
5960 to specify the packages to install into an image through
5961 <filename>image.bbclass</filename>.
5962 Additionally, "helper" classes such as the
5963 <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
5964 class exist that can take lists used with
5965 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
5966 and turn them into auto-generated entries in
5967 <filename>IMAGE_INSTALL</filename> in addition to its
5968 default contents.
5969 </para>
5970
5971 <para>
5972 When you use this variable, it is best to use it as follows:
5973 <literallayout class='monospaced'>
5974 IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>"
5975 </literallayout>
5976 Be sure to include the space between the quotation character
5977 and the start of the package name or names.
5978 <note><title>Caution</title>
5979 <itemizedlist>
5980 <listitem><para>
5981 When working with a
5982 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
5983 image, do not use the
5984 <filename>IMAGE_INSTALL</filename> variable to
5985 specify packages for installation.
5986 Instead, use the
5987 <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>
5988 variable, which allows the initial RAM
5989 filesystem (initramfs) recipe to use a fixed
5990 set of packages and not be affected by
5991 <filename>IMAGE_INSTALL</filename>.
5992 For information on creating an initramfs, see
5993 the
5994 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
5995 section in the Yocto Project Development Tasks
5996 Manual.
5997 </para></listitem>
5998 <listitem><para>
5999 Using <filename>IMAGE_INSTALL</filename> with
6000 the
6001 <ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending'><filename>+=</filename></ulink>
6002 BitBake operator within the
6003 <filename>/conf/local.conf</filename> file or
6004 from within an image recipe is not recommended.
6005 Use of this operator in these ways can cause
6006 ordering issues.
6007 Since <filename>core-image.bbclass</filename>
6008 sets <filename>IMAGE_INSTALL</filename> to a
6009 default value using the
6010 <ulink url='&YOCTO_DOCS_BB_URL;#setting-a-default-value'><filename>?=</filename></ulink>
6011 operator, using a <filename>+=</filename>
6012 operation against
6013 <filename>IMAGE_INSTALL</filename> results in
6014 unexpected behavior when used within
6015 <filename>conf/local.conf</filename>.
6016 Furthermore, the same operation from within
6017 an image recipe may or may not succeed
6018 depending on the specific situation.
6019 In both these cases, the behavior is contrary
6020 to how most users expect the
6021 <filename>+=</filename> operator to work.
6022 </para></listitem>
6023 </itemizedlist>
6024 </note>
6025 </para>
6026 </glossdef>
6027 </glossentry>
6028
6029 <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
6030 <info>
6031 IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process."
6032 </info>
6033 <glossdef>
6034 <para role="glossdeffirst">
6035 Specifies the list of locales to install into the image
6036 during the root filesystem construction process.
6037 The OpenEmbedded build system automatically splits locale
6038 files, which are used for localization, into separate
6039 packages.
6040 Setting the <filename>IMAGE_LINGUAS</filename> variable
6041 ensures that any locale packages that correspond to packages
6042 already selected for installation into the image are also
6043 installed.
6044 Here is an example:
6045 <literallayout class='monospaced'>
6046 IMAGE_LINGUAS = "pt-br de-de"
6047 </literallayout>
6048 </para>
6049
6050 <para>
6051 In this example, the build system ensures any Brazilian
6052 Portuguese and German locale files that correspond to
6053 packages in the image are installed (i.e.
6054 <filename>*-locale-pt-br</filename>
6055 and <filename>*-locale-de-de</filename> as well as
6056 <filename>*-locale-pt</filename>
6057 and <filename>*-locale-de</filename>, since some software
6058 packages only provide locale files by language and not by
6059 country-specific language).
6060 </para>
6061
6062 <para>
6063 See the
6064 <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link>
6065 variable for information on generating GLIBC locales.
6066 </para>
6067 </glossdef>
6068 </glossentry>
6069
6070 <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm>
6071 <info>
6072 IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image."
6073 </info>
6074 <glossdef>
6075 <para role="glossdeffirst">
6076 The manifest file for the image.
6077 This file lists all the installed packages that make up
6078 the image.
6079 The file contains package information on a line-per-package
6080 basis as follows:
6081 <literallayout class='monospaced'>
6082 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
6083 </literallayout>
6084 </para>
6085
6086 <para>
6087 The
6088 <link linkend='ref-classes-image'><filename>image</filename></link>
6089 class defines the manifest file as follows:
6090 <literallayout class='monospaced'>
6091 IMAGE_MANIFEST = "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
6092 </literallayout>
6093 The location is derived using the
6094 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
6095 and
6096 <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>
6097 variables.
6098 You can find information on how the image
6099 is created in the
6100 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
6101 section in the Yocto Project Overview and Concepts Manual.
6102 </para>
6103 </glossdef>
6104 </glossentry>
6105
6106 <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
6107 <info>
6108 IMAGE_NAME[doc] = "The name of the output image files minus the extension."
6109 </info>
6110 <glossdef>
6111 <para role="glossdeffirst">
6112 The name of the output image files minus the extension.
6113 This variable is derived using the
6114 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
6115 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
6116 and
6117 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
6118 variables:
6119 <literallayout class='monospaced'>
6120 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
6121 </literallayout>
6122 </para>
6123 </glossdef>
6124 </glossentry>
6125
6126 <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
6127 <info>
6128 IMAGE_OVERHEAD_FACTOR[doc] = "Defines a multiplier that the build system applies to the initial image size for cases when the multiplier times the returned disk usage value for the image is greater than the sum of IMAGE_ROOTFS_SIZE and IMAGE_ROOTFS_EXTRA_SPACE."
6129 </info>
6130 <glossdef>
6131 <para role="glossdeffirst">
6132 Defines a multiplier that the build system applies to the initial image
6133 size for cases when the multiplier times the returned disk usage value
6134 for the image is greater than the sum of
6135 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6136 and
6137 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
6138 The result of the multiplier applied to the initial image size creates
6139 free disk space in the image as overhead.
6140 By default, the build process uses a multiplier of 1.3 for this variable.
6141 This default value results in 30% free disk space added to the image when this
6142 method is used to determine the final generated image size.
6143 You should be aware that post install scripts and the package management
6144 system uses disk space inside this overhead area.
6145 Consequently, the multiplier does not produce an image with
6146 all the theoretical free disk space.
6147 See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
6148 for information on how the build system determines the overall image size.
6149 </para>
6150
6151 <para>
6152 The default 30% free disk space typically gives the image enough room to boot
6153 and allows for basic post installs while still leaving a small amount of
6154 free disk space.
6155 If 30% free space is inadequate, you can increase the default value.
6156 For example, the following setting gives you 50% free space added to the image:
6157 <literallayout class='monospaced'>
6158 IMAGE_OVERHEAD_FACTOR = "1.5"
6159 </literallayout>
6160 </para>
6161
6162 <para>
6163 Alternatively, you can ensure a specific amount of free disk space is added
6164 to the image by using the
6165 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6166 variable.
6167 </para>
6168 </glossdef>
6169 </glossentry>
6170
6171 <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm>
6172 <info>
6173 IMAGE_PKGTYPE[doc] = "Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system."
6174 </info>
6175 <glossdef>
6176 <para role="glossdeffirst">
6177 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used
6178 by the OpenEmbedded build system.
6179 The variable is defined appropriately by the
6180 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
6181 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
6182 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
6183 or
6184 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>
6185 class.
6186 <note><title>Warning</title>
6187 The <filename>package_tar</filename> class is broken
6188 and is not supported.
6189 It is recommended that you do not use it.
6190 </note>
6191 </para>
6192
6193 <para>
6194 The
6195 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_*</filename></link>
6196 and
6197 <link linkend='ref-classes-image'><filename>image</filename></link>
6198 classes use the <filename>IMAGE_PKGTYPE</filename> for
6199 packaging up images and SDKs.
6200 </para>
6201
6202 <para>
6203 You should not set the <filename>IMAGE_PKGTYPE</filename>
6204 manually.
6205 Rather, the variable is set indirectly through the
6206 appropriate
6207 <link linkend='ref-classes-package'><filename>package_*</filename></link>
6208 class using the
6209 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
6210 variable.
6211 The OpenEmbedded build system uses the first package type
6212 (e.g. DEB, RPM, or IPK) that appears with the variable
6213 <note>
6214 Files using the <filename>.tar</filename> format are
6215 never used as a substitute packaging format for DEB,
6216 RPM, and IPK formatted files for your image or SDK.
6217 </note>
6218 </para>
6219 </glossdef>
6220 </glossentry>
6221
6222 <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
6223 <info>
6224 IMAGE_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the final image output files."
6225 </info>
6226 <glossdef>
6227 <para role="glossdeffirst">
6228 Specifies a list of functions to call once the
6229 OpenEmbedded build system creates the final image
6230 output files.
6231 You can specify functions separated by semicolons:
6232 <literallayout class='monospaced'>
6233 IMAGE_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6234 </literallayout>
6235 </para>
6236
6237 <para>
6238 If you need to pass the root filesystem path to a command
6239 within the function, you can use
6240 <filename>${IMAGE_ROOTFS}</filename>, which points to
6241 the directory that becomes the root filesystem image.
6242 See the
6243 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6244 variable for more information.
6245 </para>
6246 </glossdef>
6247 </glossentry>
6248
6249 <glossentry id='var-IMAGE_PREPROCESS_COMMAND'><glossterm>IMAGE_PREPROCESS_COMMAND</glossterm>
6250 <info>
6251 IMAGE_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system creates the final image output files."
6252 </info>
6253 <glossdef>
6254 <para role="glossdeffirst">
6255 Specifies a list of functions to call before the
6256 OpenEmbedded build system creates the final image
6257 output files.
6258 You can specify functions separated by semicolons:
6259 <literallayout class='monospaced'>
6260 IMAGE_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
6261 </literallayout>
6262 </para>
6263
6264 <para>
6265 If you need to pass the root filesystem path to a command
6266 within the function, you can use
6267 <filename>${IMAGE_ROOTFS}</filename>, which points to
6268 the directory that becomes the root filesystem image.
6269 See the
6270 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
6271 variable for more information.
6272 </para>
6273 </glossdef>
6274 </glossentry>
6275
6276 <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
6277 <info>
6278 IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)."
6279 </info>
6280 <glossdef>
6281 <para role="glossdeffirst">
6282 The location of the root filesystem while it is under
6283 construction (i.e. during the
6284 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
6285 task).
6286 This variable is not configurable.
6287 Do not change it.
6288 </para>
6289 </glossdef>
6290 </glossentry>
6291
6292 <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm>
6293 <info>
6294 IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes."
6295 </info>
6296 <glossdef>
6297 <para role="glossdeffirst">
6298 Specifies the alignment for the output image file in
6299 Kbytes.
6300 If the size of the image is not a multiple of
6301 this value, then the size is rounded up to the nearest
6302 multiple of the value.
6303 The default value is "1".
6304 See
6305 <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
6306 for additional information.
6307 </para>
6308 </glossdef>
6309 </glossentry>
6310
6311 <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
6312 <info>
6313 IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'."
6314 </info>
6315 <glossdef>
6316 <para role="glossdeffirst">
6317 Defines additional free disk space created in the image in Kbytes.
6318 By default, this variable is set to "0".
6319 This free disk space is added to the image after the build system determines
6320 the image size as described in
6321 <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
6322 </para>
6323
6324 <para>
6325 This variable is particularly useful when you want to ensure that a
6326 specific amount of free disk space is available on a device after an image
6327 is installed and running.
6328 For example, to be sure 5 Gbytes of free disk space is available, set the
6329 variable as follows:
6330 <literallayout class='monospaced'>
6331 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
6332 </literallayout>
6333 </para>
6334
6335 <para>
6336 For example, the Yocto Project Build Appliance specifically requests 40 Gbytes
6337 of extra space with the line:
6338 <literallayout class='monospaced'>
6339 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
6340 </literallayout>
6341 </para>
6342 </glossdef>
6343 </glossentry>
6344
6345 <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
6346 <info>
6347 IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image."
6348 </info>
6349 <glossdef>
6350 <para role="glossdeffirst">
6351 Defines the size in Kbytes for the generated image.
6352 The OpenEmbedded build system determines the final size for the generated
6353 image using an algorithm that takes into account the initial disk space used
6354 for the generated image, a requested size for the image, and requested
6355 additional free disk space to be added to the image.
6356 Programatically, the build system determines the final size of the
6357 generated image as follows:
6358 <literallayout class='monospaced'>
6359 if (image-du * overhead) &lt; rootfs-size:
6360 internal-rootfs-size = rootfs-size + xspace
6361 else:
6362 internal-rootfs-size = (image-du * overhead) + xspace
6363
6364 where:
6365
6366 image-du = Returned value of the du command on
6367 the image.
6368
6369 overhead = IMAGE_OVERHEAD_FACTOR
6370
6371 rootfs-size = IMAGE_ROOTFS_SIZE
6372
6373 internal-rootfs-size = Initial root filesystem
6374 size before any modifications.
6375
6376 xspace = IMAGE_ROOTFS_EXTRA_SPACE
6377 </literallayout>
6378 </para>
6379
6380 <para>
6381 See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
6382 and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
6383 variables for related information.
6384<!-- In the above example, <filename>overhead</filename> is defined by the
6385 <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
6386 variable, <filename>xspace</filename> is defined by the
6387 <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
6388 variable, and <filename>du</filename> is the results of the disk usage command
6389 on the initially generated image. -->
6390 </para>
6391 </glossdef>
6392 </glossentry>
6393
6394 <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm>
6395 <info>
6396 IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another."
6397 </info>
6398 <glossdef>
6399 <para role="glossdeffirst">
6400 Specifies a dependency from one image type on another.
6401 Here is an example from the
6402 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
6403 class:
6404 <literallayout class='monospaced'>
6405 IMAGE_TYPEDEP_live = "ext3"
6406 </literallayout>
6407 </para>
6408
6409 <para>
6410 In the previous example, the variable ensures that when
6411 "live" is listed with the
6412 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6413 variable, the OpenEmbedded build system produces an
6414 <filename>ext3</filename> image first since one of the
6415 components of the live
6416 image is an <filename>ext3</filename>
6417 formatted partition containing the root
6418 filesystem.
6419 </para>
6420 </glossdef>
6421 </glossentry>
6422
6423 <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
6424 <info>
6425 IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default."
6426 </info>
6427 <glossdef>
6428 <para role="glossdeffirst">
6429 Specifies the complete list of supported image types
6430 by default:
6431 <literallayout class='monospaced'>
6432 btrfs
6433 container
6434 cpio
6435 cpio.gz
6436 cpio.lz4
6437 cpio.lzma
6438 cpio.xz
6439 cramfs
6440 ext2
6441 ext2.bz2
6442 ext2.gz
6443 ext2.lzma
6444 ext3
6445 ext3.gz
6446 ext4
6447 ext4.gz
6448 f2fs
6449 hddimg
6450 iso
6451 jffs2
6452 jffs2.sum
6453 multiubi
6454 squashfs
6455 squashfs-lz4
6456 squashfs-lzo
6457 squashfs-xz
6458 tar
6459 tar.bz2
6460 tar.gz
6461 tar.lz4
6462 tar.xz
6463 tar.zst
6464 ubi
6465 ubifs
6466 wic
6467 wic.bz2
6468 wic.gz
6469 wic.lzma
6470 </literallayout>
6471 </para>
6472
6473 <para>
6474 For more information about these types of images, see
6475 <filename>meta/classes/image_types*.bbclass</filename>
6476 in the
6477 <link linkend='source-directory'>Source Directory</link>.
6478 </para>
6479 </glossdef>
6480 </glossentry>
6481
6482 <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
6483 <info>
6484 INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file."
6485 </info>
6486 <glossdef>
6487 <para role="glossdeffirst">
6488 Helps define the recipe revision for recipes that share
6489 a common <filename>include</filename> file.
6490 You can think of this variable as part of the recipe revision
6491 as set from within an include file.
6492 </para>
6493
6494 <para>
6495 Suppose, for example, you have a set of recipes that
6496 are used across several projects.
6497 And, within each of those recipes the revision
6498 (its <link linkend='var-PR'><filename>PR</filename></link>
6499 value) is set accordingly.
6500 In this case, when the revision of those recipes changes,
6501 the burden is on you to find all those recipes and
6502 be sure that they get changed to reflect the updated
6503 version of the recipe.
6504 In this scenario, it can get complicated when recipes
6505 that are used in many places and provide common functionality
6506 are upgraded to a new revision.
6507 </para>
6508
6509 <para>
6510 A more efficient way of dealing with this situation is
6511 to set the <filename>INC_PR</filename> variable inside
6512 the <filename>include</filename> files that the recipes
6513 share and then expand the <filename>INC_PR</filename>
6514 variable within the recipes to help
6515 define the recipe revision.
6516 </para>
6517
6518 <para>
6519 The following provides an example that shows how to use
6520 the <filename>INC_PR</filename> variable
6521 given a common <filename>include</filename> file that
6522 defines the variable.
6523 Once the variable is defined in the
6524 <filename>include</filename> file, you can use the
6525 variable to set the <filename>PR</filename> values in
6526 each recipe.
6527 You will notice that when you set a recipe's
6528 <filename>PR</filename> you can provide more granular
6529 revisioning by appending values to the
6530 <filename>INC_PR</filename> variable:
6531 <literallayout class='monospaced'>
6532 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
6533 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
6534 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
6535 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
6536 </literallayout>
6537 The first line of the example establishes the baseline
6538 revision to be used for all recipes that use the
6539 <filename>include</filename> file.
6540 The remaining lines in the example are from individual
6541 recipes and show how the <filename>PR</filename> value
6542 is set.
6543 </para>
6544 </glossdef>
6545 </glossentry>
6546
6547 <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
6548 <info>
6549 INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build."
6550 </info>
6551 <glossdef>
6552 <para role="glossdeffirst">
6553 Specifies a space-separated list of license names
6554 (as they would appear in
6555 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
6556 that should be excluded from the build.
6557 Recipes that provide no alternatives to listed incompatible
6558 licenses are not built.
6559 Packages that are individually licensed with the specified
6560 incompatible licenses will be deleted.
6561 </para>
6562
6563 <note>
6564 This functionality is only regularly tested using
6565 the following setting:
6566 <literallayout class='monospaced'>
6567 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
6568 </literallayout>
6569 Although you can use other settings, you might be required
6570 to remove dependencies on or provide alternatives to
6571 components that are required to produce a functional system
6572 image.
6573 </note>
6574
6575 <note><title>Tips</title>
6576 It is possible to define a list of licenses that are allowed
6577 to be used instead of the licenses that are excluded. To do
6578 this, define a
6579 variable <filename>COMPATIBLE_LICENSES</filename> with the
6580 names of the licences that are allowed. Then
6581 define <filename>INCOMPATIBLE_LICENSE</filename> as:
6582 <literallayout class='monospaced'>
6583 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
6584 </literallayout>
6585 This will result
6586 in <filename>INCOMPATIBLE_LICENSE</filename> containing the
6587 names of all licences
6588 from <link linkend='var-AVAILABLE_LICENSES'><filename>AVAILABLE_LICENSES</filename></link>
6589 except the ones specified
6590 in <filename>COMPATIBLE_LICENSES</filename>, thus only
6591 allowing the latter licences to be used.
6592 </note>
6593 </glossdef>
6594 </glossentry>
6595
6596 <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
6597 <info>
6598 INHERIT[doc] = "Causes the named class or classes to be inherited globally."
6599 </info>
6600 <glossdef>
6601 <para role="glossdeffirst">
6602 Causes the named class or classes to be inherited globally.
6603 Anonymous functions in the class or classes
6604 are not executed for the
6605 base configuration and in each individual recipe.
6606 The OpenEmbedded build system ignores changes to
6607 <filename>INHERIT</filename> in individual recipes.
6608 </para>
6609
6610 <para>
6611 For more information on <filename>INHERIT</filename>, see
6612 the
6613 "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>"
6614 section in the Bitbake User Manual.
6615 </para>
6616 </glossdef>
6617 </glossentry>
6618
6619 <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm>
6620 <info>
6621 INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable."
6622 </info>
6623 <glossdef>
6624 <para role="glossdeffirst">
6625 Lists classes that will be inherited at the
6626 distribution level.
6627 It is unlikely that you want to edit this variable.
6628 </para>
6629
6630 <para>
6631 The default value of the variable is set as follows in the
6632 <filename>meta/conf/distro/defaultsetup.conf</filename>
6633 file:
6634 <literallayout class='monospaced'>
6635 INHERIT_DISTRO ?= "debian devshell sstate license"
6636 </literallayout>
6637 </para>
6638 </glossdef>
6639 </glossentry>
6640
6641 <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
6642 <info>
6643 INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS."
6644 </info>
6645 <glossdef>
6646 <para role="glossdeffirst">
6647 Prevents the default dependencies, namely the C compiler
6648 and standard C library (libc), from being added to
6649 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
6650 This variable is usually used within recipes that do not
6651 require any compilation using the C compiler.
6652 </para>
6653
6654 <para>
6655 Set the variable to "1" to prevent the default dependencies
6656 from being added.
6657 </para>
6658 </glossdef>
6659 </glossentry>
6660
6661 <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm>
6662 <info>
6663 INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging"
6664 </info>
6665 <glossdef>
6666 <para role="glossdeffirst">
6667 Prevents the OpenEmbedded build system from splitting
6668 out debug information during packaging.
6669 By default, the build system splits out debugging
6670 information during the
6671 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
6672 task.
6673 For more information on how debug information is split out,
6674 see the
6675 <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link>
6676 variable.
6677 </para>
6678
6679 <para>
6680 To prevent the build system from splitting out
6681 debug information during packaging, set the
6682 <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable
6683 as follows:
6684 <literallayout class='monospaced'>
6685 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
6686 </literallayout>
6687 </para>
6688 </glossdef>
6689 </glossentry>
6690
6691 <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
6692 <info>
6693 INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages."
6694 </info>
6695 <glossdef>
6696 <para role="glossdeffirst">
6697 If set to "1", causes the build to not strip binaries in
6698 resulting packages and prevents the
6699 <filename>-dbg</filename> package from containing the
6700 source files.
6701 </para>
6702
6703 <para>
6704 By default, the OpenEmbedded build system strips
6705 binaries and puts the debugging symbols into
6706 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>.
6707 Consequently, you should not set
6708 <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan
6709 to debug in general.
6710 </para>
6711 </glossdef>
6712 </glossentry>
6713
6714 <glossentry id='var-INHIBIT_SYSROOT_STRIP'><glossterm>INHIBIT_SYSROOT_STRIP</glossterm>
6715 <info>
6716 INHIBIT_SYSROOT_STRIP[doc] = "If set to "1", causes the build to not strip binaries in the resulting sysroot."
6717 </info>
6718 <glossdef>
6719 <para role="glossdeffirst">
6720 If set to "1", causes the build to not strip binaries in
6721 the resulting sysroot.
6722 </para>
6723
6724 <para>
6725 By default, the OpenEmbedded build system strips
6726 binaries in the resulting sysroot.
6727 When you specifically set the
6728 <filename>INHIBIT_SYSROOT_STRIP</filename> variable to
6729 "1" in your recipe, you inhibit this stripping.
6730 </para>
6731
6732 <para>
6733 If you want to use this variable, include the
6734 <link linkend='ref-classes-staging'><filename>staging</filename></link>
6735 class.
6736 This class uses a <filename>sys_strip()</filename>
6737 function to test for the variable and acts accordingly.
6738 <note>
6739 Use of the <filename>INHIBIT_SYSROOT_STRIP</filename>
6740 variable occurs in rare and special circumstances.
6741 For example, suppose you are building bare-metal
6742 firmware by using an external GCC toolchain.
6743 Furthermore, even if the toolchain's binaries are
6744 strippable, other files exist that are needed for the
6745 build that are not strippable.
6746 </note>
6747 </para>
6748 </glossdef>
6749 </glossentry>
6750
6751 <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
6752 <info>
6753 INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM filesystem (initramfs), which is used during boot."
6754 </info>
6755 <glossdef>
6756 <para role="glossdeffirst">
6757 Defines the format for the output image of an initial
6758 RAM filesystem (initramfs), which is used during boot.
6759 Supported formats are the same as those supported by the
6760 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6761 variable.
6762 </para>
6763
6764 <para>
6765 The default value of this variable, which is set in the
6766 <filename>meta/conf/bitbake.conf</filename> configuration
6767 file in the
6768 <link linkend='source-directory'>Source Directory</link>,
6769 is "cpio.gz".
6770 The Linux kernel's initramfs mechanism, as opposed to the
6771 initial RAM filesystem
6772 <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink>
6773 mechanism, expects an optionally compressed cpio
6774 archive.
6775 </para>
6776 </glossdef>
6777 </glossentry>
6778
6779 <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm>
6780 <info>
6781 INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM filesystem (initramfs) image."
6782 </info>
6783 <glossdef>
6784 <para role="glossdeffirst">
6785 Specifies the
6786 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
6787 name of an image recipe that is used to build an initial
6788 RAM filesystem (initramfs) image.
6789 In other words, the <filename>INITRAMFS_IMAGE</filename>
6790 variable causes an additional recipe to be built as
6791 a dependency to whatever root filesystem recipe you
6792 might be using (e.g. <filename>core-image-sato</filename>).
6793 The initramfs image recipe you provide should set
6794 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6795 to
6796 <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>.
6797 </para>
6798
6799 <para>
6800 An initramfs image provides a temporary root filesystem
6801 used for early system initialization (e.g. loading of
6802 modules needed to locate and mount the "real" root
6803 filesystem).
6804 <note>
6805 See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename>
6806 recipe in the
6807 <link linkend='source-directory'>Source Directory</link>
6808 for an example initramfs recipe.
6809 To select this sample recipe as the one built
6810 to provide the initramfs image,
6811 set <filename>INITRAMFS_IMAGE</filename> to
6812 "core-image-minimal-initramfs".
6813 </note>
6814 </para>
6815
6816 <para>
6817 You can also find more information by referencing the
6818 <filename>meta-poky/conf/local.conf.sample.extended</filename>
6819 configuration file in the Source Directory,
6820 the
6821 <link linkend='ref-classes-image'><filename>image</filename></link>
6822 class, and the
6823 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
6824 class to see how to use the
6825 <filename>INITRAMFS_IMAGE</filename> variable.
6826 </para>
6827
6828 <para>
6829 If <filename>INITRAMFS_IMAGE</filename> is empty, which is
6830 the default, then no initramfs image is built.
6831 </para>
6832
6833 <para>
6834 For more information, you can also see the
6835 <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link>
6836 variable, which allows the generated image to be bundled
6837 inside the kernel image.
6838 Additionally, for information on creating an initramfs
6839 image, see the
6840 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
6841 section in the Yocto Project Development Tasks Manual.
6842 </para>
6843 </glossdef>
6844 </glossentry>
6845
6846 <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm>
6847 <info>
6848 INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM filesystem (initramfs)."
6849 </info>
6850 <glossdef>
6851 <para role="glossdeffirst">
6852 Controls whether or not the image recipe specified by
6853 <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link>
6854 is run through an extra pass
6855 (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>)
6856 during kernel compilation in order to build a single binary
6857 that contains both the kernel image and the initial RAM
6858 filesystem (initramfs) image.
6859 This makes use of the
6860 <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link>
6861 kernel feature.
6862 <note>
6863 Using an extra compilation pass to bundle the initramfs
6864 avoids a circular dependency between the kernel recipe and
6865 the initramfs recipe should the initramfs include kernel
6866 modules.
6867 Should that be the case, the initramfs recipe depends on
6868 the kernel for the kernel modules, and the kernel depends
6869 on the initramfs recipe since the initramfs is bundled
6870 inside the kernel image.
6871 </note>
6872 </para>
6873
6874 <para>
6875 The combined binary is deposited into the
6876 <filename>tmp/deploy</filename> directory, which is part
6877 of the
6878 <link linkend='build-directory'>Build Directory</link>.
6879 </para>
6880
6881 <para>
6882 Setting the variable to "1" in a configuration file causes the
6883 OpenEmbedded build system to generate a kernel image with the
6884 initramfs specified in <filename>INITRAMFS_IMAGE</filename>
6885 bundled within:
6886 <literallayout class='monospaced'>
6887 INITRAMFS_IMAGE_BUNDLE = "1"
6888 </literallayout>
6889 By default, the
6890 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
6891 class sets this variable to a null string as follows:
6892 <literallayout class='monospaced'>
6893 INITRAMFS_IMAGE_BUNDLE ?= ""
6894 </literallayout>
6895 <note>
6896 You must set the
6897 <filename>INITRAMFS_IMAGE_BUNDLE</filename> variable in
6898 a configuration file.
6899 You cannot set the variable in a recipe file.
6900 </note>
6901 See the
6902 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink>
6903 file for additional information.
6904 Also, for information on creating an initramfs, see the
6905 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
6906 section in the Yocto Project Development Tasks Manual.
6907 </para>
6908 </glossdef>
6909 </glossentry>
6910
6911 <glossentry id='var-INITRAMFS_LINK_NAME'><glossterm>INITRAMFS_LINK_NAME</glossterm>
6912 <info>
6913 INITRAMFS_LINK_NAME[doc] = "The link name of the initial RAM filesystem image."
6914 </info>
6915 <glossdef>
6916 <para role="glossdeffirst">
6917 The link name of the initial RAM filesystem image.
6918 This variable is set in the
6919 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
6920 file as follows:
6921 <literallayout class='monospaced'>
6922 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
6923 </literallayout>
6924 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
6925 variable, which is set in the same file, has the following
6926 value:
6927 <literallayout class='monospaced'>
6928 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
6929 </literallayout>
6930 </para>
6931
6932 <para>
6933 See the
6934 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
6935 variable for additional information.
6936 </para>
6937 </glossdef>
6938 </glossentry>
6939
6940 <glossentry id='var-INITRAMFS_NAME'><glossterm>INITRAMFS_NAME</glossterm>
6941 <info>
6942 INITRAMFS_NAME[doc] = "The base name of the initial RAM filesystem image."
6943 </info>
6944 <glossdef>
6945 <para role="glossdeffirst">
6946 The base name of the initial RAM filesystem image.
6947 This variable is set in the
6948 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
6949 file as follows:
6950 <literallayout class='monospaced'>
6951 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
6952 </literallayout>
6953 The value of the
6954 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
6955 variable, which is set in the same file, has the following
6956 value:
6957 <literallayout class='monospaced'>
6958 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
6959 </literallayout>
6960 </para>
6961 </glossdef>
6962 </glossentry>
6963
6964 <glossentry id='var-INITRD'><glossterm>INITRD</glossterm>
6965 <info>
6966 INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)."
6967 </info>
6968 <glossdef>
6969 <para role="glossdeffirst">
6970 Indicates list of filesystem images to concatenate and use
6971 as an initial RAM disk (<filename>initrd</filename>).
6972 </para>
6973
6974 <para>
6975 The <filename>INITRD</filename> variable is an optional
6976 variable used with the
6977 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
6978 class.
6979 </para>
6980 </glossdef>
6981 </glossentry>
6982
6983 <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm>
6984 <info>
6985 INITRD_IMAGE[doc] = "When building a "live" bootable image (i.e. when IMAGE_FSTYPES contains "live"), INITRD_IMAGE specifies the image recipe that should be built to provide the initial RAM disk image."
6986 </info>
6987 <glossdef>
6988 <para role="glossdeffirst">
6989 When building a "live" bootable image (i.e. when
6990 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
6991 contains "live"), <filename>INITRD_IMAGE</filename>
6992 specifies the image recipe that should be built
6993 to provide the initial RAM disk image.
6994 The default value is "core-image-minimal-initramfs".
6995 </para>
6996
6997 <para>
6998 See the
6999 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
7000 class for more information.
7001 </para>
7002 </glossdef>
7003 </glossentry>
7004
7005 <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
7006 <info>
7007 INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d."
7008 </info>
7009 <glossdef>
7010 <para role="glossdeffirst">
7011 The filename of the initialization script as installed to
7012 <filename>${sysconfdir}/init.d</filename>.
7013 </para>
7014
7015 <para>
7016 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7017 The variable is mandatory.
7018 </para>
7019 </glossdef>
7020 </glossentry>
7021
7022 <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
7023 <info>
7024 INITSCRIPT_PACKAGES[doc] = "A list of the packages that contain initscripts. This variable is used in recipes when using update-rc.d.bbclass. The variable is optional and defaults to the PN variable."
7025 </info>
7026 <glossdef>
7027 <para role="glossdeffirst">
7028 A list of the packages that contain initscripts.
7029 If multiple packages are specified, you need to append the package name
7030 to the other <filename>INITSCRIPT_*</filename> as an override.
7031 </para>
7032
7033 <para>
7034 This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
7035 The variable is optional and defaults to the
7036 <link linkend='var-PN'><filename>PN</filename></link> variable.
7037 </para>
7038 </glossdef>
7039 </glossentry>
7040
7041 <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
7042 <info>
7043 INITSCRIPT_PARAMS[doc] = "Specifies the options to pass to update-rc.d. The variable is mandatory and is used in recipes when using update-rc.d.bbclass."
7044 </info>
7045 <glossdef>
7046 <para role="glossdeffirst">
7047 Specifies the options to pass to <filename>update-rc.d</filename>.
7048 Here is an example:
7049 <literallayout class='monospaced'>
7050 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
7051 </literallayout>
7052 </para>
7053
7054 <para>
7055 In this example, the script has a runlevel of 99,
7056 starts the script in initlevels 2 and 5, and
7057 stops the script in levels 0, 1 and 6.
7058 </para>
7059
7060 <para>
7061 The variable's default value is "defaults", which is
7062 set in the
7063 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
7064 class.
7065 </para>
7066
7067 <para>
7068 The value in
7069 <filename>INITSCRIPT_PARAMS</filename> is passed through
7070 to the <filename>update-rc.d</filename> command.
7071 For more information on valid parameters, please see the
7072 <filename>update-rc.d</filename> manual page at
7073 <ulink url='http://www.tin.org/bin/man.cgi?section=8&amp;topic=update-rc.d'></ulink>.
7074 </para>
7075 </glossdef>
7076 </glossentry>
7077
7078 <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
7079 <info>
7080 INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe."
7081 </info>
7082 <glossdef>
7083 <para role="glossdeffirst">
7084 Specifies the QA checks to skip for a specific package
7085 within a recipe.
7086 For example, to skip the check for symbolic link
7087 <filename>.so</filename> files in the main package of a
7088 recipe, add the following to the recipe.
7089 The package name override must be used, which in this
7090 example is <filename>${PN}</filename>:
7091 <literallayout class='monospaced'>
7092 INSANE_SKIP_${PN} += "dev-so"
7093 </literallayout>
7094 </para>
7095
7096 <para>
7097 See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
7098 section for a list of the valid QA checks you can
7099 specify using this variable.
7100 </para>
7101 </glossdef>
7102 </glossentry>
7103
7104 <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm>
7105 <info>
7106 INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file."
7107 </info>
7108 <glossdef>
7109 <para role="glossdeffirst">
7110 By default, the <filename>tzdata</filename> recipe packages
7111 an <filename>/etc/timezone</filename> file.
7112 Set the <filename>INSTALL_TIMEZONE_FILE</filename>
7113 variable to "0" at the configuration level to disable this
7114 behavior.
7115 </para>
7116 </glossdef>
7117 </glossentry>
7118
7119 <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
7120 <info>
7121 IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image."
7122 </info>
7123 <glossdef>
7124 <para role="glossdeffirst">
7125 When the IPK backend is in use and package management
7126 is enabled on the target, you can use this variable to
7127 set up <filename>opkg</filename> in the target image
7128 to point to package feeds on a nominated server.
7129 Once the feed is established, you can perform
7130 installations or upgrades using the package manager
7131 at runtime.
7132 </para>
7133 </glossdef>
7134 </glossentry>
7135
7136<!--
7137 <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
7138 <glossdef>
7139 <para>
7140 An environment variable that defines the directory where
7141 post installation hooks are installed for the
7142 post install environment.
7143 This variable is fixed as follows:
7144 <literallayout class='monospaced'>
7145 ${WORKDIR}/intercept_scripts
7146 </literallayout>
7147 </para>
7148
7149 <para>
7150 After installation of a target's root filesystem,
7151 post installation scripts, which are essentially bash scripts,
7152 are all executed just a single time.
7153 Limiting execution of these scripts minimizes installation
7154 time that would be lengthened due to certain packages
7155 triggering redundant operations.
7156 For example, consider the installation of font packages
7157 as a common example.
7158 Without limiting the execution of post installation scripts,
7159 all font directories would be rescanned to create the
7160 cache after each individual font package was installed.
7161 </para>
7162
7163 <para>
7164 Do not edit the <filename>INTERCEPT_DIR</filename>
7165 variable.
7166 </para>
7167 </glossdef>
7168 </glossentry>
7169-->
7170
7171 </glossdiv>
7172
7173<!-- <glossdiv id='var-glossary-j'><title>J</title>-->
7174<!-- </glossdiv>-->
7175
7176 <glossdiv id='var-glossary-k'><title>K</title>
7177
7178 <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
7179 <info>
7180 KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions."
7181 </info>
7182 <glossdef>
7183 <para role="glossdeffirst">
7184 Defines the kernel architecture used when assembling
7185 the configuration.
7186 Architectures supported for this release are:
7187 <literallayout class='monospaced'>
7188 powerpc
7189 i386
7190 x86_64
7191 arm
7192 qemu
7193 mips
7194 </literallayout>
7195 </para>
7196
7197 <para>
7198 You define the <filename>KARCH</filename> variable in the
7199 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7200 </para>
7201 </glossdef>
7202 </glossentry>
7203
7204 <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
7205 <info>
7206 KBRANCH[doc] = "A regular expression used by the build process to explicitly identify the kernel branch that is validated, patched, and configured during a build."
7207 </info>
7208 <glossdef>
7209 <para role="glossdeffirst">
7210 A regular expression used by the build process to explicitly
7211 identify the kernel branch that is validated, patched,
7212 and configured during a build.
7213 You must set this variable to ensure the exact kernel
7214 branch you want is being used by the build process.
7215 </para>
7216
7217 <para>
7218 Values for this variable are set in the kernel's recipe
7219 file and the kernel's append file.
7220 For example, if you are using the
7221 <filename>linux-yocto_4.12</filename> kernel, the kernel
7222 recipe file is the
7223 <filename>meta/recipes-kernel/linux/linux-yocto_4.12.bb</filename>
7224 file.
7225 <filename>KBRANCH</filename> is set as follows in that
7226 kernel recipe file:
7227 <literallayout class='monospaced'>
7228 KBRANCH ?= "standard/base"
7229 </literallayout>
7230 </para>
7231
7232 <para>
7233 This variable is also used from the kernel's append file
7234 to identify the kernel branch specific to a particular
7235 machine or target hardware.
7236 Continuing with the previous kernel example, the kernel's
7237 append file (i.e.
7238 <filename>linux-yocto_4.12.bbappend</filename>) is located
7239 in the BSP layer for a given machine.
7240 For example, the append file for the Beaglebone,
7241 EdgeRouter, and generic versions of both 32 and 64-bit IA
7242 machines (<filename>meta-yocto-bsp</filename>) is named
7243 <filename>meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend</filename>.
7244 Here are the related statements from that append file:
7245 <literallayout class='monospaced'>
7246 KBRANCH_genericx86 = "standard/base"
7247 KBRANCH_genericx86-64 = "standard/base"
7248 KBRANCH_edgerouter = "standard/edgerouter"
7249 KBRANCH_beaglebone = "standard/beaglebone"
7250 </literallayout>
7251 The <filename>KBRANCH</filename> statements identify
7252 the kernel branch to use when building for each
7253 supported BSP.
7254 </para>
7255 </glossdef>
7256 </glossentry>
7257
7258 <glossentry id='var-KBUILD_DEFCONFIG'><glossterm>KBUILD_DEFCONFIG</glossterm>
7259 <info>
7260 KBUILD_DEFCONFIG[doc] = "Specifies an "in-tree" kernel configuration file for use during a kernel build."
7261 </info>
7262 <glossdef>
7263 <para role="glossdeffirst">
7264 When used with the
7265 <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link>
7266 class, specifies an "in-tree" kernel configuration file
7267 for use during a kernel build.
7268 </para>
7269
7270 <para>
7271 Typically, when using a <filename>defconfig</filename> to
7272 configure a kernel during a build, you place the
7273 file in your layer in the same manner as you would
7274 place patch files and configuration fragment files (i.e.
7275 "out-of-tree").
7276 However, if you want to use a <filename>defconfig</filename>
7277 file that is part of the kernel tree (i.e. "in-tree"),
7278 you can use the
7279 <filename>KBUILD_DEFCONFIG</filename> variable and append
7280 the
7281 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7282 variable to point to the <filename>defconfig</filename>
7283 file.
7284 </para>
7285
7286 <para>
7287 To use the variable, set it in the append file for your
7288 kernel recipe using the following form:
7289 <literallayout class='monospaced'>
7290 KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
7291 </literallayout>
7292 Here is an example from a "raspberrypi2"
7293 <filename>KMACHINE</filename> build that uses a
7294 <filename>defconfig</filename> file named
7295 "bcm2709_defconfig":
7296 <literallayout class='monospaced'>
7297 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
7298 </literallayout>
7299 As an alternative, you can use the following within your
7300 append file:
7301 <literallayout class='monospaced'>
7302 KBUILD_DEFCONFIG_pn-linux-yocto ?= <replaceable>defconfig_file</replaceable>
7303 </literallayout>
7304 For more information on how to use the
7305 <filename>KBUILD_DEFCONFIG</filename> variable, see the
7306 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file'>Using an "In-Tree" <filename>defconfig</filename> File</ulink>"
7307 section in the Yocto Project Linux Kernel Development
7308 Manual.
7309 </para>
7310 </glossdef>
7311 </glossentry>
7312
7313 <glossentry id='var-KERNEL_ALT_IMAGETYPE'><glossterm>KERNEL_ALT_IMAGETYPE</glossterm>
7314 <info>
7315 KERNEL_ALT_IMAGETYPE[doc] = "Specifies an alternate kernel image type for creation."
7316 </info>
7317 <glossdef>
7318 <para role="glossdeffirst">
7319 Specifies an alternate kernel image type for creation in
7320 addition to the kernel image type specified using the
7321 <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
7322 variable.
7323 </para>
7324 </glossdef>
7325 </glossentry>
7326
7327 <glossentry id='var-KERNEL_ARTIFACT_NAME'><glossterm>KERNEL_ARTIFACT_NAME</glossterm>
7328 <info>
7329 KERNEL_ARTIFACT_NAME[doc] = "Specifies the name of all of the build artifacts."
7330 </info>
7331 <glossdef>
7332 <para role="glossdeffirst">
7333 Specifies the name of all of the build artifacts.
7334 You can change the name of the artifacts by changing the
7335 <filename>KERNEL_ARTIFACT_NAME</filename> variable.
7336 </para>
7337
7338 <para>
7339 The value of <filename>KERNEL_ARTIFACT_NAME</filename>,
7340 which is set in the
7341 <filename> meta/classes/kernel-artifact-names.bbclass</filename>
7342 file, has the following default value:
7343 <literallayout class='monospaced'>
7344 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7345 </literallayout>
7346 </para>
7347
7348 <para>
7349 See the
7350 <link linkend='var-PKGE'><filename>PKGE</filename></link>,
7351 <link linkend='var-PKGV'><filename>PKGV</filename></link>,
7352 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
7353 and
7354 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7355 variables for additional information.
7356 <note>
7357 The <filename>IMAGE_VERSION_SUFFIX</filename> variable
7358 is set to
7359 <link linkend='var-DATETIME'><filename>DATETIME</filename></link>.
7360 </note>
7361 </para>
7362 </glossdef>
7363 </glossentry>
7364
7365 <glossentry id='var-KERNEL_CLASSES'><glossterm>KERNEL_CLASSES</glossterm>
7366 <info>
7367 KERNEL_CLASSES[doc] = "A list of classes defining kernel image types that kernel class should inherit."
7368 </info>
7369 <glossdef>
7370 <para role="glossdeffirst">
7371 A list of classes defining kernel image types that the
7372 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
7373 class should inherit.
7374 You typically append this variable to enable extended image
7375 types.
7376 An example is the "kernel-fitimage", which enables
7377 fitImage support and resides in
7378 <filename>meta/classes/kernel-fitimage.bbclass</filename>.
7379 You can register custom kernel image types with the
7380 <filename>kernel</filename> class using this variable.
7381 </para>
7382 </glossdef>
7383 </glossentry>
7384
7385 <glossentry id='var-KERNEL_DEVICETREE'><glossterm>KERNEL_DEVICETREE</glossterm>
7386 <info>
7387 KERNEL_DEVICETREE[doc] = "Specifies the name of the generated Linux kernel device tree (i.e. the .dtb) file."
7388 </info>
7389 <glossdef>
7390 <para role="glossdeffirst">
7391 Specifies the name of the generated Linux kernel device tree
7392 (i.e. the <filename>.dtb</filename>) file.
7393 <note>
7394 Legacy support exists for specifying the full path
7395 to the device tree.
7396 However, providing just the <filename>.dtb</filename>
7397 file is preferred.
7398 </note>
7399 In order to use this variable, the
7400 <link linkend='ref-classes-kernel-devicetree'><filename>kernel-devicetree</filename></link>
7401 class must be inherited.
7402 </para>
7403 </glossdef>
7404 </glossentry>
7405
7406 <glossentry id='var-KERNEL_DTB_LINK_NAME'><glossterm>KERNEL_DTB_LINK_NAME</glossterm>
7407 <info>
7408 KERNEL_DTB_LINK_NAME[doc] = "The link name of the kernel device tree binary (DTB)."
7409 </info>
7410 <glossdef>
7411 <para role="glossdeffirst">
7412 The link name of the kernel device tree binary (DTB).
7413 This variable is set in the
7414 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7415 file as follows:
7416 <literallayout class='monospaced'>
7417 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7418 </literallayout>
7419 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7420 variable, which is set in the same file, has the following
7421 value:
7422 <literallayout class='monospaced'>
7423 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7424 </literallayout>
7425 </para>
7426
7427 <para>
7428 See the
7429 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7430 variable for additional information.
7431 </para>
7432 </glossdef>
7433 </glossentry>
7434
7435 <glossentry id='var-KERNEL_DTB_NAME'><glossterm>KERNEL_DTB_NAME</glossterm>
7436 <info>
7437 KERNEL_DTB_NAME[doc] = "The base name of the kernel device tree binary (DTB)."
7438 </info>
7439 <glossdef>
7440 <para role="glossdeffirst">
7441 The base name of the kernel device tree binary (DTB).
7442 This variable is set in the
7443 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7444 file as follows:
7445 <literallayout class='monospaced'>
7446 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7447 </literallayout>
7448 The value of the
7449 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7450 variable, which is set in the same file, has the following
7451 value:
7452 <literallayout class='monospaced'>
7453 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7454 </literallayout>
7455 </para>
7456 </glossdef>
7457 </glossentry>
7458
7459 <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
7460 <info>
7461 KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel."
7462 </info>
7463 <glossdef>
7464 <para role="glossdeffirst">
7465 Specifies additional <filename>make</filename>
7466 command-line arguments the OpenEmbedded build system
7467 passes on when compiling the kernel.
7468 </para>
7469 </glossdef>
7470 </glossentry>
7471
7472 <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
7473 <info>
7474 KERNEL_FEATURES[doc] = "Includes additional kernel metadata. The metadata you add through this variable includes config fragments and features descriptions."
7475 </info>
7476 <glossdef>
7477 <para role="glossdeffirst">
7478 Includes additional kernel metadata.
7479 In the OpenEmbedded build system, the default Board Support
7480 Packages (BSPs)
7481 <link linkend='metadata'>Metadata</link>
7482 is provided through
7483 the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
7484 and
7485 <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>
7486 variables.
7487 You can use the <filename>KERNEL_FEATURES</filename>
7488 variable from within the kernel recipe or kernel append
7489 file to further add metadata for all BSPs or specific
7490 BSPs.
7491 </para>
7492
7493 <para>
7494 The metadata you add through this variable includes config
7495 fragments and features descriptions,
7496 which usually includes patches as well as config fragments.
7497 You typically override the
7498 <filename>KERNEL_FEATURES</filename> variable for a
7499 specific machine.
7500 In this way, you can provide validated, but optional,
7501 sets of kernel configurations and features.
7502 </para>
7503
7504 <para>
7505 For example, the following example from the
7506 <filename>linux-yocto-rt_4.12</filename> kernel recipe
7507 adds "netfilter" and "taskstats" features to all BSPs
7508 as well as "virtio" configurations to all QEMU machines.
7509 The last two statements add specific configurations to
7510 targeted machine types:
7511 <literallayout class='monospaced'>
7512 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
7513 KERNEL_FEATURES_append = " ${KERNEL_EXTRA_FEATURES}"
7514 KERNEL_FEATURES_append_qemuall = " cfg/virtio.scc"
7515 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
7516 KERNEL_FEATURES_append_qemux86-64 = " cfg/sound.scc" </literallayout></para>
7517 </glossdef>
7518 </glossentry>
7519
7520 <glossentry id='var-KERNEL_FIT_LINK_NAME'><glossterm>KERNEL_FIT_LINK_NAME</glossterm>
7521 <info>
7522 KERNEL_FIT_LINK_NAME[doc] = "The link name of the kernel flattened image tree (FIT) image."
7523 </info>
7524 <glossdef>
7525 <para role="glossdeffirst">
7526 The link name of the kernel flattened image tree (FIT) image.
7527 This variable is set in the
7528 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7529 file as follows:
7530 <literallayout class='monospaced'>
7531 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7532 </literallayout>
7533 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7534 variable, which is set in the same file, has the following
7535 value:
7536 <literallayout class='monospaced'>
7537 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7538 </literallayout>
7539 </para>
7540
7541 <para>
7542 See the
7543 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7544 variable for additional information.
7545 </para>
7546 </glossdef>
7547 </glossentry>
7548
7549 <glossentry id='var-KERNEL_FIT_NAME'><glossterm>KERNEL_FIT_NAME</glossterm>
7550 <info>
7551 KERNEL_FIT_NAME[doc] = "The base name of the kernel flattened image tree (FIT) image."
7552 </info>
7553 <glossdef>
7554 <para role="glossdeffirst">
7555 The base name of the kernel flattened image tree (FIT) image.
7556 This variable is set in the
7557 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7558 file as follows:
7559 <literallayout class='monospaced'>
7560 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7561 </literallayout>
7562 The value of the
7563 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7564 variable, which is set in the same file, has the following
7565 value:
7566 <literallayout class='monospaced'>
7567 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7568 </literallayout>
7569 </para>
7570 </glossdef>
7571 </glossentry>
7572
7573 <glossentry id='var-KERNEL_IMAGE_LINK_NAME'><glossterm>KERNEL_IMAGE_LINK_NAME</glossterm>
7574 <info>
7575 KERNEL_IMAGE_LINK_NAME[doc] = "The link name for the kernel image."
7576 </info>
7577 <glossdef>
7578 <para role="glossdeffirst">
7579 The link name for the kernel image.
7580 This variable is set in the
7581 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7582 file as follows:
7583 <literallayout class='monospaced'>
7584 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
7585 </literallayout>
7586 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
7587 variable, which is set in the same file, has the following
7588 value:
7589 <literallayout class='monospaced'>
7590 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
7591 </literallayout>
7592 </para>
7593
7594 <para>
7595 See the
7596 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
7597 variable for additional information.
7598 </para>
7599 </glossdef>
7600 </glossentry>
7601
7602 <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm>
7603 <info>
7604 KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file."
7605 </info>
7606 <glossdef>
7607 <para role="glossdeffirst">
7608 Specifies the maximum size of the kernel image file in
7609 kilobytes.
7610 If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set,
7611 the size of the kernel image file is checked against
7612 the set value during the
7613 <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link>
7614 task.
7615 The task fails if the kernel image file is larger than
7616 the setting.
7617 </para>
7618
7619 <para>
7620 <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for
7621 target devices that have a limited amount of space in
7622 which the kernel image must be stored.
7623 </para>
7624
7625 <para>
7626 By default, this variable is not set, which means the
7627 size of the kernel image is not checked.
7628 </para>
7629 </glossdef>
7630 </glossentry>
7631
7632 <glossentry id='var-KERNEL_IMAGE_NAME'><glossterm>KERNEL_IMAGE_NAME</glossterm>
7633 <info>
7634 KERNEL_IMAGE_NAME[doc] = "The base name of the kernel image."
7635 </info>
7636 <glossdef>
7637 <para role="glossdeffirst">
7638 The base name of the kernel image.
7639 This variable is set in the
7640 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
7641 file as follows:
7642 <literallayout class='monospaced'>
7643 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
7644 </literallayout>
7645 The value of the
7646 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
7647 variable, which is set in the same file, has the following
7648 value:
7649 <literallayout class='monospaced'>
7650 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
7651 </literallayout>
7652 </para>
7653 </glossdef>
7654 </glossentry>
7655
7656 <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
7657 <info>
7658 KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'."
7659 </info>
7660 <glossdef>
7661 <para role="glossdeffirst">
7662 The type of kernel to build for a device, usually set by the
7663 machine configuration files and defaults to "zImage".
7664 This variable is used
7665 when building the kernel and is passed to <filename>make</filename> as the target to
7666 build.
7667 </para>
7668
7669 <para>
7670 If you want to build an alternate kernel image type, use the
7671 <link linkend='var-KERNEL_ALT_IMAGETYPE'><filename>KERNEL_ALT_IMAGETYPE</filename></link>
7672 variable.
7673 </para>
7674 </glossdef>
7675 </glossentry>
7676
7677 <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm>
7678 <info>
7679 KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot"
7680 </info>
7681 <glossdef>
7682 <para role="glossdeffirst">
7683 Lists kernel modules that need to be auto-loaded during
7684 boot.
7685 <note>
7686 This variable replaces the deprecated
7687 <link linkend='var-module_autoload'><filename>module_autoload</filename></link>
7688 variable.
7689 </note>
7690 </para>
7691
7692 <para>
7693 You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename>
7694 variable anywhere that it can be
7695 recognized by the kernel recipe or by an out-of-tree kernel
7696 module recipe (e.g. a machine configuration file, a
7697 distribution configuration file, an append file for the
7698 recipe, or the recipe itself).
7699 </para>
7700
7701 <para>
7702 Specify it as follows:
7703 <literallayout class='monospaced'>
7704 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>"
7705 </literallayout>
7706 </para>
7707
7708 <para>
7709 Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes
7710 the OpenEmbedded build system to populate the
7711 <filename>/etc/modules-load.d/modname.conf</filename>
7712 file with the list of modules to be auto-loaded on boot.
7713 The modules appear one-per-line in the file.
7714 Here is an example of the most common use case:
7715 <literallayout class='monospaced'>
7716 KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>"
7717 </literallayout>
7718 </para>
7719
7720 <para>
7721 For information on how to populate the
7722 <filename>modname.conf</filename> file with
7723 <filename>modprobe.d</filename> syntax lines, see the
7724 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
7725 variable.
7726 </para>
7727 </glossdef>
7728 </glossentry>
7729
7730 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
7731 <info>
7732 KERNEL_MODULE_PROBECONF[doc] = "Lists kernel modules for which the build system expects to find module_conf_* values that specify configuration for each of the modules."
7733 </info>
7734 <glossdef>
7735 <para role="glossdeffirst">
7736 Provides a list of modules for which the OpenEmbedded
7737 build system expects to find
7738 <filename>module_conf_</filename><replaceable>modname</replaceable>
7739 values that specify configuration for each of the modules.
7740 For information on how to provide those module
7741 configurations, see the
7742 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
7743 variable.
7744 </para>
7745 </glossdef>
7746 </glossentry>
7747
7748 <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
7749 <info>
7750 KERNEL_PATH[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."
7751 </info>
7752 <glossdef>
7753 <para role="glossdeffirst">
7754 The location of the kernel sources.
7755 This variable is set to the value of the
7756 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7757 within the
7758 <link linkend='ref-classes-module'><filename>module</filename></link>
7759 class.
7760 For information on how this variable is used, see the
7761 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
7762 section in the Yocto Project Linux Kernel Development
7763 Manual.
7764 </para>
7765
7766 <para>
7767 To help maximize compatibility with out-of-tree drivers
7768 used to build modules, the OpenEmbedded build system also
7769 recognizes and uses the
7770 <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
7771 variable, which is identical to the
7772 <filename>KERNEL_PATH</filename> variable.
7773 Both variables are common variables used by external
7774 Makefiles to point to the kernel source directory.
7775 </para>
7776 </glossdef>
7777 </glossentry>
7778
7779 <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
7780 <info>
7781 KERNEL_SRC[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)."
7782 </info>
7783 <glossdef>
7784 <para role="glossdeffirst">
7785 The location of the kernel sources.
7786 This variable is set to the value of the
7787 <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
7788 within the
7789 <link linkend='ref-classes-module'><filename>module</filename></link>
7790 class.
7791 For information on how this variable is used, see the
7792 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
7793 section in the Yocto Project Linux Kernel Development
7794 Manual.
7795 </para>
7796
7797 <para>
7798 To help maximize compatibility with out-of-tree drivers
7799 used to build modules, the OpenEmbedded build system also
7800 recognizes and uses the
7801 <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
7802 variable, which is identical to the
7803 <filename>KERNEL_SRC</filename> variable.
7804 Both variables are common variables used by external
7805 Makefiles to point to the kernel source directory.
7806 </para>
7807 </glossdef>
7808 </glossentry>
7809
7810 <glossentry id='var-KERNEL_VERSION'><glossterm>KERNEL_VERSION</glossterm>
7811 <info>
7812 KERNEL_VERSION[doc] = "Specifies the version of the kernel as extracted from version.h or utsrelease.h within the kernel sources."
7813 </info>
7814 <glossdef>
7815 <para role="glossdeffirst">
7816 Specifies the version of the kernel as extracted from
7817 <filename>version.h</filename> or
7818 <filename>utsrelease.h</filename> within the kernel sources.
7819 Effects of setting this variable do not take affect until
7820 the kernel has been configured.
7821 Consequently, attempting to refer to this variable in
7822 contexts prior to configuration will not work.
7823 </para>
7824 </glossdef>
7825 </glossentry>
7826
7827 <glossentry id='var-KERNELDEPMODDEPEND'><glossterm>KERNELDEPMODDEPEND</glossterm>
7828 <info>
7829 KERNELDEPMODDEPEND[doc] = "Specifies whether or not to use the data referenced through the PKGDATA_DIR directory."
7830 </info>
7831 <glossdef>
7832 <para role="glossdeffirst">
7833 Specifies whether the data referenced through
7834 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
7835 is needed or not.
7836 The <filename>KERNELDEPMODDEPEND</filename> does not
7837 control whether or not that data exists,
7838 but simply whether or not it is used.
7839 If you do not need to use the data, set the
7840 <filename>KERNELDEPMODDEPEND</filename> variable in your
7841 <filename>initramfs</filename> recipe.
7842 Setting the variable there when the data is not needed
7843 avoids a potential dependency loop.
7844 </para>
7845 </glossdef>
7846 </glossentry>
7847
7848 <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
7849 <info>
7850 KFEATURE_DESCRIPTION[doc] = "Provides a short description of a configuration fragment. You use this variable in the .scc file that describes a configuration fragment file."
7851 </info>
7852 <glossdef>
7853 <para role="glossdeffirst">
7854 Provides a short description of a configuration fragment.
7855 You use this variable in the <filename>.scc</filename>
7856 file that describes a configuration fragment file.
7857 Here is the variable used in a file named
7858 <filename>smp.scc</filename> to describe SMP being
7859 enabled:
7860 <literallayout class='monospaced'>
7861 define KFEATURE_DESCRIPTION "Enable SMP"
7862 </literallayout>
7863 </para>
7864 </glossdef>
7865 </glossentry>
7866
7867 <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
7868 <info>
7869 KMACHINE[doc] = "The machine as known by the kernel."
7870 </info>
7871 <glossdef>
7872 <para role="glossdeffirst">
7873 The machine as known by the kernel.
7874 Sometimes the machine name used by the kernel does not
7875 match the machine name used by the OpenEmbedded build
7876 system.
7877 For example, the machine name that the OpenEmbedded build
7878 system understands as
7879 <filename>core2-32-intel-common</filename> goes by a
7880 different name in the Linux Yocto kernel.
7881 The kernel understands that machine as
7882 <filename>intel-core2-32</filename>.
7883 For cases like these, the <filename>KMACHINE</filename>
7884 variable maps the kernel machine name to the OpenEmbedded
7885 build system machine name.
7886 </para>
7887
7888 <para>
7889 These mappings between different names occur in the
7890 Yocto Linux Kernel's <filename>meta</filename> branch.
7891 As an example take a look in the
7892 <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename>
7893 file:
7894 <literallayout class='monospaced'>
7895 LINUX_VERSION_core2-32-intel-common = "3.19.0"
7896 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
7897 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
7898 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
7899 KMACHINE_core2-32-intel-common = "intel-core2-32"
7900 KBRANCH_core2-32-intel-common = "standard/base"
7901 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
7902 </literallayout>
7903 The <filename>KMACHINE</filename> statement says that
7904 the kernel understands the machine name as
7905 "intel-core2-32".
7906 However, the OpenEmbedded build system understands the
7907 machine as "core2-32-intel-common".
7908 </para>
7909
7910 </glossdef>
7911 </glossentry>
7912
7913 <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
7914 <info>
7915 KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
7916 </info>
7917 <glossdef>
7918 <para role="glossdeffirst">
7919 Defines the kernel type to be used in assembling the
7920 configuration.
7921 The linux-yocto recipes define "standard", "tiny",
7922 and "preempt-rt" kernel types.
7923 See the
7924 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
7925 section in the Yocto Project Linux Kernel Development
7926 Manual for more information on kernel types.
7927 </para>
7928
7929 <para>
7930 You define the <filename>KTYPE</filename> variable in the
7931 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
7932 The value you use must match the value used for the
7933 <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
7934 value used by the kernel recipe.
7935 </para>
7936 </glossdef>
7937 </glossentry>
7938 </glossdiv>
7939
7940 <glossdiv id='var-glossary-l'><title>L</title>
7941
7942 <glossentry id='var-LABELS'><glossterm>LABELS</glossterm>
7943 <info>
7944 LABELS[doc] = "Provides a list of targets for automatic configuration."
7945 </info>
7946 <glossdef>
7947 <para role="glossdeffirst">
7948 Provides a list of targets for automatic configuration.
7949 </para>
7950
7951 <para>
7952 See the
7953 <link linkend='ref-classes-grub-efi'><filename>grub-efi</filename></link>
7954 class for more information on how this variable is used.
7955 </para>
7956 </glossdef>
7957 </glossentry>
7958
7959 <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
7960 <info>
7961 LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, on which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."
7962 </info>
7963 <glossdef>
7964 <para role="glossdeffirst">
7965 Lists the layers, separated by spaces, on which this
7966 recipe depends.
7967 Optionally, you can specify a specific layer version for a
7968 dependency by adding it to the end of the layer name.
7969 Here is an example:
7970 <literallayout class='monospaced'>
7971 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
7972 </literallayout>
7973 In this previous example, version 3 of "anotherlayer"
7974 is compared against
7975 <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>.
7976 </para>
7977
7978 <para>
7979 An error is produced if any dependency is missing or
7980 the version numbers (if specified) do not match exactly.
7981 This variable is used in the
7982 <filename>conf/layer.conf</filename> file and must be
7983 suffixed with the name of the specific layer (e.g.
7984 <filename>LAYERDEPENDS_mylayer</filename>).
7985 </para>
7986 </glossdef>
7987 </glossentry>
7988
7989 <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
7990 <info>
7991 LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer."
7992 </info>
7993 <glossdef>
7994 <para role="glossdeffirst">
7995 When used inside the <filename>layer.conf</filename> configuration
7996 file, this variable provides the path of the current layer.
7997 This variable is not available outside of <filename>layer.conf</filename>
7998 and references are expanded immediately when parsing of the file completes.
7999 </para>
8000 </glossdef>
8001 </glossentry>
8002
8003 <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm>
8004 <info>
8005 LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer."
8006 </info>
8007 <glossdef>
8008 <para role="glossdeffirst">
8009 Lists the layers, separated by spaces, recommended for
8010 use with this layer.
8011 </para>
8012
8013 <para>
8014 Optionally, you can specify a specific layer version for a
8015 recommendation by adding the version to the end of the
8016 layer name.
8017 Here is an example:
8018 <literallayout class='monospaced'>
8019 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
8020 </literallayout>
8021 In this previous example, version 3 of "anotherlayer" is
8022 compared against
8023 <filename>LAYERVERSION_anotherlayer</filename>.
8024 </para>
8025
8026 <para>
8027 This variable is used in the
8028 <filename>conf/layer.conf</filename> file and must be
8029 suffixed with the name of the specific layer (e.g.
8030 <filename>LAYERRECOMMENDS_mylayer</filename>).
8031 </para>
8032 </glossdef>
8033 </glossentry>
8034
8035 <glossentry id='var-LAYERSERIES_COMPAT'><glossterm>LAYERSERIES_COMPAT</glossterm>
8036 <info>
8037 LAYERSERIES_COMPAT[doc] = "Lists the OpenEmbedded-Core versions for which a layer is compatible."
8038 </info>
8039 <glossdef>
8040 <para role="glossdeffirst">
8041 Lists the versions of the
8042 <link linkend='oe-core'>OpenEmbedded-Core</link> for which
8043 a layer is compatible.
8044 Using the <filename>LAYERSERIES_COMPAT</filename> variable
8045 allows the layer maintainer to indicate which combinations
8046 of the layer and OE-Core can be expected to work.
8047 The variable gives the system a way to detect when a layer
8048 has not been tested with new releases of OE-Core (e.g.
8049 the layer is not maintained).
8050 </para>
8051
8052 <para>
8053 To specify the OE-Core versions for which a layer is
8054 compatible, use this variable in your layer's
8055 <filename>conf/layer.conf</filename> configuration file.
8056 For the list, use the Yocto Project
8057 <ulink url='https://wiki.yoctoproject.org/wiki/Releases'>Release Name</ulink>
8058 (e.g. &DISTRO_NAME_NO_CAP;).
8059 To specify multiple OE-Core versions for the layer,
8060 use a space-separated list:
8061 <literallayout class='monospaced'>
8062 LAYERSERIES_COMPAT_<replaceable>layer_root_name</replaceable> = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
8063 </literallayout>
8064 <note>
8065 Setting <filename>LAYERSERIES_COMPAT</filename> is
8066 required by the Yocto Project Compatible version 2
8067 standard.
8068 The OpenEmbedded build system produces a warning if
8069 the variable is not set for any given layer.
8070 </note>
8071 </para>
8072
8073 <para>
8074 See the
8075 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-layer'>Creating Your Own Layer</ulink>"
8076 section in the Yocto Project Development Tasks Manual.
8077 </para>
8078 </glossdef>
8079 </glossentry>
8080
8081 <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
8082 <info>
8083 LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer."
8084 </info>
8085 <glossdef>
8086 <para role="glossdeffirst">
8087 Optionally specifies the version of a layer as a single number.
8088 You can use this within
8089 <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
8090 for another layer in order to depend on a specific version
8091 of the layer.
8092 This variable is used in the <filename>conf/layer.conf</filename> file
8093 and must be suffixed with the name of the specific layer (e.g.
8094 <filename>LAYERVERSION_mylayer</filename>).
8095 </para>
8096 </glossdef>
8097 </glossentry>
8098
8099 <glossentry id='var-LD'><glossterm>LD</glossterm>
8100 <info>
8101 LD[doc] = "Minimal command and arguments to run the linker."
8102 </info>
8103 <glossdef>
8104 <para role="glossdeffirst">
8105 The minimal command and arguments used to run the
8106 linker.
8107 </para>
8108 </glossdef>
8109 </glossentry>
8110
8111 <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm>
8112 <info>
8113 LDFLAGS[doc] = "Specifies the flags to pass to the linker."
8114 </info>
8115 <glossdef>
8116 <para role="glossdeffirst">
8117 Specifies the flags to pass to the linker.
8118 This variable is exported to an environment
8119 variable and thus made visible to the software being
8120 built during the compilation step.
8121 </para>
8122
8123 <para>
8124 Default initialization for <filename>LDFLAGS</filename>
8125 varies depending on what is being built:
8126 <itemizedlist>
8127 <listitem><para>
8128 <link linkend='var-TARGET_LDFLAGS'><filename>TARGET_LDFLAGS</filename></link>
8129 when building for the target
8130 </para></listitem>
8131 <listitem><para>
8132 <link linkend='var-BUILD_LDFLAGS'><filename>BUILD_LDFLAGS</filename></link>
8133 when building for the build host (i.e.
8134 <filename>-native</filename>)
8135 </para></listitem>
8136 <listitem><para>
8137 <link linkend='var-BUILDSDK_LDFLAGS'><filename>BUILDSDK_LDFLAGS</filename></link>
8138 when building for an SDK (i.e.
8139 <filename>nativesdk-</filename>)
8140 </para></listitem>
8141 </itemizedlist>
8142 </para>
8143 </glossdef>
8144 </glossentry>
8145
8146 <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm>
8147 <info>
8148 LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (i.e. .so) that the debian class applies its naming policy to given a recipe that packages multiple libraries."
8149 </info>
8150 <glossdef>
8151 <para role="glossdeffirst">
8152 Specifies the lead (or primary) compiled library file
8153 (i.e. <filename>.so</filename>) that the
8154 <link linkend='ref-classes-debian'><filename>debian</filename></link>
8155 class applies its naming policy to given a recipe that
8156 packages multiple libraries.
8157 </para>
8158
8159 <para>
8160 This variable works in conjunction with the
8161 <filename>debian</filename> class.
8162 </para>
8163 </glossdef>
8164 </glossentry>
8165
8166 <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
8167 <info>
8168 LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code."
8169 </info>
8170 <glossdef>
8171 <para role="glossdeffirst">
8172 Checksums of the license text in the recipe source code.
8173 </para>
8174
8175 <para>
8176 This variable tracks changes in license text of the source
8177 code files.
8178 If the license text is changed, it will trigger a build
8179 failure, which gives the developer an opportunity to review any
8180 license change.
8181 </para>
8182
8183 <para>
8184 This variable must be defined for all recipes (unless
8185 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8186 is set to "CLOSED").</para>
8187 <para>For more information, see the
8188 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
8189 section in the Yocto Project Development Tasks Manual.
8190 </para>
8191 </glossdef>
8192 </glossentry>
8193
8194 <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
8195 <info>
8196 LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &amp;, '|', and parentheses can be used."
8197 </info>
8198 <glossdef>
8199 <para role="glossdeffirst">
8200 The list of source licenses for the recipe.
8201 Follow these rules:
8202 <itemizedlist>
8203 <listitem><para>Do not use spaces within individual
8204 license names.</para></listitem>
8205 <listitem><para>Separate license names using
8206 | (pipe) when there is a choice between licenses.
8207 </para></listitem>
8208 <listitem><para>Separate license names using
8209 &amp; (ampersand) when multiple licenses exist
8210 that cover different parts of the source.
8211 </para></listitem>
8212 <listitem><para>You can use spaces between license
8213 names.</para></listitem>
8214 <listitem><para>For standard licenses, use the names
8215 of the files in
8216 <filename>meta/files/common-licenses/</filename>
8217 or the
8218 <link linkend='var-SPDXLICENSEMAP'><filename>SPDXLICENSEMAP</filename></link>
8219 flag names defined in
8220 <filename>meta/conf/licenses.conf</filename>.
8221 </para></listitem>
8222 </itemizedlist>
8223 </para>
8224
8225 <para>
8226 Here are some examples:
8227 <literallayout class='monospaced'>
8228 LICENSE = "LGPLv2.1 | GPLv3"
8229 LICENSE = "MPL-1 &amp; LGPLv2.1"
8230 LICENSE = "GPLv2+"
8231 </literallayout>
8232 The first example is from the recipes for Qt, which the user
8233 may choose to distribute under either the LGPL version
8234 2.1 or GPL version 3.
8235 The second example is from Cairo where two licenses cover
8236 different parts of the source code.
8237 The final example is from <filename>sysstat</filename>,
8238 which presents a single license.
8239 </para>
8240
8241 <para>
8242 You can also specify licenses on a per-package basis to
8243 handle situations where components of the output have
8244 different licenses.
8245 For example, a piece of software whose code is
8246 licensed under GPLv2 but has accompanying documentation
8247 licensed under the GNU Free Documentation License 1.2 could
8248 be specified as follows:
8249 <literallayout class='monospaced'>
8250 LICENSE = "GFDL-1.2 &amp; GPLv2"
8251 LICENSE_${PN} = "GPLv2"
8252 LICENSE_${PN}-doc = "GFDL-1.2"
8253 </literallayout>
8254 </para>
8255 </glossdef>
8256 </glossentry>
8257
8258 <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm>
8259 <info>
8260 LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}."
8261 </info>
8262 <glossdef>
8263 <para role="glossdeffirst">
8264 Setting <filename>LICENSE_CREATE_PACKAGE</filename>
8265 to "1" causes the OpenEmbedded build system to create
8266 an extra package (i.e.
8267 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>)
8268 for each recipe and to add those packages to the
8269 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>.
8270 </para>
8271
8272 <para>
8273 The <filename>${PN}-lic</filename> package installs a
8274 directory in <filename>/usr/share/licenses</filename>
8275 named <filename>${PN}</filename>, which is the recipe's
8276 base name, and installs files in that directory that
8277 contain license and copyright information (i.e. copies of
8278 the appropriate license files from
8279 <filename>meta/common-licenses</filename> that match the
8280 licenses specified in the
8281 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8282 variable of the recipe metadata and copies of files marked
8283 in
8284 <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>
8285 as containing license text).
8286 </para>
8287
8288 <para>
8289 For related information on providing license text, see the
8290 <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link>
8291 variable, the
8292 <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link>
8293 variable, and the
8294 "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>"
8295 section in the Yocto Project Development Tasks Manual.
8296 </para>
8297 </glossdef>
8298 </glossentry>
8299
8300 <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm>
8301 <info>
8302 LICENSE_FLAGS[doc] = "Specifies additional flags for a recipe you must whitelist through LICENSE_FLAGS_WHITELIST in order to allow the recipe to be built."
8303 </info>
8304 <glossdef>
8305 <para role="glossdeffirst">
8306 Specifies additional flags for a recipe you must
8307 whitelist through
8308 <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link>
8309 in order to allow the recipe to be built.
8310 When providing multiple flags, separate them with
8311 spaces.
8312 </para>
8313
8314 <para>
8315 This value is independent of
8316 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
8317 and is typically used to mark recipes that might
8318 require additional licenses in order to be used in a
8319 commercial product.
8320 For more information, see the
8321 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8322 section in the Yocto Project Development Tasks Manual.
8323 </para>
8324 </glossdef>
8325 </glossentry>
8326
8327 <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm>
8328 <info>
8329 LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built."
8330 </info>
8331 <glossdef>
8332 <para role="glossdeffirst">
8333 Lists license flags that when specified in
8334 <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link>
8335 within a recipe should not prevent that recipe from being
8336 built.
8337 This practice is otherwise known as "whitelisting"
8338 license flags.
8339 For more information, see the
8340 "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
8341 section in the Yocto Project Development Tasks Manual.
8342 </para>
8343 </glossdef>
8344 </glossentry>
8345
8346 <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
8347 <info>
8348 LICENSE_PATH[doc] = "Path to additional licenses used during the build."
8349 </info>
8350 <glossdef>
8351 <para role="glossdeffirst">
8352 Path to additional licenses used during the build.
8353 By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
8354 to define the directory that holds common license text used during the build.
8355 The <filename>LICENSE_PATH</filename> variable allows you to extend that
8356 location to other areas that have additional licenses:
8357 <literallayout class='monospaced'>
8358 LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>"
8359 </literallayout>
8360 </para>
8361 </glossdef>
8362 </glossentry>
8363
8364 <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
8365 <info>
8366 LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration."
8367 </info>
8368 <glossdef>
8369 <para role="glossdeffirst">
8370 Defines the kernel type to be used in assembling the
8371 configuration.
8372 The linux-yocto recipes define "standard", "tiny", and
8373 "preempt-rt" kernel types.
8374 See the
8375 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
8376 section in the Yocto Project Linux Kernel Development
8377 Manual for more information on kernel types.
8378 </para>
8379
8380 <para>
8381 If you do not specify a
8382 <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
8383 "standard".
8384 Together with
8385 <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
8386 the <filename>LINUX_KERNEL_TYPE</filename> variable
8387 defines the search
8388 arguments used by the kernel tools to find the appropriate
8389 description within the kernel
8390 <link linkend='metadata'>Metadata</link>
8391 with which to build out the sources and configuration.
8392 </para>
8393 </glossdef>
8394 </glossentry>
8395
8396 <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
8397 <info>
8398 LINUX_VERSION[doc] = "The Linux version from kernel.org on which the Linux kernel image being built using the OpenEmbedded build system is based. You define this variable in the kernel recipe."
8399 </info>
8400 <glossdef>
8401 <para role="glossdeffirst">
8402 The Linux version from <filename>kernel.org</filename>
8403 on which the Linux kernel image being built using the
8404 OpenEmbedded build system is based.
8405 You define this variable in the kernel recipe.
8406 For example, the <filename>linux-yocto-3.4.bb</filename>
8407 kernel recipe found in
8408 <filename>meta/recipes-kernel/linux</filename>
8409 defines the variables as follows:
8410 <literallayout class='monospaced'>
8411 LINUX_VERSION ?= "3.4.24"
8412 </literallayout>
8413 </para>
8414
8415 <para>
8416 The <filename>LINUX_VERSION</filename> variable is used to
8417 define <link linkend='var-PV'><filename>PV</filename></link>
8418 for the recipe:
8419 <literallayout class='monospaced'>
8420 PV = "${LINUX_VERSION}+git${SRCPV}"
8421 </literallayout>
8422 </para>
8423 </glossdef>
8424 </glossentry>
8425
8426 <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
8427 <info>
8428 LINUX_VERSION_EXTENSION[doc] = "A string extension compiled into the version string of the Linux kernel built with the OpenEmbedded build system. You define this variable in the kernel recipe."
8429 </info>
8430 <glossdef>
8431 <para role="glossdeffirst">
8432 A string extension compiled into the version
8433 string of the Linux kernel built with the OpenEmbedded
8434 build system.
8435 You define this variable in the kernel recipe.
8436 For example, the linux-yocto kernel recipes all define
8437 the variable as follows:
8438 <literallayout class='monospaced'>
8439 LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
8440 </literallayout>
8441 </para>
8442
8443 <para>
8444 Defining this variable essentially sets the
8445 Linux kernel configuration item
8446 <filename>CONFIG_LOCALVERSION</filename>, which is visible
8447 through the <filename>uname</filename> command.
8448 Here is an example that shows the extension assuming it
8449 was set as previously shown:
8450 <literallayout class='monospaced'>
8451 $ uname -r
8452 3.7.0-rc8-custom
8453 </literallayout>
8454 </para>
8455 </glossdef>
8456 </glossentry>
8457
8458 <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
8459 <info>
8460 LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log"
8461 </info>
8462 <glossdef>
8463 <para role="glossdeffirst">
8464 Specifies the directory to which the OpenEmbedded build
8465 system writes overall log files.
8466 The default directory is <filename>${TMPDIR}/log</filename>.
8467 </para>
8468
8469 <para>
8470 For the directory containing logs specific to each task,
8471 see the <link linkend='var-T'><filename>T</filename></link>
8472 variable.
8473 </para>
8474 </glossdef>
8475 </glossentry>
8476
8477 </glossdiv>
8478
8479 <glossdiv id='var-glossary-m'><title>M</title>
8480
8481 <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
8482 <info>
8483 MACHINE[doc] = "Specifies the target device for which the image is built. You define MACHINE in the conf/local.conf file in the Build Directory."
8484 </info>
8485 <glossdef>
8486 <para role="glossdeffirst">
8487 Specifies the target device for which the image is built.
8488 You define <filename>MACHINE</filename> in the
8489 <filename>local.conf</filename> file found in the
8490 <link linkend='build-directory'>Build Directory</link>.
8491 By default, <filename>MACHINE</filename> is set to
8492 "qemux86", which is an x86-based architecture machine to
8493 be emulated using QEMU:
8494 <literallayout class='monospaced'>
8495 MACHINE ?= "qemux86"
8496 </literallayout>
8497 </para>
8498
8499 <para>
8500 The variable corresponds to a machine configuration file of the
8501 same name, through which machine-specific configurations are set.
8502 Thus, when <filename>MACHINE</filename> is set to "qemux86" there
8503 exists the corresponding <filename>qemux86.conf</filename> machine
8504 configuration file, which can be found in the
8505 <link linkend='source-directory'>Source Directory</link>
8506 in <filename>meta/conf/machine</filename>.
8507 </para>
8508
8509 <para>
8510 The list of machines supported by the Yocto Project as
8511 shipped include the following:
8512 <literallayout class='monospaced'>
8513 MACHINE ?= "qemuarm"
8514 MACHINE ?= "qemuarm64"
8515 MACHINE ?= "qemumips"
8516 MACHINE ?= "qemumips64"
8517 MACHINE ?= "qemuppc"
8518 MACHINE ?= "qemux86"
8519 MACHINE ?= "qemux86-64"
8520 MACHINE ?= "genericx86"
8521 MACHINE ?= "genericx86-64"
8522 MACHINE ?= "beaglebone"
8523 MACHINE ?= "edgerouter"
8524 </literallayout>
8525 The last five are Yocto Project reference hardware boards, which
8526 are provided in the <filename>meta-yocto-bsp</filename> layer.
8527 <note>Adding additional Board Support Package (BSP) layers
8528 to your configuration adds new possible settings for
8529 <filename>MACHINE</filename>.
8530 </note>
8531 </para>
8532 </glossdef>
8533 </glossentry>
8534
8535 <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm>
8536 <info>
8537 MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH."
8538 </info>
8539 <glossdef>
8540 <para role="glossdeffirst">
8541 Specifies the name of the machine-specific architecture.
8542 This variable is set automatically from
8543 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
8544 or
8545 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>.
8546 You should not hand-edit the
8547 <filename>MACHINE_ARCH</filename> variable.
8548 </para>
8549 </glossdef>
8550 </glossentry>
8551
8552 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
8553 <info>
8554 MACHINE_ESSENTIAL_EXTRA_RDEPENDS[doc] = "A list of required machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
8555 </info>
8556 <glossdef>
8557 <para role="glossdeffirst">
8558 A list of required machine-specific packages to install as part of
8559 the image being built.
8560 The build process depends on these packages being present.
8561 Furthermore, because this is a "machine-essential" variable, the list of
8562 packages are essential for the machine to boot.
8563 The impact of this variable affects images based on
8564 <filename>packagegroup-core-boot</filename>,
8565 including the <filename>core-image-minimal</filename> image.
8566 </para>
8567
8568 <para>
8569 This variable is similar to the
8570 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
8571 variable with the exception that the image being built has a build
8572 dependency on the variable's list of packages.
8573 In other words, the image will not build if a file in this list is not found.
8574 </para>
8575
8576 <para>
8577 As an example, suppose the machine for which you are building requires
8578 <filename>example-init</filename> to be run during boot to initialize the hardware.
8579 In this case, you would use the following in the machine's
8580 <filename>.conf</filename> configuration file:
8581 <literallayout class='monospaced'>
8582 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
8583 </literallayout>
8584 </para>
8585 </glossdef>
8586 </glossentry>
8587
8588 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
8589 <info>
8590 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS[doc] = "A list of recommended machine-specific packages to install as part of the image being built. Because this is a 'machine-essential' variable, the list of packages are essential for the machine to boot."
8591 </info>
8592 <glossdef>
8593 <para role="glossdeffirst">
8594 A list of recommended machine-specific packages to install as part of
8595 the image being built.
8596 The build process does not depend on these packages being present.
8597 However, because this is a "machine-essential" variable, the list of
8598 packages are essential for the machine to boot.
8599 The impact of this variable affects images based on
8600 <filename>packagegroup-core-boot</filename>,
8601 including the <filename>core-image-minimal</filename> image.
8602 </para>
8603
8604 <para>
8605 This variable is similar to the
8606 <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
8607 variable with the exception that the image being built does not have a build
8608 dependency on the variable's list of packages.
8609 In other words, the image will still build if a package in this list is not found.
8610 Typically, this variable is used to handle essential kernel modules, whose
8611 functionality may be selected to be built into the kernel rather than as a module,
8612 in which case a package will not be produced.
8613 </para>
8614
8615 <para>
8616 Consider an example where you have a custom kernel where a specific touchscreen
8617 driver is required for the machine to be usable.
8618 However, the driver can be built as a module or
8619 into the kernel depending on the kernel configuration.
8620 If the driver is built as a module, you want it to be installed.
8621 But, when the driver is built into the kernel, you still want the
8622 build to succeed.
8623 This variable sets up a "recommends" relationship so that in the latter case,
8624 the build will not fail due to the missing package.
8625 To accomplish this, assuming the package for the module was called
8626 <filename>kernel-module-ab123</filename>, you would use the
8627 following in the machine's <filename>.conf</filename> configuration
8628 file:
8629 <literallayout class='monospaced'>
8630 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
8631 </literallayout>
8632 <note>
8633 In this example, the
8634 <filename>kernel-module-ab123</filename> recipe
8635 needs to explicitly set its
8636 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
8637 variable to ensure that BitBake does not use the
8638 kernel recipe's
8639 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
8640 variable to satisfy the dependency.
8641 </note>
8642 </para>
8643
8644 <para>
8645 Some examples of these machine essentials are flash, screen, keyboard, mouse,
8646 or touchscreen drivers (depending on the machine).
8647 </para>
8648 </glossdef>
8649 </glossentry>
8650
8651 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
8652 <info>
8653 MACHINE_EXTRA_RDEPENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for the machine to boot. However, the build process for more fully-featured images depends on the packages being present."
8654 </info>
8655 <glossdef>
8656 <para role="glossdeffirst">
8657 A list of machine-specific packages to install as part of the
8658 image being built that are not essential for the machine to boot.
8659 However, the build process for more fully-featured images
8660 depends on the packages being present.
8661 </para>
8662
8663 <para>
8664 This variable affects all images based on
8665 <filename>packagegroup-base</filename>, which does not include the
8666 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8667 images.
8668 </para>
8669
8670 <para>
8671 The variable is similar to the
8672 <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
8673 variable with the exception that the image being built has a build
8674 dependency on the variable's list of packages.
8675 In other words, the image will not build if a file in this list is not found.
8676 </para>
8677
8678 <para>
8679 An example is a machine that has WiFi capability but is not
8680 essential for the machine to boot the image.
8681 However, if you are building a more fully-featured image, you want to enable
8682 the WiFi.
8683 The package containing the firmware for the WiFi hardware is always
8684 expected to exist, so it is acceptable for the build process to depend upon
8685 finding the package.
8686 In this case, assuming the package for the firmware was called
8687 <filename>wifidriver-firmware</filename>, you would use the following in the
8688 <filename>.conf</filename> file for the machine:
8689 <literallayout class='monospaced'>
8690 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
8691 </literallayout>
8692 </para>
8693 </glossdef>
8694 </glossentry>
8695
8696 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
8697 <info>
8698 MACHINE_EXTRA_RRECOMMENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for booting the machine. The image being built has no build dependencies on the packages in this list."
8699 </info>
8700 <glossdef>
8701 <para role="glossdeffirst">
8702 A list of machine-specific packages to install as part of the
8703 image being built that are not essential for booting the machine.
8704 The image being built has no build dependency on this list of packages.
8705 </para>
8706
8707 <para>
8708 This variable affects only images based on
8709 <filename>packagegroup-base</filename>, which does not include the
8710 <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename>
8711 images.
8712 </para>
8713
8714 <para>
8715 This variable is similar to the
8716 <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
8717 variable with the exception that the image being built does not have a build
8718 dependency on the variable's list of packages.
8719 In other words, the image will build if a file in this list is not found.
8720 </para>
8721
8722 <para>
8723 An example is a machine that has WiFi capability but is not essential
8724 For the machine to boot the image.
8725 However, if you are building a more fully-featured image, you want to enable
8726 WiFi.
8727 In this case, the package containing the WiFi kernel module will not be produced
8728 if the WiFi driver is built into the kernel, in which case you still want the
8729 build to succeed instead of failing as a result of the package not being found.
8730 To accomplish this, assuming the package for the module was called
8731 <filename>kernel-module-examplewifi</filename>, you would use the
8732 following in the <filename>.conf</filename> file for the machine:
8733 <literallayout class='monospaced'>
8734 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
8735 </literallayout>
8736 </para>
8737 </glossdef>
8738 </glossentry>
8739
8740 <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
8741 <info>
8742 MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports."
8743 </info>
8744 <glossdef>
8745 <para role="glossdeffirst">
8746 Specifies the list of hardware features the
8747 <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable
8748 of supporting.
8749 For related information on enabling features, see the
8750 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>,
8751 <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>,
8752 and
8753 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
8754 variables.
8755 </para>
8756
8757 <para>
8758 For a list of hardware features supported by the Yocto
8759 Project as shipped, see the
8760 "<link linkend='ref-features-machine'>Machine Features</link>"
8761 section.
8762 </para>
8763 </glossdef>
8764 </glossentry>
8765
8766 <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
8767 <info>
8768 MACHINE_FEATURES_BACKFILL[doc] = "Features to be added to MACHINE_FEATURES if not also present in MACHINE_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and is not intended to be user-configurable."
8769 </info>
8770 <glossdef>
8771 <para role="glossdeffirst">
8772 Features to be added to
8773 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
8774 if not also present in
8775 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
8776 </para>
8777
8778 <para>
8779 This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
8780 It is not intended to be user-configurable.
8781 It is best to just reference the variable to see which machine features are
8782 being backfilled for all machine configurations.
8783 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
8784 more information.
8785 </para>
8786 </glossdef>
8787 </glossentry>
8788
8789 <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
8790 <info>
8791 MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build."
8792 </info>
8793 <glossdef>
8794 <para role="glossdeffirst">
8795 Features from
8796 <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
8797 that should not be backfilled (i.e. added to
8798 <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
8799 during the build.
8800 See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
8801 more information.
8802 </para>
8803 </glossdef>
8804 </glossentry>
8805
8806 <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
8807 <info>
8808 MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine."
8809 </info>
8810 <glossdef>
8811 <para role="glossdeffirst">
8812 A colon-separated list of overrides that apply to the
8813 current machine.
8814 By default, this list includes the value of
8815 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>.
8816 </para>
8817
8818 <para>
8819 You can extend <filename>MACHINEOVERRIDES</filename>
8820 to add extra overrides that should apply to a machine.
8821 For example, all machines emulated in QEMU (e.g.
8822 <filename>qemuarm</filename>, <filename>qemux86</filename>,
8823 and so forth) include a file named
8824 <filename>meta/conf/machine/include/qemu.inc</filename>
8825 that prepends the following override to
8826 <filename>MACHINEOVERRIDES</filename>:
8827 <literallayout class='monospaced'>
8828 MACHINEOVERRIDES =. "qemuall:"
8829 </literallayout>
8830 This override allows variables to be overriden for all
8831 machines emulated in QEMU, like in the following example
8832 from the <filename>connman-conf</filename> recipe:
8833 <literallayout class='monospaced'>
8834 SRC_URI_append_qemuall = "file://wired.config \
8835 file://wired-setup \
8836 "
8837 </literallayout>
8838 The underlying mechanism behind
8839 <filename>MACHINEOVERRIDES</filename> is simply that it is
8840 included in the default value of
8841 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
8842 </para>
8843 </glossdef>
8844 </glossentry>
8845
8846 <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
8847 <info>
8848 MAINTAINER[doc] = "The email address of the distribution maintainer."
8849 </info>
8850 <glossdef>
8851 <para role="glossdeffirst">
8852 The email address of the distribution maintainer.
8853 </para>
8854 </glossdef>
8855 </glossentry>
8856
8857 <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
8858 <info>
8859 MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
8860 </info>
8861 <glossdef>
8862 <para role="glossdeffirst">
8863 Specifies additional paths from which the OpenEmbedded
8864 build system gets source code.
8865 When the build system searches for source code, it first
8866 tries the local download directory.
8867 If that location fails, the build system tries locations
8868 defined by
8869 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
8870 the upstream source, and then locations specified by
8871 <filename>MIRRORS</filename> in that order.
8872 </para>
8873
8874 <para>
8875 Assuming your distribution
8876 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
8877 is "poky", the default value for
8878 <filename>MIRRORS</filename> is defined in the
8879 <filename>conf/distro/poky.conf</filename> file in the
8880 <filename>meta-poky</filename> Git repository.
8881 </para>
8882 </glossdef>
8883 </glossentry>
8884
8885 <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
8886 <info>
8887 MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package (i.e. a Multilib version)."
8888 </info>
8889 <glossdef>
8890 <para role="glossdeffirst">
8891 Specifies a prefix has been added to
8892 <link linkend='var-PN'><filename>PN</filename></link> to create a special version
8893 of a recipe or package (i.e. a Multilib version).
8894 The variable is used in places where the prefix needs to be
8895 added to or removed from a the name (e.g. the
8896 <link linkend='var-BPN'><filename>BPN</filename></link> variable).
8897 <filename>MLPREFIX</filename> gets set when a prefix has been
8898 added to <filename>PN</filename>.
8899 <note>
8900 The "ML" in <filename>MLPREFIX</filename> stands for
8901 "MultiLib".
8902 This representation is historical and comes from
8903 a time when <filename>nativesdk</filename> was a suffix
8904 rather than a prefix on the recipe name.
8905 When <filename>nativesdk</filename> was turned into a
8906 prefix, it made sense to set
8907 <filename>MLPREFIX</filename> for it as well.
8908 </note>
8909 </para>
8910
8911 <para>
8912 To help understand when <filename>MLPREFIX</filename>
8913 might be needed, consider when
8914 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
8915 is used to provide a <filename>nativesdk</filename> version
8916 of a recipe in addition to the target version.
8917 If that recipe declares build-time dependencies on tasks in
8918 other recipes by using
8919 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
8920 then a dependency on "foo" will automatically get rewritten
8921 to a dependency on "nativesdk-foo".
8922 However, dependencies like the following will not get
8923 rewritten automatically:
8924 <literallayout class='monospaced'>
8925 do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo"
8926 </literallayout>
8927 If you want such a dependency to also get transformed,
8928 you can do the following:
8929 <literallayout class='monospaced'>
8930 do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo"
8931 </literallayout>
8932 </para>
8933 </glossdef>
8934 </glossentry>
8935
8936 <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm>
8937 <info>
8938 module_autoload[doc] = "This variable has been replaced by the KERNEL_MODULE_AUTOLOAD variable. You should replace all occurrences of module_autoload with additions to KERNEL_MODULE_AUTOLOAD."
8939 </info>
8940 <glossdef>
8941 <para role="glossdeffirst">
8942 This variable has been replaced by the
8943 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
8944 You should replace all occurrences of
8945 <filename>module_autoload</filename> with additions to
8946 <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
8947 <literallayout class='monospaced'>
8948 module_autoload_rfcomm = "rfcomm"
8949 </literallayout>
8950 </para>
8951
8952 <para>
8953 should now be replaced with:
8954 <literallayout class='monospaced'>
8955 KERNEL_MODULE_AUTOLOAD += "rfcomm"
8956 </literallayout>
8957 See the
8958 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
8959 variable for more information.
8960 </para>
8961 </glossdef>
8962 </glossentry>
8963
8964 <glossentry id='var-module_conf'><glossterm>module_conf</glossterm>
8965 <info>
8966 module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file."
8967 </info>
8968 <glossdef>
8969 <para role="glossdeffirst">
8970 Specifies
8971 <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink>
8972 syntax lines for inclusion in the
8973 <filename>/etc/modprobe.d/modname.conf</filename> file.
8974 </para>
8975
8976 <para>
8977 You can use this variable anywhere that it can be
8978 recognized by the kernel recipe or out-of-tree kernel
8979 module recipe (e.g. a machine configuration file, a
8980 distribution configuration file, an append file for the
8981 recipe, or the recipe itself).
8982 If you use this variable, you must also be sure to list
8983 the module name in the
8984 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
8985 variable.
8986 </para>
8987
8988 <para>
8989 Here is the general syntax:
8990 <literallayout class='monospaced'>
8991 module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>"
8992 </literallayout>
8993 You must use the kernel module name override.
8994 </para>
8995
8996 <para>
8997 Run <filename>man modprobe.d</filename> in the shell to
8998 find out more information on the exact syntax
8999 you want to provide with <filename>module_conf</filename>.
9000 </para>
9001
9002 <para>
9003 Including <filename>module_conf</filename> causes the
9004 OpenEmbedded build system to populate the
9005 <filename>/etc/modprobe.d/modname.conf</filename>
9006 file with <filename>modprobe.d</filename> syntax lines.
9007 Here is an example that adds the options
9008 <filename>arg1</filename> and <filename>arg2</filename>
9009 to a module named <filename>mymodule</filename>:
9010 <literallayout class='monospaced'>
9011 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
9012 </literallayout>
9013 </para>
9014
9015 <para>
9016 For information on how to specify kernel modules to
9017 auto-load on boot, see the
9018 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
9019 variable.
9020 </para>
9021 </glossdef>
9022 </glossentry>
9023
9024 <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
9025 <info>
9026 MODULE_TARBALL_DEPLOY[doc] = "Controls creation of the modules-*.tgz file. Set this variable to "0" to disable creation of this file, which contains all of the kernel modules resulting from a kernel build."
9027 </info>
9028 <glossdef>
9029 <para role="glossdeffirst">
9030 Controls creation of the <filename>modules-*.tgz</filename>
9031 file.
9032 Set this variable to "0" to disable creation of this
9033 file, which contains all of the kernel modules resulting
9034 from a kernel build.
9035 </para>
9036 </glossdef>
9037 </glossentry>
9038
9039 <glossentry id='var-MODULE_TARBALL_LINK_NAME'><glossterm>MODULE_TARBALL_LINK_NAME</glossterm>
9040 <info>
9041 MODULE_TARBALL_LINK_NAME[doc] = "The link name of the kernel module tarball."
9042 </info>
9043 <glossdef>
9044 <para role="glossdeffirst">
9045 The link name of the kernel module tarball.
9046 This variable is set in the
9047 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9048 file as follows:
9049 <literallayout class='monospaced'>
9050 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
9051 </literallayout>
9052 The value of the <filename>KERNEL_ARTIFACT_LINK_NAME</filename>
9053 variable, which is set in the same file, has the following
9054 value:
9055 <literallayout class='monospaced'>
9056 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
9057 </literallayout>
9058 </para>
9059
9060 <para>
9061 See the
9062 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
9063 variable for additional information.
9064 </para>
9065 </glossdef>
9066 </glossentry>
9067
9068 <glossentry id='var-MODULE_TARBALL_NAME'><glossterm>MODULE_TARBALL_NAME</glossterm>
9069 <info>
9070 MODULE_TARBALL_NAME[doc] = "The base name of the kernel module tarball."
9071 </info>
9072 <glossdef>
9073 <para role="glossdeffirst">
9074 The base name of the kernel module tarball.
9075 This variable is set in the
9076 <filename>meta/classes/kernel-artifact-names.bbclass</filename>
9077 file as follows:
9078 <literallayout class='monospaced'>
9079 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
9080 </literallayout>
9081 The value of the
9082 <link linkend='var-KERNEL_ARTIFACT_NAME'><filename>KERNEL_ARTIFACT_NAME</filename></link>
9083 variable, which is set in the same file, has the following
9084 value:
9085 <literallayout class='monospaced'>
9086 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
9087 </literallayout>
9088 </para>
9089 </glossdef>
9090 </glossentry>
9091
9092<!--
9093 <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm>
9094 <info>
9095 MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories."
9096 </info>
9097 <glossdef>
9098 <para role="glossdeffirst">
9099-->
9100<!--
9101 Serves the same purpose as
9102 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
9103 but for the "HOST" system, in situations that involve a
9104 "HOST" and a "TARGET" system.
9105 See the
9106 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9107 variable for more information.
9108 </para>
9109
9110 <para>
9111 The default value of this variable is:
9112 <literallayout class='monospaced'>
9113 ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS}
9114 </literallayout>
9115 </para>
9116 </glossdef>
9117 </glossentry>
9118-->
9119
9120 <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
9121 <info>
9122 MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories."
9123 </info>
9124 <glossdef>
9125 <para role="glossdeffirst">
9126 Uniquely identifies the type of the target system for
9127 which packages are being built.
9128 This variable allows output for different types of target
9129 systems to be put into different subdirectories of the same
9130 output directory.
9131 </para>
9132
9133 <para>
9134 The default value of this variable is:
9135 <literallayout class='monospaced'>
9136 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
9137 </literallayout>
9138 Some classes (e.g.
9139 <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>)
9140 modify the <filename>MULTIMACH_TARGET_SYS</filename> value.
9141 </para>
9142
9143 <para>
9144 See the
9145 <link linkend='var-STAMP'><filename>STAMP</filename></link>
9146 variable for an example.
9147 See the
9148 <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link>
9149 variable for more information.
9150 </para>
9151 </glossdef>
9152 </glossentry>
9153
9154 </glossdiv>
9155
9156 <glossdiv id='var-glossary-n'><title>N</title>
9157
9158 <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
9159 <info>
9160 NATIVELSBSTRING[doc] = "A string identifying the host distribution."
9161 </info>
9162 <glossdef>
9163 <para role="glossdeffirst">
9164 A string identifying the host distribution.
9165 Strings consist of the host distributor ID
9166 followed by the release, as reported by the
9167 <filename>lsb_release</filename> tool
9168 or as read from <filename>/etc/lsb-release</filename>.
9169 For example, when running a build on Ubuntu 12.10, the value
9170 is "Ubuntu-12.10".
9171 If this information is unable to be determined, the value
9172 resolves to "Unknown".
9173 </para>
9174
9175 <para>
9176 This variable is used by default to isolate native shared
9177 state packages for different distributions (e.g. to avoid
9178 problems with <filename>glibc</filename> version
9179 incompatibilities).
9180 Additionally, the variable is checked against
9181 <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
9182 if that variable is set.
9183 </para>
9184 </glossdef>
9185 </glossentry>
9186
9187 <glossentry id='var-NM'><glossterm>NM</glossterm>
9188 <info>
9189 NM[doc] = "Minimal command and arguments to run 'nm'."
9190 </info>
9191 <glossdef>
9192 <para role="glossdeffirst">
9193 The minimal command and arguments to run
9194 <filename>nm</filename>.
9195 </para>
9196 </glossdef>
9197 </glossentry>
9198
9199 <glossentry id='var-NO_GENERIC_LICENSE'><glossterm>NO_GENERIC_LICENSE</glossterm>
9200 <info>
9201 NO_GENERIC_LICENSE[doc] = "Used to allow copying a license that does not exist in common licenses."
9202 </info>
9203 <glossdef>
9204 <para role="glossdeffirst">
9205 Avoids QA errors when you use a non-common, non-CLOSED
9206 license in a recipe.
9207 Packages exist, such as the linux-firmware package, with
9208 many licenses that are not in any way common.
9209 Also, new licenses are added occasionally to avoid
9210 introducing a lot of common license files, which are only
9211 applicable to a specific package.
9212 <filename>NO_GENERIC_LICENSE</filename> is used to allow
9213 copying a license that does not exist in common licenses.
9214 </para>
9215
9216 <para>
9217 The following example shows how to add
9218 <filename>NO_GENERIC_LICENSE</filename> to a recipe:
9219 <literallayout class='monospaced'>
9220 NO_GENERIC_LICENSE[<replaceable>license_name</replaceable>] = "<replaceable>license_file_in_fetched_source</replaceable>"
9221 </literallayout>
9222 The following is an example that uses the
9223 <filename>LICENSE.Abilis.txt</filename> file as the license
9224 from the fetched source:
9225 <literallayout class='monospaced'>
9226 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
9227 </literallayout>
9228 </para>
9229 </glossdef>
9230 </glossentry>
9231
9232 <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
9233 <info>
9234 NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Some recommended packages might be required for certain system functionality, such as kernel-modules. It is up to the user to add packages to IMAGE_INSTALL as needed."
9235 </info>
9236 <glossdef>
9237 <para role="glossdeffirst">
9238 Prevents installation of all "recommended-only" packages.
9239 Recommended-only packages are packages installed only
9240 through the
9241 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
9242 variable).
9243 Setting the <filename>NO_RECOMMENDATIONS</filename> variable
9244 to "1" turns this feature on:
9245 <literallayout class='monospaced'>
9246 NO_RECOMMENDATIONS = "1"
9247 </literallayout>
9248 </para>
9249
9250 <para>
9251 You can set this variable globally in your
9252 <filename>local.conf</filename> file or you can attach it to
9253 a specific image recipe by using the recipe name override:
9254 <literallayout class='monospaced'>
9255 NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1"
9256 </literallayout>
9257 </para>
9258
9259 <para>
9260 It is important to realize that if you choose to not install
9261 packages using this variable and some other packages are
9262 dependent on them (i.e. listed in a recipe's
9263 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9264 variable), the OpenEmbedded build system ignores your
9265 request and will install the packages to avoid dependency
9266 errors.
9267 <note>
9268 Some recommended packages might be required for certain
9269 system functionality, such as kernel modules.
9270 It is up to you to add packages with the
9271 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
9272 variable.
9273 </note>
9274 </para>
9275
9276 <para>
9277 Support for this variable exists only when using the
9278 IPK and RPM packaging backend.
9279 Support does not exist for DEB.
9280 </para>
9281
9282 <para>
9283 See the
9284 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9285 and the
9286 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
9287 variables for related information.
9288 </para>
9289 </glossdef>
9290 </glossentry>
9291
9292 <glossentry id='var-NOAUTOPACKAGEDEBUG'><glossterm>NOAUTOPACKAGEDEBUG</glossterm>
9293 <info>
9294 NOAUTOPACKAGEDEBUG[doc] = "Disables auto package from splitting .debug files."
9295 </info>
9296 <glossdef>
9297 <para role="glossdeffirst">
9298 Disables auto package from splitting
9299 <filename>.debug</filename> files. If a recipe requires
9300 <filename>FILES_${PN}-dbg</filename> to be set manually,
9301 the <filename>NOAUTOPACKAGEDEBUG</filename> can be defined
9302 allowing you to define the content of the debug package.
9303 For example:
9304 <literallayout class='monospaced'>
9305 NOAUTOPACKAGEDEBUG = "1"
9306 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
9307 FILES_${PN}-dbg = "/usr/src/debug/"
9308 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
9309 </literallayout>
9310 </para>
9311 </glossdef>
9312 </glossentry>
9313 </glossdiv>
9314
9315 <glossdiv id='var-glossary-o'><title>O</title>
9316
9317 <glossentry id='var-OBJCOPY'><glossterm>OBJCOPY</glossterm>
9318 <info>
9319 OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'."
9320 </info>
9321 <glossdef>
9322 <para role="glossdeffirst">
9323 The minimal command and arguments to run
9324 <filename>objcopy</filename>.
9325 </para>
9326 </glossdef>
9327 </glossentry>
9328
9329 <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm>
9330 <info>
9331 OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'."
9332 </info>
9333 <glossdef>
9334 <para role="glossdeffirst">
9335 The minimal command and arguments to run
9336 <filename>objdump</filename>.
9337 </para>
9338 </glossdef>
9339 </glossentry>
9340
9341 <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
9342 <info>
9343 OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command."
9344 </info>
9345 <glossdef>
9346 <para role="glossdeffirst">
9347 When inheriting the
9348 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
9349 class, this variable
9350 specifies additional arguments passed to the "sed" command.
9351 The sed command alters any paths in configuration scripts
9352 that have been set up during compilation.
9353 Inheriting this class results in all paths in these scripts
9354 being changed to point into the
9355 <filename>sysroots/</filename> directory so that all builds
9356 that use the script will use the correct directories
9357 for the cross compiling layout.
9358 </para>
9359
9360 <para>
9361 See the <filename>meta/classes/binconfig.bbclass</filename>
9362 in the
9363 <link linkend='source-directory'>Source Directory</link>
9364 for details on how this class applies these additional
9365 sed command arguments.
9366 For general information on the
9367 <filename>binconfig</filename> class, see the
9368 "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
9369 section.
9370 </para>
9371 </glossdef>
9372 </glossentry>
9373
9374 <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
9375 <info>
9376 OE_IMPORTS[doc] = "An internal variable used to tell the OpenEmbedded build system what Python modules to import for every Python function run by the system."
9377 </info>
9378 <glossdef>
9379 <para role="glossdeffirst">
9380 An internal variable used to tell the OpenEmbedded build
9381 system what Python modules to import for every Python
9382 function run by the system.
9383 </para>
9384
9385 <note>
9386 Do not set this variable.
9387 It is for internal use only.
9388 </note>
9389 </glossdef>
9390 </glossentry>
9391
9392 <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm>
9393 <info>
9394 OE_INIT_ENV_SCRIPT[doc] = "The name of the build environment setup script for the purposes of setting up the environment within the extensible SDK."
9395 </info>
9396 <glossdef>
9397 <para role="glossdeffirst">
9398 The name of the build environment setup script for the
9399 purposes of setting up the environment within the
9400 extensible SDK.
9401 The default value is "oe-init-build-env".
9402 </para>
9403
9404 <para>
9405 If you use a custom script to set up your build
9406 environment, set the
9407 <filename>OE_INIT_ENV_SCRIPT</filename> variable to its
9408 name.
9409 </para>
9410 </glossdef>
9411 </glossentry>
9412
9413 <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
9414 <info>
9415 OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system."
9416 </info>
9417 <glossdef>
9418 <para role="glossdeffirst">
9419 Controls how the OpenEmbedded build system spawns
9420 interactive terminals on the host development system
9421 (e.g. using the BitBake command with the
9422 <filename>-c devshell</filename> command-line option).
9423 For more information, see the
9424 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
9425 in the Yocto Project Development Tasks Manual.
9426 </para>
9427
9428 <para>
9429 You can use the following values for the
9430 <filename>OE_TERMINAL</filename> variable:
9431 <literallayout class='monospaced'>
9432 auto
9433 gnome
9434 xfce
9435 rxvt
9436 screen
9437 konsole
9438 none
9439 </literallayout>
9440 </para>
9441 </glossdef>
9442 </glossentry>
9443
9444 <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
9445 <info>
9446 OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced."
9447 </info>
9448 <glossdef>
9449 <para role="glossdeffirst">
9450 The directory from which the top-level build environment
9451 setup script is sourced.
9452 The Yocto Project provides a top-level build environment
9453 setup script:
9454 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
9455 When you run this script, the
9456 <filename>OEROOT</filename> variable resolves to the
9457 directory that contains the script.
9458 </para>
9459
9460 <para>
9461 For additional information on how this variable is used,
9462 see the initialization script.
9463 </para>
9464 </glossdef>
9465 </glossentry>
9466
9467 <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
9468 <info>
9469 OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support."
9470 </info>
9471 <glossdef>
9472 <para role="glossdeffirst">
9473 Declares the oldest version of the Linux kernel that the
9474 produced binaries must support.
9475 This variable is passed into the build of the Embedded
9476 GNU C Library (<filename>glibc</filename>).
9477 </para>
9478
9479 <para>
9480 The default for this variable comes from the
9481 <filename>meta/conf/bitbake.conf</filename> configuration
9482 file.
9483 You can override this default by setting the variable
9484 in a custom distribution configuration file.
9485 </para>
9486 </glossdef>
9487 </glossentry>
9488
9489 <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
9490 <info>
9491 OVERRIDES[doc] = "A colon-separated list of overrides that currently apply."
9492 </info>
9493 <glossdef>
9494 <para role="glossdeffirst">
9495 A colon-separated list of overrides that currently apply.
9496 Overrides are a BitBake mechanism that allows variables to
9497 be selectively overridden at the end of parsing.
9498 The set of overrides in <filename>OVERRIDES</filename>
9499 represents the "state" during building, which includes
9500 the current recipe being built, the machine for which
9501 it is being built, and so forth.
9502 </para>
9503
9504 <para>
9505 As an example, if the string "an-override" appears as an
9506 element in the colon-separated list in
9507 <filename>OVERRIDES</filename>, then the following
9508 assignment will override <filename>FOO</filename> with the
9509 value "overridden" at the end of parsing:
9510 <literallayout class='monospaced'>
9511 FOO_an-override = "overridden"
9512 </literallayout>
9513 See the
9514 "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>"
9515 section in the BitBake User Manual for more information on
9516 the overrides mechanism.
9517 </para>
9518
9519 <para>
9520 The default value of <filename>OVERRIDES</filename>
9521 includes the values of the
9522 <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>,
9523 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>,
9524 and
9525 <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
9526 variables.
9527 Another important override included by default is
9528 <filename>pn-${PN}</filename>.
9529 This override allows variables to be set for a single
9530 recipe within configuration (<filename>.conf</filename>)
9531 files.
9532 Here is an example:
9533 <literallayout class='monospaced'>
9534 FOO_pn-myrecipe = "myrecipe-specific value"
9535 </literallayout>
9536 <note><title>Tip</title>
9537 An easy way to see what overrides apply is to search for
9538 <filename>OVERRIDES</filename> in the output of the
9539 <filename>bitbake -e</filename> command.
9540 See the
9541 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-debugging-viewing-variable-values'>Viewing Variable Values</ulink>"
9542 section in the Yocto Project Development Tasks
9543 Manual for more information.
9544 </note>
9545 </para>
9546 </glossdef>
9547 </glossentry>
9548 </glossdiv>
9549
9550 <glossdiv id='var-glossary-p'><title>P</title>
9551
9552 <glossentry id='var-P'><glossterm>P</glossterm>
9553 <info>
9554 P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}."
9555 </info>
9556 <glossdef>
9557 <para role="glossdeffirst">
9558 The recipe name and version.
9559 <filename>P</filename> is comprised of the following:
9560 <literallayout class='monospaced'>
9561 ${PN}-${PV}
9562 </literallayout>
9563 </para>
9564 </glossdef>
9565 </glossentry>
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
9601 <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
9602 <info>
9603 PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."
9604 </info>
9605 <glossdef>
9606 <para role="glossdeffirst">
9607 The architecture of the resulting package or packages.
9608 </para>
9609
9610 <para>
9611 By default, the value of this variable is set to
9612 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
9613 when building for the target,
9614 <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>
9615 when building for the
9616 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building
9617 for the SDK.
9618 <note>
9619 See
9620 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>
9621 for more information.
9622 </note>
9623 However, if your recipe's output packages are built
9624 specific to the target machine rather than generally for
9625 the architecture of the machine, you should set
9626 <filename>PACKAGE_ARCH</filename> to the value of
9627 <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>
9628 in the recipe as follows:
9629 <literallayout class='monospaced'>
9630 PACKAGE_ARCH = "${MACHINE_ARCH}"
9631 </literallayout>
9632 </para>
9633 </glossdef>
9634 </glossentry>
9635
9636 <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm>
9637 <info>
9638 PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority."
9639 </info>
9640 <glossdef>
9641 <para role="glossdeffirst">
9642 Specifies a list of architectures compatible with
9643 the target machine.
9644 This variable is set automatically and should not
9645 normally be hand-edited.
9646 Entries are separated using spaces and listed in order
9647 of priority.
9648 The default value for
9649 <filename>PACKAGE_ARCHS</filename> is "all any noarch
9650 ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
9651 </para>
9652 </glossdef>
9653 </glossentry>
9654
9655 <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
9656 <info>
9657 PACKAGE_BEFORE_PN[doc] = "Enables easily adding packages to PACKAGES before ${PN} so that the packages can pick up files that would normally be included in the default package."
9658 </info>
9659 <glossdef>
9660 <para role="glossdeffirst">
9661 Enables easily adding packages to
9662 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
9663 before <filename>${<link linkend='var-PN'>PN</link>}</filename>
9664 so that those added packages can pick up files that would normally be
9665 included in the default package.
9666 </para>
9667 </glossdef>
9668 </glossentry>
9669
9670 <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
9671 <info>
9672 PACKAGE_CLASSES[doc] = "This variable specifies the package manager to use when packaging data. It is set in the conf/local.conf file in the Build Directory."
9673 </info>
9674 <glossdef>
9675 <para role="glossdeffirst">
9676 This variable, which is set in the
9677 <filename>local.conf</filename> configuration file found in
9678 the <filename>conf</filename> folder of the
9679 <link linkend='build-directory'>Build Directory</link>,
9680 specifies the package manager the OpenEmbedded build system
9681 uses when packaging data.
9682 </para>
9683
9684 <para>
9685 You can provide one or more of the following arguments for
9686 the variable:
9687 <literallayout class='monospaced'>
9688 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar"
9689 </literallayout>
9690 <note><title>Warning</title>
9691 While it is a legal option, the
9692 <filename>package_tar</filename> class has limited
9693 functionality due to no support for package
9694 dependencies by that backend.
9695 Therefore, it is recommended that you do not use it.
9696 </note>
9697 The build system uses only the first argument in the list
9698 as the package manager when creating your image or SDK.
9699 However, packages will be created using any additional
9700 packaging classes you specify.
9701 For example, if you use the following in your
9702 <filename>local.conf</filename> file:
9703 <literallayout class='monospaced'>
9704 PACKAGE_CLASSES ?= "package_ipk"
9705 </literallayout>
9706 The OpenEmbedded build system uses the IPK package manager
9707 to create your image or SDK.
9708 </para>
9709
9710 <para>
9711 For information on packaging and build performance effects
9712 as a result of the package manager in use, see the
9713 "<link linkend='ref-classes-package'><filename>package.bbclass</filename></link>"
9714 section.
9715 </para>
9716 </glossdef>
9717 </glossentry>
9718
9719 <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>PACKAGE_DEBUG_SPLIT_STYLE</glossterm>
9720 <info>
9721 PACKAGE_DEBUG_SPLIT_STYLE[doc] = "Determines how to split up the binary and debug information when creating *-dbg packages to be used with the GNU Project Debugger (GDB)."
9722 </info>
9723 <glossdef>
9724 <para role="glossdeffirst">
9725 Determines how to split up the binary and debug information
9726 when creating <filename>*-dbg</filename> packages to be
9727 used with the GNU Project Debugger (GDB).
9728 </para>
9729
9730 <para>
9731 With the
9732 <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable,
9733 you can control where debug information, which can include
9734 or exclude source files, is stored:
9735 <itemizedlist>
9736 <listitem><para>
9737 ".debug": Debug symbol files are placed next
9738 to the binary in a <filename>.debug</filename>
9739 directory on the target.
9740 For example, if a binary is installed into
9741 <filename>/bin</filename>, the corresponding debug
9742 symbol files are installed in
9743 <filename>/bin/.debug</filename>.
9744 Source files are placed in
9745 <filename>/usr/src/debug</filename>.
9746 </para></listitem>
9747 <listitem><para>
9748 "debug-file-directory": Debug symbol files are
9749 placed under <filename>/usr/lib/debug</filename>
9750 on the target, and separated by the path from where
9751 the binary is installed.
9752 For example, if a binary is installed in
9753 <filename>/bin</filename>, the corresponding debug
9754 symbols are installed in
9755 <filename>/usr/lib/debug/bin</filename>.
9756 Source files are placed in
9757 <filename>/usr/src/debug</filename>.
9758 </para></listitem>
9759 <listitem><para>
9760 "debug-without-src": The same behavior as
9761 ".debug" previously described with the exception
9762 that no source files are installed.
9763 </para></listitem>.
9764 <listitem><para>
9765 "debug-with-srcpkg": The same behavior as
9766 ".debug" previously described with the exception
9767 that all source files are placed in a separate
9768 <filename>*-src</filename> pkg.
9769 This is the default behavior.
9770 </para></listitem>
9771 </itemizedlist>
9772 </para>
9773
9774 <para>
9775 You can find out more about debugging using GDB by reading
9776 the
9777 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
9778 section in the Yocto Project Development Tasks Manual.
9779 </para>
9780 </glossdef>
9781 </glossentry>
9782
9783 <glossentry id='var-PACKAGE_EXCLUDE_COMPLEMENTARY'><glossterm>PACKAGE_EXCLUDE_COMPLEMENTARY</glossterm>
9784 <info>
9785 PACKAGE_EXCLUDE_COMPLEMENTARY[doc] = "Prevents specific packages from being installed when you are installing complementary packages."
9786 </info>
9787 <glossdef>
9788 <para role="glossdeffirst">
9789 Prevents specific packages from being installed when
9790 you are installing complementary packages.
9791 </para>
9792
9793 <para>
9794 You might find that you want to prevent installing certain
9795 packages when you are installing complementary packages.
9796 For example, if you are using
9797 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
9798 to install <filename>dev-pkgs</filename>, you might not want
9799 to install all packages from a particular multilib.
9800 If you find yourself in this situation, you can use the
9801 <filename>PACKAGE_EXCLUDE_COMPLEMENTARY</filename> variable
9802 to specify regular expressions to match the packages you
9803 want to exclude.
9804 </para>
9805 </glossdef>
9806 </glossentry>
9807
9808 <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
9809 <info>
9810 PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated."
9811 </info>
9812 <glossdef>
9813 <para role="glossdeffirst">
9814 Lists packages that should not be installed into an image.
9815 For example:
9816 <literallayout class='monospaced'>
9817 PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..."
9818 </literallayout>
9819 </para>
9820
9821 <para>
9822 You can set this variable globally in your
9823 <filename>local.conf</filename> file or you can attach it to
9824 a specific image recipe by using the recipe name override:
9825 <literallayout class='monospaced'>
9826 PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>"
9827 </literallayout>
9828 </para>
9829
9830 <para>
9831 If you choose to not install
9832 a package using this variable and some other package is
9833 dependent on it (i.e. listed in a recipe's
9834 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
9835 variable), the OpenEmbedded build system generates a fatal
9836 installation error.
9837 Because the build system halts the process with a fatal
9838 error, you can use the variable with an iterative
9839 development process to remove specific components from a
9840 system.
9841 </para>
9842
9843 <para>
9844 Support for this variable exists only when using the
9845 IPK and RPM packaging backend.
9846 Support does not exist for DEB.
9847 </para>
9848
9849 <para>
9850 See the
9851 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
9852 and the
9853 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
9854 variables for related information.
9855 </para>
9856 </glossdef>
9857 </glossentry>
9858
9859 <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
9860 <info>
9861 PACKAGE_EXTRA_ARCHS[doc] = "Specifies the list of architectures compatible with the device CPU. This variable is useful when you build for several different devices that use miscellaneous processors."
9862 </info>
9863 <glossdef>
9864 <para role="glossdeffirst">
9865 Specifies the list of architectures compatible with the device CPU.
9866 This variable is useful when you build for several different devices that use
9867 miscellaneous processors such as XScale and ARM926-EJS.
9868 </para>
9869 </glossdef>
9870 </glossentry>
9871
9872 <glossentry id='var-PACKAGE_FEED_ARCHS'><glossterm>PACKAGE_FEED_ARCHS</glossterm>
9873 <info>
9874 PACKAGE_FEED_ARCHS[doc] = "Optionally specifies user-defined package architectures when constructing package feed URIs."
9875 </info>
9876 <glossdef>
9877 <para role="glossdeffirst">
9878 Optionally specifies the package architectures used as
9879 part of the package feed URIs during the build.
9880 When used, the <filename>PACKAGE_FEED_ARCHS</filename>
9881 variable is appended to the final package feed URI, which
9882 is constructed using the
9883 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
9884 and
9885 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>
9886 variables.
9887 <note><title>Tip</title>
9888 You can use the <filename>PACKAGE_FEEDS_ARCHS</filename>
9889 variable to whitelist specific package architectures.
9890 If you do not need to whitelist specific architectures,
9891 which is a common case, you can omit this variable.
9892 Omitting the variable results in all available
9893 architectures for the current machine being included
9894 into remote package feeds.
9895 </note>
9896 </para>
9897
9898 <para>
9899 Consider the following example where the
9900 <filename>PACKAGE_FEED_URIS</filename>,
9901 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
9902 <filename>PACKAGE_FEED_ARCHS</filename> variables are
9903 defined in your <filename>local.conf</filename> file:
9904 <literallayout class='monospaced'>
9905 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
9906 https://example.com/packagerepos/updates"
9907 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
9908 PACKAGE_FEED_ARCHS = "all core2-64"
9909 </literallayout>
9910 Given these settings, the resulting package feeds are
9911 as follows:
9912 <literallayout class='monospaced'>
9913 https://example.com/packagerepos/release/rpm/all
9914 https://example.com/packagerepos/release/rpm/core2-64
9915 https://example.com/packagerepos/release/rpm-dev/all
9916 https://example.com/packagerepos/release/rpm-dev/core2-64
9917 https://example.com/packagerepos/updates/rpm/all
9918 https://example.com/packagerepos/updates/rpm/core2-64
9919 https://example.com/packagerepos/updates/rpm-dev/all
9920 https://example.com/packagerepos/updates/rpm-dev/core2-64
9921 </literallayout>
9922 </para>
9923 </glossdef>
9924 </glossentry>
9925
9926 <glossentry id='var-PACKAGE_FEED_BASE_PATHS'><glossterm>PACKAGE_FEED_BASE_PATHS</glossterm>
9927 <info>
9928 PACKAGE_FEED_BASE_PATHS[doc] = "Specifies base path used when constructing package feed URIs."
9929 </info>
9930 <glossdef>
9931 <para role="glossdeffirst">
9932 Specifies the base path used when constructing package feed
9933 URIs.
9934 The <filename>PACKAGE_FEED_BASE_PATHS</filename> variable
9935 makes up the middle portion of a package feed URI used
9936 by the OpenEmbedded build system.
9937 The base path lies between the
9938 <link linkend='var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></link>
9939 and
9940 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
9941 variables.
9942 </para>
9943
9944 <para>
9945 Consider the following example where the
9946 <filename>PACKAGE_FEED_URIS</filename>,
9947 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
9948 <filename>PACKAGE_FEED_ARCHS</filename> variables are
9949 defined in your <filename>local.conf</filename> file:
9950 <literallayout class='monospaced'>
9951 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
9952 https://example.com/packagerepos/updates"
9953 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
9954 PACKAGE_FEED_ARCHS = "all core2-64"
9955 </literallayout>
9956 Given these settings, the resulting package feeds are
9957 as follows:
9958 <literallayout class='monospaced'>
9959 https://example.com/packagerepos/release/rpm/all
9960 https://example.com/packagerepos/release/rpm/core2-64
9961 https://example.com/packagerepos/release/rpm-dev/all
9962 https://example.com/packagerepos/release/rpm-dev/core2-64
9963 https://example.com/packagerepos/updates/rpm/all
9964 https://example.com/packagerepos/updates/rpm/core2-64
9965 https://example.com/packagerepos/updates/rpm-dev/all
9966 https://example.com/packagerepos/updates/rpm-dev/core2-64
9967 </literallayout>
9968 </para>
9969 </glossdef>
9970 </glossentry>
9971
9972 <glossentry id='var-PACKAGE_FEED_URIS'><glossterm>PACKAGE_FEED_URIS</glossterm>
9973 <info>
9974 PACKAGE_FEED_URIS[doc] = "Specifies the front portion of the package feed URI used by the OpenEmbedded build system."
9975 </info>
9976 <glossdef>
9977 <para role="glossdeffirst">
9978 Specifies the front portion of the package feed URI
9979 used by the OpenEmbedded build system.
9980 Each final package feed URI is comprised of
9981 <filename>PACKAGE_FEED_URIS</filename>,
9982 <link linkend='var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></link>,
9983 and
9984 <link linkend='var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></link>
9985 variables.
9986 </para>
9987
9988 <para>
9989 Consider the following example where the
9990 <filename>PACKAGE_FEED_URIS</filename>,
9991 <filename>PACKAGE_FEED_BASE_PATHS</filename>, and
9992 <filename>PACKAGE_FEED_ARCHS</filename> variables are
9993 defined in your <filename>local.conf</filename> file:
9994 <literallayout class='monospaced'>
9995 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
9996 https://example.com/packagerepos/updates"
9997 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
9998 PACKAGE_FEED_ARCHS = "all core2-64"
9999 </literallayout>
10000 Given these settings, the resulting package feeds are
10001 as follows:
10002 <literallayout class='monospaced'>
10003 https://example.com/packagerepos/release/rpm/all
10004 https://example.com/packagerepos/release/rpm/core2-64
10005 https://example.com/packagerepos/release/rpm-dev/all
10006 https://example.com/packagerepos/release/rpm-dev/core2-64
10007 https://example.com/packagerepos/updates/rpm/all
10008 https://example.com/packagerepos/updates/rpm/core2-64
10009 https://example.com/packagerepos/updates/rpm-dev/all
10010 https://example.com/packagerepos/updates/rpm-dev/core2-64
10011 </literallayout>
10012 </para>
10013 </glossdef>
10014 </glossentry>
10015
10016 <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
10017 <info>
10018 PACKAGE_INSTALL[doc] = "List of the packages to be installed into the image. The variable is generally not user-defined and uses IMAGE_INSTALL as part of the list."
10019 </info>
10020 <glossdef>
10021 <para role="glossdeffirst">
10022 The final list of packages passed to the package manager
10023 for installation into the image.
10024 </para>
10025
10026 <para>
10027 Because the package manager controls actual installation
10028 of all packages, the list of packages passed using
10029 <filename>PACKAGE_INSTALL</filename> is not the final list
10030 of packages that are actually installed.
10031 This variable is internal to the image construction
10032 code.
10033 Consequently, in general, you should use the
10034 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
10035 variable to specify packages for installation.
10036 The exception to this is when working with
10037 the
10038 <link linkend='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename></link>
10039 image.
10040 When working with an initial RAM filesystem (initramfs)
10041 image, use the <filename>PACKAGE_INSTALL</filename>
10042 variable.
10043 For information on creating an initramfs, see the
10044 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
10045 section in the Yocto Project Development Tasks Manual.
10046 </para>
10047 </glossdef>
10048 </glossentry>
10049
10050 <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm>
10051 <info>
10052 PACKAGE_INSTALL_ATTEMPTONLY[doc] = "List of packages attempted to be installed when creating an image. If a listed package fails to install, the build system does not generate an error. This variable is generally not user-defined."
10053 </info>
10054 <glossdef>
10055 <para role="glossdeffirst">
10056 Specifies a list of packages the OpenEmbedded build
10057 system attempts to install when creating an image.
10058 If a listed package fails to install, the build system
10059 does not generate an error.
10060 This variable is generally not user-defined.
10061 </para>
10062 </glossdef>
10063 </glossentry>
10064
10065 <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm>
10066 <info>
10067 PACKAGE_PREPROCESS_FUNCS[doc] = "Specifies a list of functions run to pre-process the PKGD directory prior to splitting the files out to individual packages."
10068 </info>
10069 <glossdef>
10070 <para role="glossdeffirst">
10071 Specifies a list of functions run to pre-process the
10072 <link linkend='var-PKGD'><filename>PKGD</filename></link>
10073 directory prior to splitting the files out to individual
10074 packages.
10075 </para>
10076 </glossdef>
10077 </glossentry>
10078
10079 <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm>
10080 <info>
10081 PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools."
10082 </info>
10083 <glossdef>
10084 <para role="glossdeffirst">
10085 Specifies a list of dependencies for post-installation and
10086 pre-installation scripts on native/cross tools.
10087 If your post-installation or pre-installation script can
10088 execute at rootfs creation time rather than on the
10089 target but depends on a native tool in order to execute,
10090 you need to list the tools in
10091 <filename>PACKAGE_WRITE_DEPS</filename>.
10092 </para>
10093
10094 <para>
10095 For information on running post-installation scripts, see
10096 the
10097 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>"
10098 section in the Yocto Project Development Tasks Manual.
10099 </para>
10100 </glossdef>
10101 </glossentry>
10102
10103 <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
10104 <info>
10105 PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis."
10106 </info>
10107 <glossdef>
10108 <para role="glossdeffirst">
10109 This variable provides a means of enabling or disabling
10110 features of a recipe on a per-recipe basis.
10111 <filename>PACKAGECONFIG</filename> blocks are defined
10112 in recipes when you specify features and then arguments
10113 that define feature behaviors.
10114 Here is the basic block structure (broken over multiple
10115 lines for readability):
10116 <literallayout class='monospaced'>
10117 PACKAGECONFIG ??= "f1 f2 f3 ..."
10118 PACKAGECONFIG[f1] = "\
10119 --with-f1, \
10120 --without-f1, \
10121 build-deps-for-f1, \
10122 runtime-deps-for-f1, \
10123 runtime-recommends-for-f1, \
10124 packageconfig-conflicts-for-f1 \
10125 "
10126 PACKAGECONFIG[f2] = "\
10127 ... and so on and so on ...
10128 </literallayout>
10129 </para>
10130
10131 <para>
10132 The <filename>PACKAGECONFIG</filename>
10133 variable itself specifies a space-separated list of the
10134 features to enable.
10135 Following the features, you can determine the behavior of
10136 each feature by providing up to six order-dependent
10137 arguments, which are separated by commas.
10138 You can omit any argument you like but must retain the
10139 separating commas.
10140 The order is important and specifies the following:
10141 <orderedlist>
10142 <listitem><para>Extra arguments
10143 that should be added to the configure script
10144 argument list
10145 (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
10146 or
10147 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>)
10148 if the feature is enabled.</para></listitem>
10149 <listitem><para>Extra arguments
10150 that should be added to <filename>EXTRA_OECONF</filename>
10151 or <filename>PACKAGECONFIG_CONFARGS</filename>
10152 if the feature is disabled.
10153 </para></listitem>
10154 <listitem><para>Additional build dependencies
10155 (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
10156 that should be added if the feature is enabled.
10157 </para></listitem>
10158 <listitem><para>Additional runtime dependencies
10159 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10160 that should be added if the feature is enabled.
10161 </para></listitem>
10162 <listitem><para>Additional runtime recommendations
10163 (<link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>)
10164 that should be added if the feature is enabled.
10165 </para></listitem>
10166 <listitem><para>Any conflicting (that is, mutually
10167 exclusive) <filename>PACKAGECONFIG</filename>
10168 settings for this feature.
10169 </para></listitem>
10170 </orderedlist>
10171 </para>
10172
10173 <para>
10174 Consider the following
10175 <filename>PACKAGECONFIG</filename> block taken from the
10176 <filename>librsvg</filename> recipe.
10177 In this example the feature is <filename>gtk</filename>,
10178 which has three arguments that determine the feature's
10179 behavior.
10180 <literallayout class='monospaced'>
10181 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
10182 </literallayout>
10183 The <filename>--with-gtk3</filename> and
10184 <filename>gtk+3</filename> arguments apply only if
10185 the feature is enabled.
10186 In this case, <filename>--with-gtk3</filename> is
10187 added to the configure script argument list and
10188 <filename>gtk+3</filename> is added to
10189 <filename>DEPENDS</filename>.
10190 On the other hand, if the feature is disabled say through
10191 a <filename>.bbappend</filename> file in another layer, then
10192 the second argument <filename>--without-gtk3</filename> is
10193 added to the configure script instead.
10194 </para>
10195
10196 <para>
10197 The basic <filename>PACKAGECONFIG</filename> structure
10198 previously described holds true regardless of whether you
10199 are creating a block or changing a block.
10200 When creating a block, use the structure inside your
10201 recipe.
10202 </para>
10203
10204 <para>
10205 If you want to change an existing
10206 <filename>PACKAGECONFIG</filename> block, you can do so
10207 one of two ways:
10208 <itemizedlist>
10209 <listitem><para><emphasis>Append file:</emphasis>
10210 Create an append file named
10211 <replaceable>recipename</replaceable><filename>.bbappend</filename>
10212 in your layer and override the value of
10213 <filename>PACKAGECONFIG</filename>.
10214 You can either completely override the variable:
10215 <literallayout class='monospaced'>
10216 PACKAGECONFIG = "f4 f5"
10217 </literallayout>
10218 Or, you can just append the variable:
10219 <literallayout class='monospaced'>
10220 PACKAGECONFIG_append = " f4"
10221 </literallayout></para></listitem>
10222 <listitem><para><emphasis>Configuration file:</emphasis>
10223 This method is identical to changing the block
10224 through an append file except you edit your
10225 <filename>local.conf</filename> or
10226 <filename><replaceable>mydistro</replaceable>.conf</filename> file.
10227 As with append files previously described,
10228 you can either completely override the variable:
10229 <literallayout class='monospaced'>
10230 PACKAGECONFIG_pn-<replaceable>recipename</replaceable> = "f4 f5"
10231 </literallayout>
10232 Or, you can just amend the variable:
10233 <literallayout class='monospaced'>
10234 PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4"
10235 </literallayout></para></listitem>
10236 </itemizedlist>
10237 </para>
10238 </glossdef>
10239 </glossentry>
10240
10241 <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm>
10242 <info>
10243 PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from the PACKAGECONFIG setting."
10244 </info>
10245 <glossdef>
10246 <para role="glossdeffirst">
10247 A space-separated list of configuration options generated
10248 from the
10249 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
10250 setting.
10251 </para>
10252
10253 <para>
10254 Classes such as
10255 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
10256 and
10257 <link linkend='ref-classes-cmake'><filename>cmake</filename></link>
10258 use <filename>PACKAGECONFIG_CONFARGS</filename> to pass
10259 <filename>PACKAGECONFIG</filename> options to
10260 <filename>configure</filename> and
10261 <filename>cmake</filename>, respectively.
10262 If you are using
10263 <filename>PACKAGECONFIG</filename> but not a class that
10264 handles the <filename>do_configure</filename> task, then
10265 you need to use
10266 <filename>PACKAGECONFIG_CONFARGS</filename> appropriately.
10267 </para>
10268 </glossdef>
10269 </glossentry>
10270
10271 <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm>
10272 <info>
10273 PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe."
10274 </info>
10275 <glossdef>
10276 <para role="glossdeffirst">
10277 For recipes inheriting the
10278 <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link>
10279 class, setting
10280 <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to
10281 "1" specifies that the normal complementary packages
10282 (i.e. <filename>-dev</filename>,
10283 <filename>-dbg</filename>, and so forth) should not be
10284 automatically created by the
10285 <filename>packagegroup</filename> recipe, which is the
10286 default behavior.
10287 </para>
10288 </glossdef>
10289 </glossentry>
10290
10291 <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
10292 <info>
10293 PACKAGES[doc] = "The list of packages the recipe creates."
10294 </info>
10295 <glossdef>
10296 <para role="glossdeffirst">
10297 The list of packages the recipe creates.
10298 The default value is the following:
10299 <literallayout class='monospaced'>
10300 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
10301 </literallayout>
10302 </para>
10303
10304 <para>
10305 During packaging, the
10306 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10307 task goes through <filename>PACKAGES</filename> and uses
10308 the
10309 <link linkend='var-FILES'><filename>FILES</filename></link>
10310 variable corresponding to each package to assign files to
10311 the package.
10312 If a file matches the <filename>FILES</filename> variable
10313 for more than one package in <filename>PACKAGES</filename>,
10314 it will be assigned to the earliest (leftmost) package.
10315 </para>
10316
10317 <para>
10318 Packages in the variable's list that are empty (i.e. where
10319 none of the patterns in
10320 <filename>FILES_</filename><replaceable>pkg</replaceable>
10321 match any files installed by the
10322 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10323 task) are not generated, unless generation is forced through
10324 the
10325 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>
10326 variable.
10327 </para>
10328 </glossdef>
10329 </glossentry>
10330
10331 <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
10332 <info>
10333 PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes."
10334 </info>
10335 <glossdef>
10336 <para role="glossdeffirst">
10337 A promise that your recipe satisfies runtime dependencies
10338 for optional modules that are found in other recipes.
10339 <filename>PACKAGES_DYNAMIC</filename>
10340 does not actually satisfy the dependencies, it only states that
10341 they should be satisfied.
10342 For example, if a hard, runtime dependency
10343 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
10344 of another package is satisfied
10345 at build time through the <filename>PACKAGES_DYNAMIC</filename>
10346 variable, but a package with the module name is never actually
10347 produced, then the other package will be broken.
10348 Thus, if you attempt to include that package in an image,
10349 you will get a dependency failure from the packaging system
10350 during the
10351 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
10352 task.
10353 </para>
10354
10355 <para>
10356 Typically, if there is a chance that such a situation can
10357 occur and the package that is not created is valid
10358 without the dependency being satisfied, then you should use
10359 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
10360 (a soft runtime dependency) instead of
10361 <filename>RDEPENDS</filename>.
10362 </para>
10363
10364 <para>
10365 For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
10366 variable when you are splitting packages, see the
10367 "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
10368 in the Yocto Project Development Tasks Manual.
10369 </para>
10370 </glossdef>
10371 </glossentry>
10372
10373 <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm>
10374 <info>
10375 PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages."
10376 </info>
10377 <glossdef>
10378 <para role="glossdeffirst">
10379 Specifies a list of functions run to perform additional
10380 splitting of files into individual packages.
10381 Recipes can either prepend to this variable or prepend
10382 to the <filename>populate_packages</filename> function
10383 in order to perform additional package splitting.
10384 In either case, the function should set
10385 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>,
10386 <link linkend='var-FILES'><filename>FILES</filename></link>,
10387 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
10388 and other packaging variables appropriately in order to
10389 perform the desired splitting.
10390 </para>
10391 </glossdef>
10392 </glossentry>
10393
10394 <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
10395 <info>
10396 PARALLEL_MAKE[doc] = "Specifies extra options that are passed to the make command during the compile tasks. This variable is usually in the form -j x, where x represents the maximum number of parallel threads make can run."
10397 </info>
10398 <glossdef>
10399 <para role="glossdeffirst">
10400 Extra options passed to the <filename>make</filename>
10401 command during the
10402 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
10403 task in order to specify parallel compilation on the local
10404 build host.
10405 This variable is usually in the form "-j <replaceable>x</replaceable>",
10406 where <replaceable>x</replaceable> represents the maximum
10407 number of parallel threads <filename>make</filename> can
10408 run.
10409 <note><title>Caution</title>
10410 In order for <filename>PARALLEL_MAKE</filename> to be
10411 effective, <filename>make</filename> must be called
10412 with
10413 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10414 An easy way to ensure this is to use the
10415 <filename>oe_runmake</filename> function.
10416 </note>
10417 </para>
10418
10419 <para>
10420 By default, the OpenEmbedded build system automatically
10421 sets this variable to be equal to the number of cores the
10422 build system uses.
10423 <note>
10424 If the software being built experiences dependency
10425 issues during the <filename>do_compile</filename>
10426 task that result in race conditions, you can clear
10427 the <filename>PARALLEL_MAKE</filename> variable within
10428 the recipe as a workaround.
10429 For information on addressing race conditions, see the
10430 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
10431 section in the Yocto Project Development Tasks Manual.
10432 </note>
10433 For single socket systems (i.e. one CPU), you should not
10434 have to override this variable to gain optimal parallelism
10435 during builds.
10436 However, if you have very large systems that employ
10437 multiple physical CPUs, you might want to make sure the
10438 <filename>PARALLEL_MAKE</filename> variable is not
10439 set higher than "-j 20".
10440 </para>
10441
10442 <para>
10443 For more information on speeding up builds, see the
10444 "<ulink url='&YOCTO_DOCS_DEV_URL;#speeding-up-a-build'>Speeding Up a Build</ulink>"
10445 section in the Yocto Project Development Tasks Manual.
10446 </para>
10447 </glossdef>
10448 </glossentry>
10449
10450 <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
10451 <info>
10452 PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation."
10453 </info>
10454 <glossdef>
10455 <para role="glossdeffirst">
10456 Extra options passed to the
10457 <filename>make install</filename> command during the
10458 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
10459 task in order to specify parallel installation.
10460 This variable defaults to the value of
10461 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
10462 <note><title>Notes and Cautions</title>
10463 <para>In order for <filename>PARALLEL_MAKEINST</filename>
10464 to be
10465 effective, <filename>make</filename> must be called
10466 with
10467 <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>.
10468 An easy way to ensure this is to use the
10469 <filename>oe_runmake</filename> function.</para>
10470
10471 <para>If the software being built experiences
10472 dependency issues during the
10473 <filename>do_install</filename> task that result in
10474 race conditions, you can clear the
10475 <filename>PARALLEL_MAKEINST</filename> variable within
10476 the recipe as a workaround.
10477 For information on addressing race conditions, see the
10478 "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>"
10479 section in the Yocto Project Development Tasks Manual.
10480 </para>
10481 </note>
10482 </para>
10483 </glossdef>
10484 </glossentry>
10485
10486 <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
10487 <info>
10488 PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution."
10489 </info>
10490 <glossdef>
10491 <para role="glossdeffirst">
10492 Determines the action to take when a patch fails.
10493 You can set this variable to one of two values: "noop" and
10494 "user".
10495 </para>
10496
10497 <para>
10498 The default value of "noop" causes the build to simply fail
10499 when the OpenEmbedded build system cannot successfully
10500 apply a patch.
10501 Setting the value to "user" causes the build system to
10502 launch a shell and places you in the right location so that
10503 you can manually resolve the conflicts.
10504 </para>
10505
10506 <para>
10507 Set this variable in your
10508 <filename>local.conf</filename> file.
10509 </para>
10510 </glossdef>
10511 </glossentry>
10512
10513 <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
10514 <info>
10515 PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch."
10516 </info>
10517 <glossdef>
10518 <para role="glossdeffirst">
10519 Specifies the utility used to apply patches for a recipe
10520 during the
10521 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
10522 task.
10523 You can specify one of three utilities: "patch", "quilt", or
10524 "git".
10525 The default utility used is "quilt" except for the
10526 quilt-native recipe itself.
10527 Because the quilt tool is not available at the
10528 time quilt-native is being patched, it uses "patch".
10529 </para>
10530
10531 <para>
10532 If you wish to use an alternative patching tool, set the
10533 variable in the recipe using one of the following:
10534 <literallayout class='monospaced'>
10535 PATCHTOOL = "patch"
10536 PATCHTOOL = "quilt"
10537 PATCHTOOL = "git"
10538 </literallayout>
10539 </para>
10540 </glossdef>
10541 </glossentry>
10542
10543 <glossentry id='var-PE'><glossterm>PE</glossterm>
10544 <info>
10545 PE[doc] = "The epoch of the recipe. The default value is '0'. The field is used to make upgrades possible when the versioning scheme changes in some backwards incompatible way."
10546 </info>
10547 <glossdef>
10548 <para role="glossdeffirst">
10549 The epoch of the recipe.
10550 By default, this variable is unset.
10551 The variable is used to make upgrades possible when the
10552 versioning scheme changes in some backwards incompatible
10553 way.
10554 </para>
10555
10556 <para>
10557 <filename>PE</filename> is the default value of the
10558 <link linkend='var-PKGE'><filename>PKGE</filename></link>
10559 variable.
10560 </para>
10561 </glossdef>
10562 </glossentry>
10563
10564 <glossentry id='var-PF'><glossterm>PF</glossterm>
10565 <info>
10566 PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}."
10567 </info>
10568 <glossdef>
10569 <para role="glossdeffirst">
10570 Specifies the recipe or package name and includes all version and revision
10571 numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and
10572 <filename>bash-4.2-r1/</filename>).
10573 This variable is comprised of the following:
10574 <literallayout class='monospaced'>
10575 ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
10576 </literallayout>
10577 </para>
10578 </glossdef>
10579 </glossentry>
10580
10581 <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm>
10582 <info>
10583 PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf."
10584 </info>
10585 <glossdef>
10586 <para role="glossdeffirst">
10587 When inheriting the
10588 <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link>
10589 class, this variable identifies packages that contain
10590 the pixbuf loaders used with
10591 <filename>gdk-pixbuf</filename>.
10592 By default, the <filename>pixbufcache</filename> class
10593 assumes that the loaders are in the recipe's main package
10594 (i.e. <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
10595 Use this variable if the loaders you need are in a package
10596 other than that main package.
10597 </para>
10598 </glossdef>
10599 </glossentry>
10600
10601 <glossentry id='var-PKG'><glossterm>PKG</glossterm>
10602 <info>
10603 PKG[doc] = "The name of the resulting package created by the OpenEmbedded build system. When you use this variable, you must use a package name override."
10604 </info>
10605 <glossdef>
10606 <para role="glossdeffirst">
10607 The name of the resulting package created by the
10608 OpenEmbedded build system.
10609 <note>
10610 When using the <filename>PKG</filename> variable, you
10611 must use a package name override.
10612 </note>
10613 </para>
10614
10615 <para>
10616 For example, when the
10617 <link linkend='ref-classes-debian'><filename>debian</filename></link>
10618 class renames the output package, it does so by setting
10619 <filename>PKG_<replaceable>packagename</replaceable></filename>.
10620 </para>
10621 </glossdef>
10622 </glossentry>
10623
10624 <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm>
10625 <info>
10626 PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context."
10627 </info>
10628 <glossdef>
10629 <para role="glossdeffirst">
10630 The path to <filename>pkg-config</filename> files for the
10631 current build context.
10632 <filename>pkg-config</filename> reads this variable
10633 from the environment.
10634 </para>
10635 </glossdef>
10636 </glossentry>
10637
10638 <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
10639 <info>
10640 PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages."
10641 </info>
10642 <glossdef>
10643 <para role="glossdeffirst">
10644 Points to the destination directory for files to be
10645 packaged before they are split into individual packages.
10646 This directory defaults to the following:
10647 <literallayout class='monospaced'>
10648 ${WORKDIR}/package
10649 </literallayout>
10650 </para>
10651
10652 <para>
10653 Do not change this default.
10654 </para>
10655 </glossdef>
10656 </glossentry>
10657
10658 <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
10659 <info>
10660 PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process."
10661 </info>
10662 <glossdef>
10663 <para role="glossdeffirst">
10664 Points to a shared, global-state directory that holds data
10665 generated during the packaging process.
10666 During the packaging process, the
10667 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10668 task packages data for each recipe and installs it into
10669 this temporary, shared area.
10670 This directory defaults to the following, which you should
10671 not change:
10672 <literallayout class='monospaced'>
10673 ${STAGING_DIR_HOST}/pkgdata
10674 </literallayout>
10675 For examples of how this data is used, see the
10676 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
10677 section in the Yocto Project Overview and Concepts Manual
10678 and the
10679 "<ulink url='&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></ulink>"
10680 section in the Yocto Project Development Tasks Manual.
10681 For more information on the shared, global-state directory,
10682 see
10683 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
10684 </para>
10685 </glossdef>
10686 </glossentry>
10687
10688 <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
10689 <info>
10690 PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages."
10691 </info>
10692 <glossdef>
10693 <para role="glossdeffirst">
10694 Points to the parent directory for files to be packaged
10695 after they have been split into individual packages.
10696 This directory defaults to the following:
10697 <literallayout class='monospaced'>
10698 ${WORKDIR}/packages-split
10699 </literallayout>
10700 </para>
10701
10702 <para>
10703 Under this directory, the build system creates
10704 directories for each package specified in
10705 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
10706 Do not change this default.
10707 </para>
10708 </glossdef>
10709 </glossentry>
10710
10711 <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
10712 <info>
10713 PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata."
10714 </info>
10715 <glossdef>
10716 <para role="glossdeffirst">
10717 Points to a temporary work area where the
10718 <link linkend='ref-tasks-package'><filename>do_package</filename></link>
10719 task saves package metadata.
10720 The <filename>PKGDESTWORK</filename> location defaults to
10721 the following:
10722 <literallayout class='monospaced'>
10723 ${WORKDIR}/pkgdata
10724 </literallayout>
10725 Do not change this default.
10726 </para>
10727
10728 <para>
10729 The
10730 <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>
10731 task copies the package metadata from
10732 <filename>PKGDESTWORK</filename> to
10733 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
10734 to make it available globally.
10735 </para>
10736 </glossdef>
10737 </glossentry>
10738
10739 <glossentry id='var-PKGE'><glossterm>PKGE</glossterm>
10740 <info>
10741 PKGE[doc] = "The epoch of the package(s) built by the recipe."
10742 </info>
10743 <glossdef>
10744 <para role="glossdeffirst">
10745 The epoch of the package(s) built by the recipe.
10746 By default, <filename>PKGE</filename> is set to
10747 <link linkend='var-PE'><filename>PE</filename></link>.
10748 </para>
10749 </glossdef>
10750 </glossentry>
10751
10752 <glossentry id='var-PKGR'><glossterm>PKGR</glossterm>
10753 <info>
10754 PKGR[doc] = "The revision of the package(s) built by the recipe."
10755 </info>
10756 <glossdef>
10757 <para role="glossdeffirst">
10758 The revision of the package(s) built by the recipe.
10759 By default, <filename>PKGR</filename> is set to
10760 <link linkend='var-PR'><filename>PR</filename></link>.
10761 </para>
10762 </glossdef>
10763 </glossentry>
10764
10765 <glossentry id='var-PKGV'><glossterm>PKGV</glossterm>
10766 <info>
10767 PKGV[doc] = "The version of the package(s) built by the recipe."
10768 </info>
10769 <glossdef>
10770 <para role="glossdeffirst">
10771 The version of the package(s) built by the
10772 recipe.
10773 By default, <filename>PKGV</filename> is set to
10774 <link linkend='var-PV'><filename>PV</filename></link>.
10775 </para>
10776 </glossdef>
10777 </glossentry>
10778
10779 <glossentry id='var-PN'><glossterm>PN</glossterm>
10780 <info>
10781 PN[doc] = "PN refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package."
10782 </info>
10783 <glossdef>
10784 <para role="glossdeffirst">
10785 This variable can have two separate functions depending on the context: a recipe
10786 name or a resulting package name.
10787 </para>
10788
10789 <para>
10790 <filename>PN</filename> refers to a recipe name in the context of a file used
10791 by the OpenEmbedded build system as input to create a package.
10792 The name is normally extracted from the recipe file name.
10793 For example, if the recipe is named
10794 <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
10795 will be "expat".
10796 </para>
10797
10798 <para>
10799 The variable refers to a package name in the context of a file created or produced by the
10800 OpenEmbedded build system.
10801 </para>
10802
10803 <para>
10804 If applicable, the <filename>PN</filename> variable also contains any special
10805 suffix or prefix.
10806 For example, using <filename>bash</filename> to build packages for the native
10807 machine, <filename>PN</filename> is <filename>bash-native</filename>.
10808 Using <filename>bash</filename> to build packages for the target and for Multilib,
10809 <filename>PN</filename> would be <filename>bash</filename> and
10810 <filename>lib64-bash</filename>, respectively.
10811 </para>
10812 </glossdef>
10813 </glossentry>
10814
10815 <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm>
10816 <info>
10817 PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build."
10818 </info>
10819 <glossdef>
10820 <para role="glossdeffirst">
10821 Lists recipes you do not want the OpenEmbedded build system
10822 to build.
10823 This variable works in conjunction with the
10824 <link linkend='ref-classes-blacklist'><filename>blacklist</filename></link>
10825 class, which is inherited globally.
10826 </para>
10827
10828 <para>
10829 To prevent a recipe from being built, use the
10830 <filename>PNBLACKLIST</filename> variable in your
10831 <filename>local.conf</filename> file.
10832 Here is an example that prevents
10833 <filename>myrecipe</filename> from being built:
10834 <literallayout class='monospaced'>
10835 PNBLACKLIST[myrecipe] = "Not supported by our organization."
10836 </literallayout>
10837 </para>
10838 </glossdef>
10839 </glossentry>
10840
10841 <glossentry id='var-POPULATE_SDK_POST_HOST_COMMAND'><glossterm>POPULATE_SDK_POST_HOST_COMMAND</glossterm>
10842 <info>
10843 POPULATE_SDK_POST_HOST_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created host part of the SDK."
10844 </info>
10845 <glossdef>
10846 <para role="glossdeffirst">
10847 Specifies a list of functions to call once the
10848 OpenEmbedded build system has created the host part of
10849 the SDK.
10850 You can specify functions separated by semicolons:
10851 <literallayout class='monospaced'>
10852 POPULATE_SDK_POST_HOST_COMMAND += "<replaceable>function</replaceable>; ... "
10853 </literallayout>
10854 </para>
10855
10856 <para>
10857 If you need to pass the SDK path to a command
10858 within a function, you can use
10859 <filename>${SDK_DIR}</filename>, which points to
10860 the parent directory used by the OpenEmbedded build
10861 system when creating SDK output.
10862 See the
10863 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
10864 variable for more information.
10865 </para>
10866 </glossdef>
10867 </glossentry>
10868
10869 <glossentry id='var-POPULATE_SDK_POST_TARGET_COMMAND'><glossterm>POPULATE_SDK_POST_TARGET_COMMAND</glossterm>
10870 <info>
10871 POPULATE_SDK_POST_TARGET_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created target part of the SDK."
10872 </info>
10873 <glossdef>
10874 <para role="glossdeffirst">
10875 Specifies a list of functions to call once the
10876 OpenEmbedded build system has created the target part of
10877 the SDK.
10878 You can specify functions separated by semicolons:
10879 <literallayout class='monospaced'>
10880 POPULATE_SDK_POST_TARGET_COMMAND += "<replaceable>function</replaceable>; ... "
10881 </literallayout>
10882 </para>
10883
10884 <para>
10885 If you need to pass the SDK path to a command
10886 within a function, you can use
10887 <filename>${SDK_DIR}</filename>, which points to
10888 the parent directory used by the OpenEmbedded build
10889 system when creating SDK output.
10890 See the
10891 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
10892 variable for more information.
10893 </para>
10894 </glossdef>
10895 </glossentry>
10896
10897 <glossentry id='var-PR'><glossterm>PR</glossterm>
10898 <info>
10899 PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'."
10900 </info>
10901 <glossdef>
10902 <para role="glossdeffirst">
10903 The revision of the recipe. The default value for this
10904 variable is "r0".
10905 Subsequent revisions of the recipe conventionally have the
10906 values "r1", "r2", and so forth.
10907 When
10908 <link linkend='var-PV'><filename>PV</filename></link>
10909 increases, <filename>PR</filename> is conventionally reset
10910 to "r0".
10911 <note>
10912 The OpenEmbedded build system does not need the aid of
10913 <filename>PR</filename> to know when to rebuild a
10914 recipe.
10915 The build system uses the task
10916 <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>input checksums</ulink>
10917 along with the
10918 <link linkend='structure-build-tmp-stamps'>stamp</link>
10919 and
10920 <ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>shared state cache</ulink>
10921 mechanisms.
10922 </note>
10923 The <filename>PR</filename> variable primarily becomes
10924 significant when a package manager dynamically installs
10925 packages on an already built image.
10926 In this case, <filename>PR</filename>, which is the default
10927 value of
10928 <link linkend='var-PKGR'><filename>PKGR</filename></link>,
10929 helps the package manager distinguish which package is the
10930 most recent one in cases where many packages have the same
10931 <filename>PV</filename> (i.e. <filename>PKGV</filename>).
10932 A component having many packages with the same
10933 <filename>PV</filename> usually means that the packages all
10934 install the same upstream version, but with later
10935 (<filename>PR</filename>) version packages including
10936 packaging fixes.
10937 <note>
10938 <filename>PR</filename> does not need to be increased
10939 for changes that do not change the package contents or
10940 metadata.
10941 </note>
10942 Because manually managing <filename>PR</filename> can be
10943 cumbersome and error-prone, an automated solution exists.
10944 See the
10945 "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>"
10946 section in the Yocto Project Development Tasks Manual
10947 for more information.
10948 </para>
10949 </glossdef>
10950 </glossentry>
10951
10952 <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
10953 <info>
10954 PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference."
10955 </info>
10956 <glossdef>
10957 <para role="glossdeffirst">
10958 If multiple recipes provide the same item, this variable
10959 determines which recipe is preferred and thus provides
10960 the item (i.e. the preferred provider).
10961 You should always suffix this variable with the name of the
10962 provided item.
10963 And, you should define the variable using the preferred
10964 recipe's name
10965 (<link linkend='var-PN'><filename>PN</filename></link>).
10966 Here is a common example:
10967 <literallayout class='monospaced'>
10968 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
10969 </literallayout>
10970 In the previous example, multiple recipes are providing
10971 "virtual/kernel".
10972 The <filename>PREFERRED_PROVIDER</filename> variable is
10973 set with the name (<filename>PN</filename>) of the recipe
10974 you prefer to provide "virtual/kernel".
10975 </para>
10976
10977 <para>
10978 Following are more examples:
10979 <literallayout class='monospaced'>
10980 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
10981 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
10982 </literallayout>
10983 For more information, see the
10984 "<ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>Using Virtual Providers</ulink>"
10985 section in the Yocto Project Development Tasks Manual.
10986 <note>
10987 If you use a <filename>virtual/*</filename> item
10988 with <filename>PREFERRED_PROVIDER</filename>, then any
10989 recipe that
10990 <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
10991 that item but is not selected (defined) by
10992 <filename>PREFERRED_PROVIDER</filename> is prevented
10993 from building, which is usually desirable since this
10994 mechanism is designed to select between mutually
10995 exclusive alternative providers.
10996 </note>
10997 </para>
10998 </glossdef>
10999 </glossentry>
11000
11001 <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
11002 <info>
11003 PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference."
11004 </info>
11005 <glossdef>
11006 <para role="glossdeffirst">
11007 If multiple versions of recipes exist, this
11008 variable determines which version is given preference.
11009 You must always suffix the variable with the
11010 <link linkend='var-PN'><filename>PN</filename></link>
11011 you want to select, and you should set the
11012 <link linkend='var-PV'><filename>PV</filename></link>
11013 accordingly for precedence.
11014 </para>
11015
11016 <para>
11017 The <filename>PREFERRED_VERSION</filename> variable
11018 supports limited wildcard use through the
11019 "<filename>%</filename>" character.
11020 You can use the character to match any number of
11021 characters, which can be useful when specifying versions
11022 that contain long revision numbers that potentially change.
11023 Here are two examples:
11024 <literallayout class='monospaced'>
11025 PREFERRED_VERSION_python = "3.4.0"
11026 PREFERRED_VERSION_linux-yocto = "5.0%"
11027 </literallayout>
11028 <note><title>Important</title>
11029 The use of the "<filename>%</filename>" character
11030 is limited in that it only works at the end of the
11031 string.
11032 You cannot use the wildcard character in any other
11033 location of the string.
11034 </note>
11035 </para>
11036
11037 <para>
11038 The specified version is matched against
11039 <link linkend='var-PV'><filename>PV</filename></link>,
11040 which does not necessarily match the version part of
11041 the recipe's filename.
11042 For example, consider two recipes
11043 <filename>foo_1.2.bb</filename> and
11044 <filename>foo_git.bb</filename> where
11045 <filename>foo_git.bb</filename> contains the following
11046 assignment:
11047 <literallayout class='monospaced'>
11048 PV = "1.1+git${SRCPV}"
11049 </literallayout>
11050 In this case, the correct way to select
11051 <filename>foo_git.bb</filename> is by using an
11052 assignment such as the following:
11053 <literallayout class='monospaced'>
11054 PREFERRED_VERSION_foo = "1.1+git%"
11055 </literallayout>
11056 Compare that previous example against the following
11057 incorrect example, which does not work:
11058 <literallayout class='monospaced'>
11059 PREFERRED_VERSION_foo = "git"
11060 </literallayout>
11061 </para>
11062
11063 <para>
11064 Sometimes the <filename>PREFERRED_VERSION</filename>
11065 variable can be set by configuration files in a way that
11066 is hard to change.
11067 You can use
11068 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
11069 to set a machine-specific override.
11070 Here is an example:
11071 <literallayout class='monospaced'>
11072 PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%"
11073 </literallayout>
11074 Although not recommended, worst case, you can also use the
11075 "forcevariable" override, which is the strongest override
11076 possible.
11077 Here is an example:
11078 <literallayout class='monospaced'>
11079 PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%"
11080 </literallayout>
11081 <note>
11082 The <filename>_forcevariable</filename> override is
11083 not handled specially.
11084 This override only works because the default value of
11085 <filename>OVERRIDES</filename> includes
11086 "forcevariable".
11087 </note>
11088 </para>
11089 </glossdef>
11090 </glossentry>
11091
11092 <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
11093 <info>
11094 PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code."
11095 </info>
11096 <glossdef>
11097 <para role="glossdeffirst">
11098 Specifies additional paths from which the OpenEmbedded
11099 build system gets source code.
11100 When the build system searches for source code, it first
11101 tries the local download directory.
11102 If that location fails, the build system tries locations
11103 defined by <filename>PREMIRRORS</filename>, the upstream
11104 source, and then locations specified by
11105 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
11106 in that order.
11107 </para>
11108
11109 <para>
11110 Assuming your distribution
11111 (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
11112 is "poky", the default value for
11113 <filename>PREMIRRORS</filename> is defined in the
11114 <filename>conf/distro/poky.conf</filename> file in the
11115 <filename>meta-poky</filename> Git repository.
11116 </para>
11117
11118 <para>
11119 Typically, you could add a specific server for the
11120 build system to attempt before any others by adding
11121 something like the following to the
11122 <filename>local.conf</filename> configuration file in the
11123 <link linkend='build-directory'>Build Directory</link>:
11124 <literallayout class='monospaced'>
11125 PREMIRRORS_prepend = "\
11126 git://.*/.* http://www.yoctoproject.org/sources/ \n \
11127 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
11128 http://.*/.* http://www.yoctoproject.org/sources/ \n \
11129 https://.*/.* http://www.yoctoproject.org/sources/ \n"
11130 </literallayout>
11131 These changes cause the build system to intercept
11132 Git, FTP, HTTP, and HTTPS requests and direct them to
11133 the <filename>http://</filename> sources mirror.
11134 You can use <filename>file://</filename> URLs to point
11135 to local directories or network shares as well.
11136 </para>
11137 </glossdef>
11138 </glossentry>
11139
11140 <glossentry id='var-PRIORITY'><glossterm>PRIORITY</glossterm>
11141 <info>
11142 PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard', and 'extra'."
11143 </info>
11144 <glossdef>
11145 <para role="glossdeffirst">
11146 Indicates the importance of a package.
11147 </para>
11148
11149 <para>
11150 <filename>PRIORITY</filename> is considered to be part of
11151 the distribution policy because the importance of any given
11152 recipe depends on the purpose for which the distribution
11153 is being produced.
11154 Thus, <filename>PRIORITY</filename> is not normally set
11155 within recipes.
11156 </para>
11157
11158 <para>
11159 You can set <filename>PRIORITY</filename> to "required",
11160 "standard", "extra", and "optional", which is the default.
11161 </para>
11162 </glossdef>
11163 </glossentry>
11164
11165 <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm>
11166 <info>
11167 PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver."
11168 </info>
11169 <glossdef>
11170 <para role="glossdeffirst">
11171 Specifies libraries installed within a recipe that
11172 should be ignored by the OpenEmbedded build system's
11173 shared library resolver.
11174 This variable is typically used when software being
11175 built by a recipe has its own private versions of a
11176 library normally provided by another recipe.
11177 In this case, you would not want the package containing
11178 the private libraries to be set as a dependency on other
11179 unrelated packages that should instead depend on the
11180 package providing the standard version of the library.
11181 </para>
11182
11183 <para>
11184 Libraries specified in this variable should be specified
11185 by their file name.
11186 For example, from the Firefox recipe in meta-browser:
11187 <literallayout class='monospaced'>
11188 PRIVATE_LIBS = "libmozjs.so \
11189 libxpcom.so \
11190 libnspr4.so \
11191 libxul.so \
11192 libmozalloc.so \
11193 libplc4.so \
11194 libplds4.so"
11195 </literallayout>
11196 </para>
11197
11198 <para>
11199 For more information, see the
11200 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11201 section in the Yocto Project Overview and Concepts Manual.
11202 </para>
11203 </glossdef>
11204 </glossentry>
11205
11206 <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
11207 <info>
11208 PROVIDES[doc] = "A list of aliases that a recipe also provides. These aliases are useful for satisfying dependencies of other recipes during the build as specified by DEPENDS."
11209 </info>
11210 <glossdef>
11211 <para role="glossdeffirst">
11212 A list of aliases by which a particular recipe can be
11213 known.
11214 By default, a recipe's own
11215 <filename><link linkend='var-PN'>PN</link></filename>
11216 is implicitly already in its <filename>PROVIDES</filename>
11217 list and therefore does not need to mention that it provides itself.
11218 If a recipe uses <filename>PROVIDES</filename>, the
11219 additional aliases are synonyms for the recipe and can
11220 be useful for satisfying dependencies of other recipes during
11221 the build as specified by
11222 <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
11223 </para>
11224
11225 <para>
11226 Consider the following example
11227 <filename>PROVIDES</filename> statement from the recipe
11228 file <filename>eudev_3.2.9.bb</filename>:
11229 <literallayout class='monospaced'>
11230 PROVIDES = "udev"
11231 </literallayout>
11232 The <filename>PROVIDES</filename> statement results in
11233 the "eudev" recipe also being available as simply "udev".
11234
11235 <note>
11236 Given that a recipe's own recipe name is already
11237 implicitly in its own <filename>PROVIDES</filename> list,
11238 it is unnecessary to add aliases with the "+=" operator;
11239 using a simple assignment will be sufficient. In other
11240 words, while you could write:
11241 <literallayout class='monospaced'>
11242 PROVIDES += "udev"
11243 </literallayout>
11244 in the above, the "+=" is overkill and unnecessary.
11245 </note>
11246 </para>
11247
11248 <para>
11249 In addition to providing recipes under alternate names,
11250 the <filename>PROVIDES</filename> mechanism is also used
11251 to implement virtual targets.
11252 A virtual target is a name that corresponds to some
11253 particular functionality (e.g. a Linux kernel).
11254 Recipes that provide the functionality in question list the
11255 virtual target in <filename>PROVIDES</filename>.
11256 Recipes that depend on the functionality in question can
11257 include the virtual target in <filename>DEPENDS</filename>
11258 to leave the choice of provider open.
11259 </para>
11260
11261 <para>
11262 Conventionally, virtual targets have names on the form
11263 "virtual/function" (e.g. "virtual/kernel").
11264 The slash is simply part of the name and has no
11265 syntactical significance.
11266 </para>
11267
11268 <para>
11269 The
11270 <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link>
11271 variable is used to select which particular recipe
11272 provides a virtual target.
11273 <note>
11274 <para>A corresponding mechanism for virtual runtime
11275 dependencies (packages) exists.
11276 However, the mechanism does not depend on any special
11277 functionality beyond ordinary variable assignments.
11278 For example,
11279 <filename>VIRTUAL-RUNTIME_dev_manager</filename>
11280 refers to the package of the component that manages
11281 the <filename>/dev</filename> directory.</para>
11282
11283 <para>Setting the "preferred provider" for runtime
11284 dependencies is as simple as using the following
11285 assignment in a configuration file:</para>
11286 <literallayout class='monospaced'>
11287 VIRTUAL-RUNTIME_dev_manager = "udev"
11288 </literallayout>
11289 </note>
11290 </para>
11291 </glossdef>
11292 </glossentry>
11293
11294 <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm>
11295 <info>
11296 PRSERV_HOST[doc] = "The network based PR service host and port."
11297 </info>
11298 <glossdef>
11299 <para role="glossdeffirst">
11300 The network based
11301 <link linkend='var-PR'><filename>PR</filename></link>
11302 service host and port.
11303 </para>
11304
11305 <para>
11306 The <filename>conf/local.conf.sample.extended</filename>
11307 configuration file in the
11308 <link linkend='source-directory'>Source Directory</link>
11309 shows how the <filename>PRSERV_HOST</filename> variable is
11310 set:
11311 <literallayout class='monospaced'>
11312 PRSERV_HOST = "localhost:0"
11313 </literallayout>
11314 You must set the variable if you want to automatically
11315 start a local
11316 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>.
11317 You can set <filename>PRSERV_HOST</filename> to other
11318 values to use a remote PR service.
11319 </para>
11320 </glossdef>
11321 </glossentry>
11322
11323 <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm>
11324 <info>
11325 PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe."
11326 </info>
11327 <glossdef>
11328 <para role="glossdeffirst">
11329 Specifies whether or not
11330 <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink>
11331 (ptest) functionality is enabled when building a recipe.
11332 You should not set this variable directly.
11333 Enabling and disabling building Package Tests
11334 at build time should be done by adding "ptest" to (or
11335 removing it from)
11336 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
11337 </para>
11338 </glossdef>
11339 </glossentry>
11340
11341 <glossentry id='var-PV'><glossterm>PV</glossterm>
11342 <info>
11343 PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename."
11344 </info>
11345 <glossdef>
11346 <para role="glossdeffirst">
11347 The version of the recipe.
11348 The version is normally extracted from the recipe filename.
11349 For example, if the recipe is named
11350 <filename>expat_2.0.1.bb</filename>, then the default value
11351 of <filename>PV</filename> will be "2.0.1".
11352 <filename>PV</filename> is generally not overridden within
11353 a recipe unless it is building an unstable (i.e.
11354 development) version from a source code repository
11355 (e.g. Git or Subversion).
11356 </para>
11357
11358 <para>
11359 <filename>PV</filename> is the default value of the
11360 <link linkend='var-PKGV'><filename>PKGV</filename></link>
11361 variable.
11362 </para>
11363 </glossdef>
11364 </glossentry>
11365
11366 <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm>
11367 <info>
11368 PYTHON_ABI[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, denotes the Application Binary Interface (ABI) currently in use for Python."
11369 </info>
11370 <glossdef>
11371 <para role="glossdeffirst">
11372 When used by recipes that inherit the
11373 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11374 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11375 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11376 or
11377 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11378 classes, denotes the Application Binary Interface (ABI)
11379 currently in use for Python.
11380 By default, the ABI is "m".
11381 You do not have to set this variable as the OpenEmbedded
11382 build system sets it for you.
11383 </para>
11384
11385 <para>
11386 The OpenEmbedded build system uses the ABI to construct
11387 directory names used when installing the Python headers
11388 and libraries in sysroot
11389 (e.g. <filename>.../python3.3m/...</filename>).
11390 </para>
11391
11392 <para>
11393 Recipes that inherit the <filename>distutils</filename>
11394 class during cross-builds also use this variable to
11395 locate the headers and libraries of the appropriate Python
11396 that the extension is targeting.
11397 </para>
11398 </glossdef>
11399 </glossentry>
11400
11401 <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm>
11402 <info>
11403 PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built."
11404 </info>
11405 <glossdef>
11406 <para role="glossdeffirst">
11407 When used by recipes that inherit the
11408 <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>,
11409 <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>,
11410 <link linkend='ref-classes-distutils'><filename>distutils</filename></link>,
11411 or
11412 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
11413 classes, specifies the major Python version being built.
11414 For Python 3.x, <filename>PYTHON_PN</filename> would be
11415 "python3".
11416 You do not have to set this variable as the
11417 OpenEmbedded build system automatically sets it for you.
11418 </para>
11419
11420 <para>
11421 The variable allows recipes to use common infrastructure
11422 such as the following:
11423 <literallayout class='monospaced'>
11424 DEPENDS += "${PYTHON_PN}-native"
11425 </literallayout>
11426 In the previous example, the version of the dependency
11427 is <filename>PYTHON_PN</filename>.
11428 </para>
11429 </glossdef>
11430 </glossentry>
11431
11432 </glossdiv>
11433
11434 <glossdiv id='var-glossary-r'><title>R</title>
11435
11436 <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm>
11437 <info>
11438 RANLIB[doc] = "Minimal command and arguments to run 'ranlib'."
11439 </info>
11440 <glossdef>
11441 <para role="glossdeffirst">
11442 The minimal command and arguments to run
11443 <filename>ranlib</filename>.
11444 </para>
11445 </glossdef>
11446 </glossentry>
11447
11448 <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
11449 <info>
11450 RCONFLICTS[doc] = "The list of packages that conflict with another package. Note that the package will not be installed if the conflicting packages are not first removed."
11451 </info>
11452 <glossdef>
11453 <para role="glossdeffirst">
11454 The list of packages that conflict with packages.
11455 Note that packages will not be installed if conflicting
11456 packages are not first removed.
11457 </para>
11458
11459 <para>
11460 Like all package-controlling variables, you must always use
11461 them in conjunction with a package name override.
11462 Here is an example:
11463 <literallayout class='monospaced'>
11464 RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>"
11465 </literallayout>
11466 </para>
11467
11468 <para>
11469 BitBake, which the OpenEmbedded build system uses, supports
11470 specifying versioned dependencies.
11471 Although the syntax varies depending on the packaging
11472 format, BitBake hides these differences from you.
11473 Here is the general syntax to specify versions with
11474 the <filename>RCONFLICTS</filename> variable:
11475 <literallayout class='monospaced'>
11476 RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11477 </literallayout>
11478 For <filename>operator</filename>, you can specify the
11479 following:
11480 <literallayout class='monospaced'>
11481 =
11482 &lt;
11483 &gt;
11484 &lt;=
11485 &gt;=
11486 </literallayout>
11487 For example, the following sets up a dependency on version
11488 1.2 or greater of the package <filename>foo</filename>:
11489 <literallayout class='monospaced'>
11490 RCONFLICTS_${PN} = "foo (>= 1.2)"
11491 </literallayout>
11492 </para>
11493 </glossdef>
11494 </glossentry>
11495
11496 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
11497 <info>
11498 RDEPENDS[doc] = "Lists runtime dependencies of a package."
11499 </info>
11500 <glossdef>
11501 <para role="glossdeffirst">
11502 Lists runtime dependencies of a package.
11503 These dependencies are other packages that must be
11504 installed in order for the package to function correctly.
11505 As an example, the following assignment declares that the
11506 package <filename>foo</filename> needs the packages
11507 <filename>bar</filename> and <filename>baz</filename> to
11508 be installed:
11509 <literallayout class='monospaced'>
11510 RDEPENDS_foo = "bar baz"
11511 </literallayout>
11512 The most common types of package runtime dependencies are
11513 automatically detected and added.
11514 Therefore, most recipes do not need to set
11515 <filename>RDEPENDS</filename>.
11516 For more information, see the
11517 "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
11518 section in the Yocto Project Overview and Concepts Manual.
11519 </para>
11520
11521 <para>
11522 The practical effect of the above
11523 <filename>RDEPENDS</filename> assignment is that
11524 <filename>bar</filename> and <filename>baz</filename>
11525 will be declared as dependencies inside the package
11526 <filename>foo</filename> when it is written out by one of
11527 the
11528 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
11529 tasks.
11530 Exactly how this is done depends on which package format
11531 is used, which is determined by
11532 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>.
11533 When the corresponding package manager installs the
11534 package, it will know to also install the packages on
11535 which it depends.
11536 </para>
11537
11538 <para>
11539 To ensure that the packages <filename>bar</filename> and
11540 <filename>baz</filename> get built, the previous
11541 <filename>RDEPENDS</filename> assignment also causes a task
11542 dependency to be added.
11543 This dependency is from the recipe's
11544 <link linkend='ref-tasks-build'><filename>do_build</filename></link>
11545 (not to be confused with
11546 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>)
11547 task to the <filename>do_package_write_*</filename>
11548 task of the recipes that build <filename>bar</filename> and
11549 <filename>baz</filename>.
11550 </para>
11551
11552 <para>
11553 The names of the packages you list within
11554 <filename>RDEPENDS</filename> must be the names of other
11555 packages - they cannot be recipe names.
11556 Although package names and recipe names usually match,
11557 the important point here is that you are
11558 providing package names within the
11559 <filename>RDEPENDS</filename> variable.
11560 For an example of the default list of packages created from
11561 a recipe, see the
11562 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11563 variable.
11564 </para>
11565
11566 <para>
11567 Because the <filename>RDEPENDS</filename> variable applies
11568 to packages being built, you should always use the variable
11569 in a form with an attached package name (remember that a
11570 single recipe can build multiple packages).
11571 For example, suppose you are building a development package
11572 that depends on the <filename>perl</filename> package.
11573 In this case, you would use the following
11574 <filename>RDEPENDS</filename> statement:
11575 <literallayout class='monospaced'>
11576 RDEPENDS_${PN}-dev += "perl"
11577 </literallayout>
11578 In the example, the development package depends on
11579 the <filename>perl</filename> package.
11580 Thus, the <filename>RDEPENDS</filename> variable has the
11581 <filename>${PN}-dev</filename> package name as part of the
11582 variable.
11583 <note>
11584 <title>Caution</title>
11585 <filename>RDEPENDS_${PN}-dev</filename> includes
11586 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>
11587 by default.
11588 This default is set in the BitBake configuration file
11589 (<filename>meta/conf/bitbake.conf</filename>).
11590 Be careful not to accidentally remove
11591 <filename>${PN}</filename> when modifying
11592 <filename>RDEPENDS_${PN}-dev</filename>.
11593 Use the "+=" operator rather than the "=" operator.
11594 </note>
11595 </para>
11596
11597 <para>
11598 The package names you use with
11599 <filename>RDEPENDS</filename> must appear as they would in
11600 the <filename>PACKAGES</filename> variable.
11601 The
11602 <link linkend='var-PKG'><filename>PKG</filename></link>
11603 variable allows a different name to be used for
11604 the final package (e.g. the
11605 <link linkend='ref-classes-debian'><filename>debian</filename></link>
11606 class uses this to rename packages), but this final package
11607 name cannot be used with <filename>RDEPENDS</filename>,
11608 which makes sense as <filename>RDEPENDS</filename> is meant
11609 to be independent of the package format used.
11610 </para>
11611
11612 <para>
11613 BitBake, which the OpenEmbedded build system uses, supports
11614 specifying versioned dependencies.
11615 Although the syntax varies depending on the packaging
11616 format, BitBake hides these differences from you.
11617 Here is the general syntax to specify versions with
11618 the <filename>RDEPENDS</filename> variable:
11619 <literallayout class='monospaced'>
11620 RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11621 </literallayout>
11622 For <replaceable>operator</replaceable>, you can specify the
11623 following:
11624 <literallayout class='monospaced'>
11625 =
11626 &lt;
11627 &gt;
11628 &lt;=
11629 &gt;=
11630 </literallayout>
11631 For <replaceable>version</replaceable>, provide the version
11632 number.
11633 <note><title>Tip</title>
11634 You can use
11635 <link linkend='var-EXTENDPKGV'><filename>EXTENDPKGV</filename></link>
11636 to provide a full package version specification.
11637 </note>
11638 For example, the following sets up a dependency on version
11639 1.2 or greater of the package <filename>foo</filename>:
11640 <literallayout class='monospaced'>
11641 RDEPENDS_${PN} = "foo (>= 1.2)"
11642 </literallayout>
11643 </para>
11644
11645 <para>
11646 For information on build-time dependencies, see the
11647 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
11648 variable.
11649 You can also see the
11650 "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and
11651 "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>"
11652 sections in the BitBake User Manual for additional
11653 information on tasks and dependencies.
11654 </para>
11655 </glossdef>
11656 </glossentry>
11657
11658 <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm>
11659 <info>
11660 REQUIRED_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that must exist in the current configuration in order for the OpenEmbedded build system to build the recipe."
11661 </info>
11662 <glossdef>
11663 <para role="glossdeffirst">
11664 When inheriting the
11665 <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link>
11666 class, this
11667 variable identifies distribution features that must
11668 exist in the current configuration in order for the
11669 OpenEmbedded build system to build the recipe.
11670 In other words, if the
11671 <filename>REQUIRED_DISTRO_FEATURES</filename> variable
11672 lists a feature that does not appear in
11673 <filename>DISTRO_FEATURES</filename> within the
11674 current configuration, an error occurs and the
11675 build stops.
11676 </para>
11677 </glossdef>
11678 </glossentry>
11679
11680 <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
11681 <info>
11682 RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed."
11683 </info>
11684 <glossdef>
11685 <para role="glossdeffirst">
11686 With <filename>rm_work</filename> enabled, this
11687 variable specifies a list of recipes whose work directories
11688 should not be removed.
11689 See the "<link linkend='ref-classes-rm-work'><filename>rm_work.bbclass</filename></link>"
11690 section for more details.
11691 </para>
11692 </glossdef>
11693 </glossentry>
11694
11695 <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm>
11696 <info>
11697 ROOT_HOME[doc] = "Defines the root home directory."
11698 </info>
11699 <glossdef>
11700 <para role="glossdeffirst">
11701 Defines the root home directory.
11702 By default, this directory is set as follows in the
11703 BitBake configuration file:
11704 <literallayout class='monospaced'>
11705 ROOT_HOME ??= "/home/root"
11706 </literallayout>
11707 <note>
11708 This default value is likely used because some
11709 embedded solutions prefer to have a read-only root
11710 filesystem and prefer to keep writeable data in one
11711 place.
11712 </note>
11713 </para>
11714
11715 <para>
11716 You can override the default by setting the variable
11717 in any layer or in the <filename>local.conf</filename> file.
11718 Because the default is set using a "weak" assignment
11719 (i.e. "??="), you can use either of the following forms
11720 to define your override:
11721 <literallayout class='monospaced'>
11722 ROOT_HOME = "/root"
11723 ROOT_HOME ?= "/root"
11724 </literallayout>
11725 These override examples use <filename>/root</filename>,
11726 which is probably the most commonly used override.
11727 </para>
11728 </glossdef>
11729 </glossentry>
11730
11731 <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm>
11732 <info>
11733 ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem."
11734 </info>
11735 <glossdef>
11736 <para role="glossdeffirst">
11737 Indicates a filesystem image to include as the root
11738 filesystem.
11739 </para>
11740
11741 <para>
11742 The <filename>ROOTFS</filename> variable is an optional
11743 variable used with the
11744 <link linkend='ref-classes-image-live'><filename>image-live</filename></link>
11745 class.
11746 </para>
11747 </glossdef>
11748 </glossentry>
11749
11750 <glossentry id='var-ROOTFS_POSTINSTALL_COMMAND'><glossterm>ROOTFS_POSTINSTALL_COMMAND</glossterm>
11751 <info>
11752 ROOTFS_POSTINSTALL_COMMAND[doc] = "Specifies a list of functions to call after installing packages."
11753 </info>
11754 <glossdef>
11755 <para role="glossdeffirst">
11756 Specifies a list of functions to call after the
11757 OpenEmbedded build system has installed packages.
11758 You can specify functions separated by semicolons:
11759 <literallayout class='monospaced'>
11760 ROOTFS_POSTINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
11761 </literallayout>
11762 </para>
11763
11764 <para>
11765 If you need to pass the root filesystem path to a command
11766 within a function, you can use
11767 <filename>${IMAGE_ROOTFS}</filename>, which points to
11768 the directory that becomes the root filesystem image.
11769 See the
11770 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11771 variable for more information.
11772 </para>
11773 </glossdef>
11774 </glossentry>
11775
11776 <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
11777 <info>
11778 ROOTFS_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system has created the root filesystem."
11779 </info>
11780 <glossdef>
11781 <para role="glossdeffirst">
11782 Specifies a list of functions to call once the
11783 OpenEmbedded build system has created the root filesystem.
11784 You can specify functions separated by semicolons:
11785 <literallayout class='monospaced'>
11786 ROOTFS_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
11787 </literallayout>
11788 </para>
11789
11790 <para>
11791 If you need to pass the root filesystem path to a command
11792 within a function, you can use
11793 <filename>${IMAGE_ROOTFS}</filename>, which points to
11794 the directory that becomes the root filesystem image.
11795 See the
11796 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11797 variable for more information.
11798 </para>
11799 </glossdef>
11800 </glossentry>
11801
11802 <glossentry id='var-ROOTFS_POSTUNINSTALL_COMMAND'><glossterm>ROOTFS_POSTUNINSTALL_COMMAND</glossterm>
11803 <info>
11804 ROOTFS_POSTUNINSTALL_COMMAND[doc] = "Specifies a list of functions to call after removal of unneeded packages."
11805 </info>
11806 <glossdef>
11807 <para role="glossdeffirst">
11808 Specifies a list of functions to call after the
11809 OpenEmbedded build system has removed unnecessary
11810 packages.
11811 When runtime package management is disabled in the
11812 image, several packages are removed including
11813 <filename>base-passwd</filename>,
11814 <filename>shadow</filename>, and
11815 <filename>update-alternatives</filename>.
11816 You can specify functions separated by semicolons:
11817 <literallayout class='monospaced'>
11818 ROOTFS_POSTUNINSTALL_COMMAND += "<replaceable>function</replaceable>; ... "
11819 </literallayout>
11820 </para>
11821
11822 <para>
11823 If you need to pass the root filesystem path to a command
11824 within a function, you can use
11825 <filename>${IMAGE_ROOTFS}</filename>, which points to
11826 the directory that becomes the root filesystem image.
11827 See the
11828 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11829 variable for more information.
11830 </para>
11831 </glossdef>
11832 </glossentry>
11833
11834 <glossentry id='var-ROOTFS_PREPROCESS_COMMAND'><glossterm>ROOTFS_PREPROCESS_COMMAND</glossterm>
11835 <info>
11836 ROOTFS_PREPROCESS_COMMAND[doc] = "Specifies a list of functions to call before the OpenEmbedded build system has created the root filesystem."
11837 </info>
11838 <glossdef>
11839 <para role="glossdeffirst">
11840 Specifies a list of functions to call before the
11841 OpenEmbedded build system has created the root filesystem.
11842 You can specify functions separated by semicolons:
11843 <literallayout class='monospaced'>
11844 ROOTFS_PREPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
11845 </literallayout>
11846 </para>
11847
11848 <para>
11849 If you need to pass the root filesystem path to a command
11850 within a function, you can use
11851 <filename>${IMAGE_ROOTFS}</filename>, which points to
11852 the directory that becomes the root filesystem image.
11853 See the
11854 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
11855 variable for more information.
11856 </para>
11857 </glossdef>
11858 </glossentry>
11859
11860 <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
11861 <info>
11862 RPROVIDES[doc] = "A list of package name aliases that a package also provides. These aliases are useful for satisfying runtime dependencies of other packages both during the build and on the target."
11863 </info>
11864 <glossdef>
11865 <para role="glossdeffirst">
11866 A list of package name aliases that a package also provides.
11867 These aliases are useful for satisfying runtime dependencies
11868 of other packages both during the build and on the target
11869 (as specified by
11870 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
11871 <note>
11872 A package's own name is implicitly already in its
11873 <filename>RPROVIDES</filename> list.
11874 </note>
11875 </para>
11876
11877 <para>
11878 As with all package-controlling variables, you must always
11879 use the variable in conjunction with a package name override.
11880 Here is an example:
11881 <literallayout class='monospaced'>
11882 RPROVIDES_${PN} = "widget-abi-2"
11883 </literallayout>
11884 </para>
11885 </glossdef>
11886 </glossentry>
11887
11888 <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
11889 <info>
11890 RRECOMMENDS[doc] = "A list of packages that extends the usability of a package being built. The package being built does not depend on this list of packages in order to successfully build, but needs them for the extended usability."
11891 </info>
11892 <glossdef>
11893 <para role="glossdeffirst">
11894 A list of packages that extends the usability of a package
11895 being built.
11896 The package being built does not depend on this list of
11897 packages in order to successfully build, but rather
11898 uses them for extended usability.
11899 To specify runtime dependencies for packages, see the
11900 <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
11901 variable.
11902 </para>
11903
11904 <para>
11905 The package manager will automatically install the
11906 <filename>RRECOMMENDS</filename> list of packages when
11907 installing the built package.
11908 However, you can prevent listed packages from being
11909 installed by using the
11910 <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
11911 <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
11912 and
11913 <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
11914 variables.
11915 </para>
11916
11917 <para>
11918 Packages specified in
11919 <filename>RRECOMMENDS</filename> need not actually be
11920 produced.
11921 However, a recipe must exist that provides each package,
11922 either through the
11923 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
11924 or
11925 <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link>
11926 variables or the
11927 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>
11928 variable, or an error will occur during the build.
11929 If such a recipe does exist and the package is not produced,
11930 the build continues without error.
11931 </para>
11932
11933 <para>
11934 Because the <filename>RRECOMMENDS</filename> variable
11935 applies to packages being built, you should always attach
11936 an override to the variable to specify the particular
11937 package whose usability is being extended.
11938 For example, suppose you are building a development package
11939 that is extended to support wireless functionality.
11940 In this case, you would use the following:
11941 <literallayout class='monospaced'>
11942 RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>"
11943 </literallayout>
11944 In the example, the package name
11945 (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
11946 must appear as it would in the
11947 <filename>PACKAGES</filename> namespace before any renaming
11948 of the output package by classes such as
11949 <filename>debian.bbclass</filename>.
11950 </para>
11951
11952 <para>
11953 BitBake, which the OpenEmbedded build system uses, supports
11954 specifying versioned recommends.
11955 Although the syntax varies depending on the packaging
11956 format, BitBake hides these differences from you.
11957 Here is the general syntax to specify versions with
11958 the <filename>RRECOMMENDS</filename> variable:
11959 <literallayout class='monospaced'>
11960 RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
11961 </literallayout>
11962 For <filename>operator</filename>, you can specify the
11963 following:
11964 <literallayout class='monospaced'>
11965 =
11966 &lt;
11967 &gt;
11968 &lt;=
11969 &gt;=
11970 </literallayout>
11971 For example, the following sets up a recommend on version
11972 1.2 or greater of the package <filename>foo</filename>:
11973 <literallayout class='monospaced'>
11974 RRECOMMENDS_${PN} = "foo (>= 1.2)"
11975 </literallayout>
11976 </para>
11977 </glossdef>
11978 </glossentry>
11979
11980 <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
11981 <info>
11982 RREPLACES[doc] = "A list of packages replaced by a package. The package manager uses this variable to determine which package should be installed to replace other package(s) during an upgrade."
11983 </info>
11984 <glossdef>
11985 <para role="glossdeffirst">
11986 A list of packages replaced by a package.
11987 The package manager uses this variable to determine which
11988 package should be installed to replace other package(s)
11989 during an upgrade.
11990 In order to also have the other package(s) removed at the
11991 same time, you must add the name of the other
11992 package to the
11993 <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
11994 </para>
11995
11996 <para>
11997 As with all package-controlling variables, you must use
11998 this variable in conjunction with a package name
11999 override.
12000 Here is an example:
12001 <literallayout class='monospaced'>
12002 RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>"
12003 </literallayout>
12004 </para>
12005
12006 <para>
12007 BitBake, which the OpenEmbedded build system uses, supports
12008 specifying versioned replacements.
12009 Although the syntax varies depending on the packaging
12010 format, BitBake hides these differences from you.
12011 Here is the general syntax to specify versions with
12012 the <filename>RREPLACES</filename> variable:
12013 <literallayout class='monospaced'>
12014 RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)"
12015 </literallayout>
12016 For <filename>operator</filename>, you can specify the
12017 following:
12018 <literallayout class='monospaced'>
12019 =
12020 &lt;
12021 &gt;
12022 &lt;=
12023 &gt;=
12024 </literallayout>
12025 For example, the following sets up a replacement using
12026 version 1.2 or greater of the package
12027 <filename>foo</filename>:
12028 <literallayout class='monospaced'>
12029 RREPLACES_${PN} = "foo (>= 1.2)"
12030 </literallayout>
12031 </para>
12032 </glossdef>
12033 </glossentry>
12034
12035 <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
12036 <info>
12037 RSUGGESTS[doc] = "A list of additional packages that you can suggest for installation by the package manager at the time a package is installed. Not all package managers support this functionality."
12038 </info>
12039 <glossdef>
12040 <para role="glossdeffirst">
12041 A list of additional packages that you can suggest for
12042 installation by the package manager at the time a package
12043 is installed.
12044 Not all package managers support this functionality.
12045 </para>
12046
12047 <para>
12048 As with all package-controlling variables, you must always
12049 use this variable in conjunction with a package name
12050 override.
12051 Here is an example:
12052 <literallayout class='monospaced'>
12053 RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>"
12054 </literallayout>
12055 </para>
12056 </glossdef>
12057 </glossentry>
12058
12059 </glossdiv>
12060
12061 <glossdiv id='var-glossary-s'><title>S</title>
12062
12063 <glossentry id='var-S'><glossterm>S</glossterm>
12064 <info>
12065 S[doc] = "The location in the Build Directory where unpacked package source code resides."
12066 </info>
12067 <glossdef>
12068 <para role="glossdeffirst">
12069 The location in the
12070 <link linkend='build-directory'>Build Directory</link>
12071 where unpacked recipe source code resides.
12072 By default, this directory is
12073 <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/${</filename><link linkend='var-BPN'><filename>BPN</filename></link><filename>}-${</filename><link linkend='var-PV'><filename>PV</filename></link><filename>}</filename>,
12074 where <filename>${BPN}</filename> is the base recipe name
12075 and <filename>${PV}</filename> is the recipe version.
12076 If the source tarball extracts the code to a directory
12077 named anything other than <filename>${BPN}-${PV}</filename>,
12078 or if the source code is fetched from an SCM such as
12079 Git or Subversion, then you must set <filename>S</filename>
12080 in the recipe so that the OpenEmbedded build system
12081 knows where to find the unpacked source.
12082 </para>
12083
12084 <para>
12085 As an example, assume a
12086 <link linkend='source-directory'>Source Directory</link>
12087 top-level folder named <filename>poky</filename> and a
12088 default Build Directory at <filename>poky/build</filename>.
12089 In this case, the work directory the build system uses
12090 to keep the unpacked recipe for <filename>db</filename>
12091 is the following:
12092 <literallayout class='monospaced'>
12093 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
12094 </literallayout>
12095 The unpacked source code resides in the
12096 <filename>db-5.1.19</filename> folder.
12097 </para>
12098
12099 <para>
12100 This next example assumes a Git repository.
12101 By default, Git repositories are cloned to
12102 <filename>${WORKDIR}/git</filename> during
12103 <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>.
12104 Since this path is different from the default value of
12105 <filename>S</filename>, you must set it specifically
12106 so the source can be located:
12107 <literallayout class='monospaced'>
12108 SRC_URI = "git://path/to/repo.git"
12109 S = "${WORKDIR}/git"
12110 </literallayout>
12111 </para>
12112 </glossdef>
12113 </glossentry>
12114
12115 <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>SANITY_REQUIRED_UTILITIES</glossterm>
12116 <info>
12117 SANITY_REQUIRED_UTILITIES[doc] = "Specifies a list of command-line utilities that should be checked for during the initial sanity checking process when running BitBake."
12118 </info>
12119 <glossdef>
12120 <para role="glossdeffirst">
12121 Specifies a list of command-line utilities that should be
12122 checked for during the initial sanity checking process when
12123 running BitBake.
12124 If any of the utilities are not installed on the build host,
12125 then BitBake immediately exits with an error.
12126 </para>
12127 </glossdef>
12128 </glossentry>
12129
12130 <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
12131 <info>
12132 SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against."
12133 </info>
12134 <glossdef>
12135 <para role="glossdeffirst">
12136 A list of the host distribution identifiers that the
12137 build system has been tested against.
12138 Identifiers consist of the host distributor ID
12139 followed by the release,
12140 as reported by the <filename>lsb_release</filename> tool
12141 or as read from <filename>/etc/lsb-release</filename>.
12142 Separate the list items with explicit newline
12143 characters (<filename>\n</filename>).
12144 If <filename>SANITY_TESTED_DISTROS</filename> is not empty
12145 and the current value of
12146 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
12147 does not appear in the list, then the build system reports
12148 a warning that indicates the current host distribution has
12149 not been tested as a build host.
12150 </para>
12151 </glossdef>
12152 </glossentry>
12153
12154 <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
12155 <info>
12156 SDK_ARCH[doc] = "The target architecture for the SDK."
12157 </info>
12158 <glossdef>
12159 <para role="glossdeffirst">
12160 The target architecture for the SDK.
12161 Typically, you do not directly set this variable.
12162 Instead, use
12163 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
12164 </para>
12165 </glossdef>
12166 </glossentry>
12167
12168 <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm>
12169 <info>
12170 SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed."
12171 </info>
12172 <glossdef>
12173 <para role="glossdeffirst">
12174 The directory set up and used by the
12175 <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link>
12176 class to which the SDK is deployed.
12177 The <filename>populate_sdk_base</filename> class defines
12178 <filename>SDK_DEPLOY</filename> as follows:
12179 <literallayout class='monospaced'>
12180 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
12181 </literallayout>
12182 </para>
12183 </glossdef>
12184 </glossentry>
12185
12186 <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm>
12187 <info>
12188 SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output."
12189 </info>
12190 <glossdef>
12191 <para role="glossdeffirst">
12192 The parent directory used by the OpenEmbedded build system
12193 when creating SDK output.
12194 The
12195 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12196 class defines the variable as follows:
12197 <literallayout class='monospaced'>
12198 SDK_DIR = "${WORKDIR}/sdk"
12199 </literallayout>
12200 <note>
12201 The <filename>SDK_DIR</filename> directory is a
12202 temporary directory as it is part of
12203 <filename>WORKDIR</filename>.
12204 The final output directory is
12205 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12206 </note>
12207 </para>
12208 </glossdef>
12209 </glossentry>
12210
12211 <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm>
12212 <info>
12213 SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK."
12214 </info>
12215 <glossdef>
12216 <para role="glossdeffirst">
12217 Controls whether or not shared state artifacts are copied
12218 into the extensible SDK.
12219 The default value of "full" copies all of the required
12220 shared state artifacts into the extensible SDK.
12221 The value "minimal" leaves these artifacts out of the
12222 SDK.
12223 <note>
12224 If you set the variable to "minimal", you need to
12225 ensure
12226 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
12227 is set in the SDK's configuration to enable the
12228 artifacts to be fetched as needed.
12229 </note>
12230 </para>
12231 </glossdef>
12232 </glossentry>
12233
12234 <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm>
12235 <info>
12236 SDK_HOST_MANIFEST[doc] = "The manifest file for the host part of the SDK. This file lists all the installed packages that make up the host part of the SDK."
12237 </info>
12238 <glossdef>
12239 <para role="glossdeffirst">
12240 The manifest file for the host part of the SDK.
12241 This file lists all the installed packages that make up
12242 the host part of the SDK.
12243 The file contains package information on a line-per-package
12244 basis as follows:
12245 <literallayout class='monospaced'>
12246 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12247 </literallayout>
12248 </para>
12249
12250 <para>
12251 The
12252 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12253 class defines the manifest file as follows:
12254 <literallayout class='monospaced'>
12255 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
12256 </literallayout>
12257 The location is derived using the
12258 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12259 and
12260 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12261 variables.
12262 </para>
12263 </glossdef>
12264 </glossentry>
12265
12266 <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm>
12267 <info>
12268 SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target in the extensible SDK."
12269 </info>
12270 <glossdef>
12271 <para role="glossdeffirst">
12272 When set to "1", specifies to include the packagedata for
12273 all recipes in the "world" target in the extensible SDK.
12274 Including this data allows the
12275 <filename>devtool search</filename> command to find these
12276 recipes in search results, as well as allows the
12277 <filename>devtool add</filename> command to map
12278 dependencies more effectively.
12279 <note>
12280 Enabling the <filename>SDK_INCLUDE_PKGDATA</filename>
12281 variable significantly increases build time because
12282 all of world needs to be built.
12283 Enabling the variable also slightly increases the size
12284 of the extensible SDK.
12285 </note>
12286 </para>
12287 </glossdef>
12288 </glossentry>
12289
12290 <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm>
12291 <info>
12292 SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK."
12293 </info>
12294 <glossdef>
12295 <para role="glossdeffirst">
12296 When set to "1", specifies to include the toolchain in the
12297 extensible SDK.
12298 Including the toolchain is useful particularly when
12299 <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>
12300 is set to "minimal" to keep the SDK reasonably small
12301 but you still want to provide a usable toolchain.
12302 For example, suppose you want to use the toolchain from an
12303 IDE or from other tools and you do not
12304 want to perform additional steps to install the toolchain.
12305 </para>
12306
12307 <para>
12308 The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable
12309 defaults to "0" if <filename>SDK_EXT_TYPE</filename>
12310 is set to "minimal", and defaults to "1" if
12311 <filename>SDK_EXT_TYPE</filename> is set to "full".
12312 </para>
12313 </glossdef>
12314 </glossentry>
12315
12316 <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm>
12317 <info>
12318 SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration."
12319 </info>
12320 <glossdef>
12321 <para role="glossdeffirst">
12322 A list of classes to remove from the
12323 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
12324 value globally within the extensible SDK configuration.
12325 The
12326 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12327 class sets the default value:
12328 <literallayout class='monospaced'>
12329 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
12330 </literallayout>
12331 </para>
12332
12333 <para>
12334 Some classes are not generally applicable within
12335 the extensible SDK context.
12336 You can use this variable to disable those classes.
12337 </para>
12338
12339 <para>
12340 For additional information on how to customize the
12341 extensible SDK's configuration, see the
12342 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12343 section in the Yocto Project Application Development and
12344 the Extensible Software Development Kit (eSDK) manual.
12345 </para>
12346 </glossdef>
12347 </glossentry>
12348
12349 <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm>
12350 <info>
12351 SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration."
12352 </info>
12353 <glossdef>
12354 <para role="glossdeffirst">
12355 A list of variables not allowed through from the
12356 OpenEmbedded build system configuration into the extensible
12357 SDK configuration.
12358 Usually, these are variables that are specific to the
12359 machine on which the build system is running and thus
12360 would be potentially problematic within the extensible SDK.
12361 </para>
12362
12363 <para>By default,
12364 <filename>SDK_LOCAL_CONF_BLACKLIST</filename> is set in the
12365 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12366 class and excludes the following variables:
12367 <literallayout class='monospaced'>
12368 <link linkend='var-CONF_VERSION'>CONF_VERSION</link>
12369 <link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
12370 <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'>BB_NUMBER_PARSE_THREADS</ulink>
12371 <link linkend='var-PARALLEL_MAKE'>PARALLEL_MAKE</link>
12372 <link linkend='var-PRSERV_HOST'>PRSERV_HOST</link>
12373 <link linkend='var-SSTATE_MIRRORS'>SSTATE_MIRRORS</link>
12374 <link linkend='var-DL_DIR'>DL_DIR</link>
12375 <link linkend='var-SSTATE_DIR'>SSTATE_DIR</link>
12376 <link linkend='var-TMPDIR'>TMPDIR</link>
12377 <link linkend='var-BB_SERVER_TIMEOUT'>BB_SERVER_TIMEOUT</link>
12378 </literallayout>
12379 </para>
12380
12381 <para>
12382 For additional information on how to customize the
12383 extensible SDK's configuration, see the
12384 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12385 section in the Yocto Project Application Development and
12386 the Extensible Software Development Kit (eSDK) manual.
12387 </para>
12388
12389 </glossdef>
12390 </glossentry>
12391
12392 <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm>
12393 <info>
12394 SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration."
12395 </info>
12396 <glossdef>
12397 <para role="glossdeffirst">
12398 A list of variables allowed through from the OpenEmbedded
12399 build system configuration into the extensible SDK
12400 configuration.
12401 By default, the list of variables is empty and is set in
12402 the
12403 <link linkend='ref-classes-populate-sdk-*'><filename>populate-sdk-ext</filename></link>
12404 class.
12405 </para>
12406
12407 <para>
12408 This list overrides the variables specified using the
12409 <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>
12410 variable as well as any variables identified by automatic
12411 blacklisting due to the "/" character being found at the
12412 start of the value, which is usually indicative of being a
12413 path and thus might not be valid on the system where the
12414 SDK is installed.
12415 </para>
12416
12417 <para>
12418 For additional information on how to customize the
12419 extensible SDK's configuration, see the
12420 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk'>Configuring the Extensible SDK</ulink>"
12421 section in the Yocto Project Application Development and
12422 the Extensible Software Development Kit (eSDK) manual.
12423 </para>
12424 </glossdef>
12425 </glossentry>
12426
12427 <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
12428 <info>
12429 SDK_NAME[doc] = "The base name for SDK output files."
12430 </info>
12431 <glossdef>
12432 <para role="glossdeffirst">
12433 The base name for SDK output files.
12434 The name is derived from the
12435 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
12436 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
12437 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12438 <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
12439 and
12440 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
12441 variables:
12442 <literallayout class='monospaced'>
12443 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
12444 </literallayout>
12445 </para>
12446 </glossdef>
12447 </glossentry>
12448
12449 <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm>
12450 <info>
12451 SDK_OS[doc] = "The operating system for which the SDK will be built."
12452 </info>
12453 <glossdef>
12454 <para role="glossdeffirst">
12455 Specifies the operating system for which the SDK
12456 will be built.
12457 The default value is the value of
12458 <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>.
12459 </para>
12460 </glossdef>
12461 </glossentry>
12462
12463 <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm>
12464 <info>
12465 SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output."
12466 </info>
12467 <glossdef>
12468 <para role="glossdeffirst">
12469 The location used by the OpenEmbedded build system when
12470 creating SDK output.
12471 The
12472 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12473 class defines the variable as follows:
12474 <literallayout class='monospaced'>
12475 SDK_DIR = "${WORKDIR}/sdk"
12476 SDK_OUTPUT = "${SDK_DIR}/image"
12477 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
12478 </literallayout>
12479 <note>
12480 The <filename>SDK_OUTPUT</filename> directory is a
12481 temporary directory as it is part of
12482 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
12483 by way of
12484 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>.
12485 The final output directory is
12486 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>.
12487 </note>
12488 </para>
12489 </glossdef>
12490 </glossentry>
12491
12492 <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm>
12493 <info>
12494 SDK_PACKAGE_ARCHS[doc] = "Specifies a list of architectures compatible with the SDK machine. This variable is set automatically and should not normally be hand-edited."
12495 </info>
12496 <glossdef>
12497 <para role="glossdeffirst">
12498 Specifies a list of architectures compatible with
12499 the SDK machine.
12500 This variable is set automatically and should not
12501 normally be hand-edited.
12502 Entries are separated using spaces and listed in order
12503 of priority.
12504 The default value for
12505 <filename>SDK_PACKAGE_ARCHS</filename> is "all any noarch
12506 ${SDK_ARCH}-${SDKPKGSUFFIX}".
12507 </para>
12508 </glossdef>
12509 </glossentry>
12510
12511 <glossentry id='var-SDK_POSTPROCESS_COMMAND'><glossterm>SDK_POSTPROCESS_COMMAND</glossterm>
12512 <info>
12513 SDK_POSTPROCESS_COMMAND[doc] = "Specifies a list of functions to call once the OpenEmbedded build system creates the SDK."
12514 </info>
12515 <glossdef>
12516 <para role="glossdeffirst">
12517 Specifies a list of functions to call once the
12518 OpenEmbedded build system creates the SDK.
12519 You can specify functions separated by semicolons:
12520 <literallayout class='monospaced'>
12521 SDK_POSTPROCESS_COMMAND += "<replaceable>function</replaceable>; ... "
12522 </literallayout>
12523 </para>
12524
12525 <para>
12526 If you need to pass an SDK path to a command within a
12527 function, you can use
12528 <filename>${SDK_DIR}</filename>, which points to
12529 the parent directory used by the OpenEmbedded build system
12530 when creating SDK output.
12531 See the
12532 <link linkend='var-SDK_DIR'><filename>SDK_DIR</filename></link>
12533 variable for more information.
12534 </para>
12535 </glossdef>
12536 </glossentry>
12537
12538 <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm>
12539 <info>
12540 SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes."
12541 </info>
12542 <glossdef>
12543 <para role="glossdeffirst">
12544 The toolchain binary prefix used for
12545 <filename>nativesdk</filename> recipes.
12546 The OpenEmbedded build system uses the
12547 <filename>SDK_PREFIX</filename> value to set the
12548 <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>
12549 when building <filename>nativesdk</filename> recipes.
12550 The default value is "${SDK_SYS}-".
12551 </para>
12552 </glossdef>
12553 </glossentry>
12554
12555 <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm>
12556 <info>
12557 SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK."
12558 </info>
12559 <glossdef>
12560 <para role="glossdeffirst">
12561 A list of shared state tasks added to the extensible SDK.
12562 By default, the following tasks are added:
12563 <literallayout class='monospaced'>
12564 do_populate_lic
12565 do_package_qa
12566 do_populate_sysroot
12567 do_deploy
12568 </literallayout>
12569 Despite the default value of "" for the
12570 <filename>SDK_RECRDEP_TASKS</filename> variable, the
12571 above four tasks are always added to the SDK.
12572 To specify tasks beyond these four, you need to use
12573 the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g.
12574 you are defining additional tasks that are needed in
12575 order to build
12576 <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>).
12577 </para>
12578 </glossdef>
12579 </glossentry>
12580
12581 <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm>
12582 <info>
12583 SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built."
12584 </info>
12585 <glossdef>
12586 <para role="glossdeffirst">
12587 Specifies the system, including the architecture and the
12588 operating system, for which the SDK will be built.
12589 </para>
12590
12591 <para>
12592 The OpenEmbedded build system automatically sets this
12593 variable based on
12594 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
12595 <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>,
12596 and
12597 <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>.
12598 You do not need to set the <filename>SDK_SYS</filename>
12599 variable yourself.
12600 </para>
12601 </glossdef>
12602 </glossentry>
12603
12604 <glossentry id='var-SDK_TARGET_MANIFEST'><glossterm>SDK_TARGET_MANIFEST</glossterm>
12605 <info>
12606 SDK_TARGET_MANIFEST[doc] = "The manifest file for the target part of the SDK. This file lists all the installed packages that make up the target part of the SDK."
12607 </info>
12608 <glossdef>
12609 <para role="glossdeffirst">
12610 The manifest file for the target part of the SDK.
12611 This file lists all the installed packages that make up
12612 the target part of the SDK.
12613 The file contains package information on a line-per-package
12614 basis as follows:
12615 <literallayout class='monospaced'>
12616 <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable>
12617 </literallayout>
12618 </para>
12619
12620 <para>
12621 The
12622 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12623 class defines the manifest file as follows:
12624 <literallayout class='monospaced'>
12625 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
12626 </literallayout>
12627 The location is derived using the
12628 <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>
12629 and
12630 <link linkend='var-TOOLCHAIN_OUTPUTNAME'><filename>TOOLCHAIN_OUTPUTNAME</filename></link>
12631 variables.
12632 </para>
12633 </glossdef>
12634 </glossentry>
12635
12636 <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm>
12637 <info>
12638 SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation."
12639 </info>
12640 <glossdef>
12641 <para role="glossdeffirst">
12642 A list of targets to install from shared state as part of
12643 the standard or extensible SDK installation.
12644 The default value is "${PN}" (i.e. the image from which
12645 the SDK is built).
12646 </para>
12647
12648 <para>
12649 The <filename>SDK_TARGETS</filename> variable is an
12650 internal variable and typically would not be changed.
12651 </para>
12652 </glossdef>
12653 </glossentry>
12654
12655 <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm>
12656 <info>
12657 SDK_TITLE[doc] = "The title to be printed when running the SDK installer."
12658 </info>
12659 <glossdef>
12660 <para role="glossdeffirst">
12661 The title to be printed when running the SDK installer.
12662 By default, this title is based on the
12663 <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link>
12664 or
12665 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
12666 variable and is set in the
12667 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12668 class as follows:
12669 <literallayout class='monospaced'>
12670 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
12671 </literallayout>
12672 For the default distribution "poky",
12673 <filename>SDK_TITLE</filename> is set to
12674 "Poky (Yocto Project Reference Distro)".
12675 </para>
12676
12677 <para>
12678 For information on how to change this default title,
12679 see the
12680 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title'>Changing the Extensible SDK Installer Title</ulink>"
12681 section in the Yocto Project Application Development and
12682 the Extensible Software Development Kit (eSDK) manual.
12683 </para>
12684 </glossdef>
12685 </glossentry>
12686
12687 <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm>
12688 <info>
12689 SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK."
12690 </info>
12691 <glossdef>
12692 <para role="glossdeffirst">
12693 An optional URL for an update server for the extensible
12694 SDK.
12695 If set, the value is used as the default update server when
12696 running <filename>devtool sdk-update</filename> within the
12697 extensible SDK.
12698 </para>
12699 </glossdef>
12700 </glossentry>
12701
12702 <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm>
12703 <info>
12704 SDK_VENDOR[doc] = "Specifies the name of the SDK vendor."
12705 </info>
12706 <glossdef>
12707 <para role="glossdeffirst">
12708 Specifies the name of the SDK vendor.
12709 </para>
12710 </glossdef>
12711 </glossentry>
12712
12713 <glossentry id='var-SDK_VERSION'><glossterm>SDK_VERSION</glossterm>
12714 <info>
12715 SDK_VERSION[doc] = "Specifies the version for the SDK."
12716 </info>
12717 <glossdef>
12718 <para role="glossdeffirst">
12719 Specifies the version of the SDK.
12720 The distribution configuration file (e.g.
12721 <filename>/meta-poky/conf/distro/poky.conf</filename>)
12722 defines the <filename>SDK_VERSION</filename> as follows:
12723 <literallayout class='monospaced'>
12724 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
12725 </literallayout>
12726 </para>
12727
12728 <para>
12729 For additional information, see the
12730 <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link>
12731 and
12732 <link linkend='var-DATE'><filename>DATE</filename></link>
12733 variables.
12734 </para>
12735 </glossdef>
12736 </glossentry>
12737
12738 <glossentry id='var-SDKEXTPATH'><glossterm>SDKEXTPATH</glossterm>
12739 <info>
12740 SDKEXTPATH[doc] = "The default installation directory for the extensible SDK."
12741 </info>
12742 <glossdef>
12743 <para role="glossdeffirst">
12744 The default installation directory for the Extensible SDK.
12745 By default, this directory is based on the
12746 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>
12747 variable and is set in the
12748 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
12749 class as follows:
12750 <literallayout class='monospaced'>
12751 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
12752 </literallayout>
12753 For the default distribution "poky", the
12754 <filename>SDKEXTPATH</filename> is set to "poky_sdk".
12755 </para>
12756
12757 <para>
12758 For information on how to change this default directory,
12759 see the
12760 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory'>Changing the Default SDK Installation Directory</ulink>"
12761 section in the Yocto Project Application Development and
12762 the Extensible Software Development Kit (eSDK) manual.
12763 </para>
12764 </glossdef>
12765 </glossentry>
12766
12767 <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
12768 <info>
12769 SDKIMAGE_FEATURES[doc] = "Equivalent to IMAGE_FEATURES. However, this variable applies to the SDK generated from an image using the command 'bitbake -c populate_sdk imagename'."
12770 </info>
12771 <glossdef>
12772 <para role="glossdeffirst">
12773 Equivalent to
12774 <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
12775 However, this variable applies to the SDK generated from an
12776 image using the following command:
12777 <literallayout class='monospaced'>
12778 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
12779 </literallayout>
12780 </para>
12781 </glossdef>
12782 </glossentry>
12783
12784 <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
12785 <info>
12786 SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items."
12787 </info>
12788 <glossdef>
12789 <para role="glossdeffirst">
12790 The machine for which the SDK is built.
12791 In other words, the SDK is built such that it
12792 runs on the target you specify with the
12793 <filename>SDKMACHINE</filename> value.
12794 The value points to a corresponding
12795 <filename>.conf</filename> file under
12796 <filename>conf/machine-sdk/</filename>.
12797 </para>
12798
12799 <para>
12800 You can use "i686" and "x86_64" as possible values
12801 for this variable. The variable defaults to "i686"
12802 and is set in the local.conf file in the Build Directory.
12803 <literallayout class='monospaced'>
12804 SDKMACHINE ?= "i686"
12805 </literallayout>
12806 <note>
12807 You cannot set the <filename>SDKMACHINE</filename>
12808 variable in your distribution configuration file.
12809 If you do, the configuration will not take affect.
12810 </note>
12811 </para>
12812 </glossdef>
12813 </glossentry>
12814
12815 <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm>
12816 <info>
12817 SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system."
12818 </info>
12819 <glossdef>
12820 <para role="glossdeffirst">
12821 Defines the path offered to the user for installation
12822 of the SDK that is generated by the OpenEmbedded build
12823 system.
12824 The path appears as the default location for installing
12825 the SDK when you run the SDK's installation script.
12826 You can override the offered path when you run the
12827 script.
12828 </para>
12829 </glossdef>
12830 </glossentry>
12831
12832 <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm>
12833 <info>
12834 SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH."
12835 </info>
12836 <glossdef>
12837 <para role="glossdeffirst">
12838 The full path to the sysroot used for cross-compilation
12839 within an SDK as it will be when installed into the
12840 default
12841 <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>.
12842 </para>
12843 </glossdef>
12844 </glossentry>
12845
12846 <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
12847 <info>
12848 SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable."
12849 </info>
12850 <glossdef>
12851 <para role="glossdeffirst">
12852 The section in which packages should be categorized.
12853 Package management utilities can make use of this variable.
12854 </para>
12855 </glossdef>
12856 </glossentry>
12857
12858 <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
12859 <info>
12860 SELECTED_OPTIMIZATION[doc] = "The variable takes the value of FULL_OPTIMIZATION unless DEBUG_BUILD = '1'. In this case, the value of DEBUG_OPTIMIZATION is used."
12861 </info>
12862 <glossdef>
12863 <para role="glossdeffirst">
12864 Specifies the optimization flags passed to the C compiler
12865 when building for the target.
12866 The flags are passed through the default value of the
12867 <link linkend='var-TARGET_CFLAGS'><filename>TARGET_CFLAGS</filename></link>
12868 variable.
12869 </para>
12870
12871 <para>
12872 The <filename>SELECTED_OPTIMIZATION</filename> variable
12873 takes the value of
12874 <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
12875 unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
12876 If that is the case, the value of
12877 <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
12878 </para>
12879 </glossdef>
12880 </glossentry>
12881
12882 <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
12883 <info>
12884 SERIAL_CONSOLE[doc] = "Defines the serial consoles (TTYs) to enable using getty."
12885 </info>
12886 <glossdef>
12887 <para role="glossdeffirst">
12888 Defines a serial console (TTY) to enable using
12889 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
12890 Provide a value that specifies the baud rate followed by
12891 the TTY device name separated by a space.
12892 You cannot specify more than one TTY device:
12893 <literallayout class='monospaced'>
12894 SERIAL_CONSOLE = "115200 ttyS0"
12895 </literallayout>
12896 <note>
12897 The <filename>SERIAL_CONSOLE</filename> variable
12898 is deprecated.
12899 Please use the
12900 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
12901 variable.
12902 </note>
12903 </para>
12904 </glossdef>
12905 </glossentry>
12906
12907 <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
12908 <info>
12909 SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty."
12910 </info>
12911 <glossdef>
12912 <para role="glossdeffirst">
12913 Defines a serial console (TTY) to enable using
12914 <ulink url='https://en.wikipedia.org/wiki/Getty_(Unix)'>getty</ulink>.
12915 Provide a value that specifies the baud rate followed by
12916 the TTY device name separated by a semicolon.
12917 Use spaces to separate multiple devices:
12918 <literallayout class='monospaced'>
12919 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
12920 </literallayout>
12921 </para>
12922 </glossdef>
12923 </glossentry>
12924
12925 <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
12926 <info>
12927 SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit."
12928 </info>
12929 <glossdef>
12930 <para role="glossdeffirst">
12931 Specifies serial consoles, which must be listed in
12932 <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>,
12933 to check against <filename>/proc/console</filename>
12934 before enabling them using getty.
12935 This variable allows aliasing in the format:
12936 &lt;device&gt;:&lt;alias&gt;.
12937 If a device was listed as "sclp_line0"
12938 in <filename>/dev/</filename> and "ttyS0" was listed
12939 in <filename>/proc/console</filename>, you would do the
12940 following:
12941 <literallayout class='monospaced'>
12942 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
12943 </literallayout>
12944 This variable is currently only supported with SysVinit
12945 (i.e. not with systemd).
12946 </para>
12947 </glossdef>
12948 </glossentry>
12949
12950 <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
12951 <info>
12952 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS[doc] = "A list of recipe dependencies that should not be used to determine signatures of tasks from one recipe when they depend on tasks from another recipe."
12953 </info>
12954 <glossdef>
12955 <para role="glossdeffirst">
12956 A list of recipe dependencies that should not be used to
12957 determine signatures of tasks from one recipe when they
12958 depend on tasks from another recipe.
12959 For example:
12960 <literallayout class='monospaced'>
12961 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
12962 </literallayout>
12963 </para>
12964
12965 <para>
12966 In the previous example, <filename>intone</filename>
12967 depends on <filename>mplayer2</filename>.
12968 </para>
12969
12970 <para>
12971 You can use the special token <filename>"*"</filename> on
12972 the left-hand side of the dependency to match all
12973 recipes except the one on the right-hand side.
12974 Here is an example:
12975 <literallayout class='monospaced'>
12976 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
12977 </literallayout>
12978 </para>
12979
12980 <para>
12981 In the previous example, all recipes except
12982 <filename>quilt-native</filename> ignore task
12983 signatures from the <filename>quilt-native</filename>
12984 recipe when determining their task signatures.
12985 </para>
12986
12987 <para>
12988 Use of this variable is one mechanism to remove dependencies
12989 that affect task signatures and thus force rebuilds when a
12990 recipe changes.
12991 <note><title>Caution</title>
12992 If you add an inappropriate dependency for a recipe
12993 relationship, the software might break during
12994 runtime if the interface of the second recipe was
12995 changed after the first recipe had been built.
12996 </note>
12997 </para>
12998 </glossdef>
12999 </glossentry>
13000
13001 <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
13002 <info>
13003 SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change."
13004 </info>
13005 <glossdef>
13006 <para role="glossdeffirst">
13007 A list of recipes that are completely stable and will
13008 never change.
13009 The ABI for the recipes in the list are presented by
13010 output from the tasks run to build the recipe.
13011 Use of this variable is one way to remove dependencies from
13012 one recipe on another that affect task signatures and
13013 thus force rebuilds when the recipe changes.
13014 <note><title>Caution</title>
13015 If you add an inappropriate variable to this list,
13016 the software might break at runtime if the
13017 interface of the recipe was changed after the other
13018 had been built.
13019 </note>
13020 </para>
13021 </glossdef>
13022 </glossentry>
13023
13024 <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
13025 <info>
13026 SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU."
13027 </info>
13028 <glossdef>
13029 <para role="glossdeffirst">
13030 Specifies the number of bits for the target system CPU.
13031 The value should be either "32" or "64".
13032 </para>
13033 </glossdef>
13034 </glossentry>
13035
13036 <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
13037 <info>
13038 SITEINFO_ENDIANNESS[doc] = "Specifies the endian byte order of the target system. The value should be either 'le' for 'little-endian' or 'be' for 'big-endian'."
13039 </info>
13040 <glossdef>
13041 <para role="glossdeffirst">
13042 Specifies the endian byte order of the target system.
13043 The value should be either "le" for little-endian or "be" for big-endian.
13044 </para>
13045 </glossdef>
13046 </glossentry>
13047
13048 <glossentry id='var-SKIP_FILEDEPS'><glossterm>SKIP_FILEDEPS</glossterm>
13049 <info>
13050 SKIP_FILEDEPS[doc] = "Enables you to remove all files from the 'Provides' section of an RPM package."
13051 </info>
13052 <glossdef>
13053 <para role="glossdeffirst">
13054 Enables removal of all files from the "Provides" section of
13055 an RPM package.
13056 Removal of these files is required for packages containing
13057 prebuilt binaries and libraries such as
13058 <filename>libstdc++</filename> and
13059 <filename>glibc</filename>.
13060 </para>
13061
13062 <para>
13063 To enable file removal, set the variable to "1" in your
13064 <filename>conf/local.conf</filename> configuration file
13065 in your:
13066 <link linkend='build-directory'>Build Directory</link>.
13067 <literallayout class='monospaced'>
13068 SKIP_FILEDEPS = "1"
13069 </literallayout>
13070 </para>
13071 </glossdef>
13072 </glossentry>
13073
13074 <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
13075 <info>
13076 SOC_FAMILY[doc] = "Groups together machines based upon the same family of SOC (System On Chip). You typically set this variable in a common .inc file that you include in the configuration files of all the machines."
13077 </info>
13078 <glossdef>
13079 <para role="glossdeffirst">
13080 Groups together machines based upon the same family
13081 of SOC (System On Chip).
13082 You typically set this variable in a common
13083 <filename>.inc</filename> file that you include in the
13084 configuration files of all the machines.
13085 <note>
13086 You must include
13087 <filename>conf/machine/include/soc-family.inc</filename>
13088 for this variable to appear in
13089 <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
13090 </note>
13091 </para>
13092 </glossdef>
13093 </glossentry>
13094
13095 <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
13096 <info>
13097 SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform."
13098 </info>
13099 <glossdef>
13100 <para role="glossdeffirst">
13101 Defines the suffix for shared libraries used on the
13102 target platform.
13103 By default, this suffix is ".so.*" for all Linux-based
13104 systems and is defined in the
13105 <filename>meta/conf/bitbake.conf</filename> configuration
13106 file.
13107 </para>
13108
13109 <para>
13110 You will see this variable referenced in the default values
13111 of <filename>FILES_${PN}</filename>.
13112 </para>
13113 </glossdef>
13114 </glossentry>
13115
13116 <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
13117 <info>
13118 SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform."
13119 </info>
13120 <glossdef>
13121 <para role="glossdeffirst">
13122 Defines the suffix for the development symbolic link
13123 (symlink) for shared libraries on the target platform.
13124 By default, this suffix is ".so" for Linux-based
13125 systems and is defined in the
13126 <filename>meta/conf/bitbake.conf</filename> configuration
13127 file.
13128 </para>
13129
13130 <para>
13131 You will see this variable referenced in the default values
13132 of <filename>FILES_${PN}-dev</filename>.
13133 </para>
13134 </glossdef>
13135 </glossentry>
13136
13137 <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm>
13138 <info>
13139 SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks."
13140 </info>
13141 <glossdef>
13142 <para role="glossdeffirst">
13143 When you are fetching files to create a mirror of sources
13144 (i.e. creating a source mirror), setting
13145 <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your
13146 <filename>local.conf</filename> configuration file ensures
13147 the source for all recipes are fetched regardless of
13148 whether or not a recipe is compatible with the
13149 configuration.
13150 A recipe is considered incompatible with the currently
13151 configured machine when either or both the
13152 <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link>
13153 variable and
13154 <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link>
13155 variables specify compatibility with a machine other
13156 than that of the current machine or host.
13157 <note><title>Warning</title>
13158 Do not set the
13159 <filename>SOURCE_MIRROR_FETCH</filename> variable
13160 unless you are creating a source mirror.
13161 In other words, do not set the variable during a
13162 normal build.
13163 </note>
13164 </para>
13165 </glossdef>
13166 </glossentry>
13167
13168 <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm>
13169 <info>
13170 SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI."
13171 </info>
13172 <glossdef>
13173 <para role="glossdeffirst">
13174 Defines your own
13175 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13176 from which to first fetch source before attempting to fetch
13177 from the upstream specified in
13178 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
13179 </para>
13180
13181 <para>
13182 To use this variable, you must globally inherit the
13183 <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link>
13184 class and then provide the URL to your mirrors.
13185 Here is the general syntax:
13186 <literallayout class='monospaced'>
13187 INHERIT += "own-mirrors"
13188 SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>"
13189 </literallayout>
13190 <note>
13191 You can specify only a single URL in
13192 <filename>SOURCE_MIRROR_URL</filename>.
13193 </note>
13194 </para>
13195 </glossdef>
13196 </glossentry>
13197
13198 <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm>
13199 <info>
13200 SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/."
13201 </info>
13202 <glossdef>
13203 <para role="glossdeffirst">
13204 Maps commonly used license names to their SPDX counterparts
13205 found in <filename>meta/files/common-licenses/</filename>.
13206 For the default <filename>SPDXLICENSEMAP</filename>
13207 mappings, see the
13208 <filename>meta/conf/licenses.conf</filename> file.
13209 </para>
13210
13211 <para>
13212 For additional information, see the
13213 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
13214 variable.
13215 </para>
13216 </glossdef>
13217 </glossentry>
13218
13219 <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
13220 <info>
13221 SPECIAL_PKGSUFFIX[doc] = "A list of prefixes for PN used by the OpenEmbedded build system to create variants of recipes or packages. The list specifies the prefixes to strip off during certain circumstances such as the generation of the BPN variable."
13222 </info>
13223 <glossdef>
13224 <para role="glossdeffirst">
13225 A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
13226 OpenEmbedded build system to create variants of recipes or packages.
13227 The list specifies the prefixes to strip off during certain circumstances
13228 such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
13229 </para>
13230 </glossdef>
13231 </glossentry>
13232
13233 <glossentry id='var-SPL_BINARY'><glossterm>SPL_BINARY</glossterm>
13234 <info>
13235 SPL_BINARY[doc] = "The file type of the Secondary Program Loader (SPL)."
13236 </info>
13237 <glossdef>
13238 <para role="glossdeffirst">
13239 The file type for the Secondary Program Loader (SPL).
13240 Some devices use an SPL from which to boot (e.g. the
13241 BeagleBone development board).
13242 For such cases, you can declare the file type of the
13243 SPL binary in the <filename>u-boot.inc</filename> include
13244 file, which is used in the U-Boot recipe.
13245 </para>
13246
13247 <para>
13248 The SPL file type is set to "null" by default in the
13249 <filename>u-boot.inc</filename> file as follows:
13250 <literallayout class='monospaced'>
13251 # Some versions of u-boot build an SPL (Second Program Loader) image that
13252 # should be packaged along with the u-boot binary as well as placed in the
13253 # deploy directory. For those versions they can set the following variables
13254 # to allow packaging the SPL.
13255 SPL_BINARY ?= ""
13256 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
13257 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
13258 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
13259 </literallayout>
13260 The <filename>SPL_BINARY</filename> variable helps form
13261 various <filename>SPL_*</filename> variables used by
13262 the OpenEmbedded build system.
13263 </para>
13264
13265 <para>
13266 See the BeagleBone machine configuration example in the
13267 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
13268 section in the Yocto Project Board Support Package
13269 Developer's Guide for additional information.
13270 </para>
13271 </glossdef>
13272 </glossentry>
13273
13274 <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
13275 <info>
13276 SRC_URI[doc] = "The list of source files - local or remote. This variable tells the OpenEmbedded build system what bits to pull in for the build and how to pull them in."
13277 </info>
13278 <glossdef>
13279 <para role="glossdeffirst">
13280 The list of source files - local or remote.
13281 This variable tells the OpenEmbedded build system which bits
13282 to pull in for the build and how to pull them in.
13283 For example, if the recipe or append file only needs to
13284 fetch a tarball from the Internet, the recipe or
13285 append file uses a single <filename>SRC_URI</filename>
13286 entry.
13287 On the other hand, if the recipe or append file needs to
13288 fetch a tarball, apply two patches, and include a custom
13289 file, the recipe or append file would include four
13290 instances of the variable.
13291 </para>
13292
13293 <para>
13294 The following list explains the available URI protocols.
13295 URI protocols are highly dependent on particular BitBake
13296 Fetcher submodules.
13297 Depending on the fetcher BitBake uses, various URL
13298 parameters are employed.
13299 For specifics on the supported Fetchers, see the
13300 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
13301 section in the BitBake User Manual.
13302 <itemizedlist>
13303 <listitem><para><emphasis><filename>file://</filename> -</emphasis>
13304 Fetches files, which are usually files shipped with
13305 the
13306 <link linkend='metadata'>Metadata</link>,
13307 from the local machine (e.g.
13308 <ulink url='&YOCTO_DOCS_OM_URL;#patching-dev-environment'>patch</ulink>
13309 files).
13310 The path is relative to the
13311 <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
13312 variable.
13313 Thus, the build system searches, in order, from the
13314 following directories, which are assumed to be a
13315 subdirectories of the directory in which the
13316 recipe file (<filename>.bb</filename>) or
13317 append file (<filename>.bbappend</filename>)
13318 resides:
13319 <itemizedlist>
13320 <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
13321 The base recipe name without any special
13322 suffix or version numbers.
13323 </para></listitem>
13324 <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
13325 <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
13326 The base recipe name and version but without
13327 any special package name suffix.
13328 </para></listitem>
13329 <listitem><para><emphasis>files -</emphasis>
13330 Files within a directory, which is named
13331 <filename>files</filename> and is also
13332 alongside the recipe or append file.
13333 </para></listitem>
13334 </itemizedlist>
13335 <note>
13336 If you want the build system to pick up files
13337 specified through a
13338 <filename>SRC_URI</filename>
13339 statement from your append file, you need to be
13340 sure to extend the
13341 <filename>FILESPATH</filename>
13342 variable by also using the
13343 <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
13344 variable from within your append file.
13345 </note>
13346 </para></listitem>
13347 <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
13348 Bazaar revision control repository.</para></listitem>
13349 <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
13350 Git revision control repository.</para></listitem>
13351 <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
13352 an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
13353 <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
13354 a repo (Git) repository.</para></listitem>
13355 <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis>
13356 Fetches files from a ClearCase repository.
13357 </para></listitem>
13358 <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
13359 the Internet using <filename>http</filename>.</para></listitem>
13360 <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
13361 from the Internet using <filename>https</filename>.</para></listitem>
13362 <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
13363 from the Internet using <filename>ftp</filename>.</para></listitem>
13364 <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
13365 a CVS revision control repository.</para></listitem>
13366 <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
13367 a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
13368 <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
13369 a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
13370 <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
13371 a secure shell.</para></listitem>
13372 <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
13373 a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
13374 <listitem><para><emphasis><filename>npm://</filename> -</emphasis> Fetches JavaScript
13375 modules from a registry.
13376 </para></listitem>
13377 </itemizedlist>
13378 </para>
13379
13380 <para>
13381 Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
13382 Here are standard options:
13383 <itemizedlist>
13384 <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
13385 the patch or not.
13386 The default action is to apply the patch.</para></listitem>
13387 <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
13388 striplevel to use when applying the patch.
13389 The default level is 1.</para></listitem>
13390 <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
13391 the directory in which the patch should be applied.
13392 The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
13393 </para></listitem>
13394 </itemizedlist>
13395 </para>
13396
13397 <para>
13398 Here are options specific to recipes building code from a revision control system:
13399 <itemizedlist>
13400 <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
13401 Apply the patch only if
13402 <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
13403 is equal to or greater than <filename>mindate</filename>.
13404 </para></listitem>
13405 <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
13406 Apply the patch only if <filename>SRCDATE</filename>
13407 is not later than <filename>maxdate</filename>.
13408 </para></listitem>
13409 <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
13410 Apply the patch only if <filename>SRCREV</filename>
13411 is equal to or greater than <filename>minrev</filename>.
13412 </para></listitem>
13413 <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
13414 Apply the patch only if <filename>SRCREV</filename>
13415 is not later than <filename>maxrev</filename>.
13416 </para></listitem>
13417 <listitem><para><emphasis><filename>rev</filename> -</emphasis>
13418 Apply the patch only if <filename>SRCREV</filename>
13419 is equal to <filename>rev</filename>.
13420 </para></listitem>
13421 <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
13422 Apply the patch only if <filename>SRCREV</filename>
13423 is not equal to <filename>rev</filename>.
13424 </para></listitem>
13425 </itemizedlist>
13426 </para>
13427
13428 <para>
13429 Here are some additional options worth mentioning:
13430 <itemizedlist>
13431 <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
13432 whether or not to unpack the file if it is an archive.
13433 The default action is to unpack the file.</para></listitem>
13434 <listitem><para><emphasis><filename>destsuffix</filename> -</emphasis> Places the file
13435 (or extracts its contents) into the specified
13436 subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
13437 when the Git fetcher is used.
13438 </para></listitem>
13439 <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
13440 (or extracts its contents) into the specified
13441 subdirectory of <filename>WORKDIR</filename>
13442 when the local (<filename>file://</filename>)
13443 fetcher is used.
13444 </para></listitem>
13445 <listitem><para><emphasis><filename>localdir</filename> -</emphasis> Places the file
13446 (or extracts its contents) into the specified
13447 subdirectory of <filename>WORKDIR</filename> when
13448 the CVS fetcher is used.
13449 </para></listitem>
13450 <listitem><para><emphasis><filename>subpath</filename> -</emphasis>
13451 Limits the checkout to a specific subpath of the
13452 tree when using the Git fetcher is used.
13453 </para></listitem>
13454 <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
13455 name to be used for association with <filename>SRC_URI</filename> checksums
13456 when you have more than one file specified in <filename>SRC_URI</filename>.
13457 </para></listitem>
13458 <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
13459 the filename used when storing the downloaded file.</para></listitem>
13460 </itemizedlist>
13461 </para>
13462 </glossdef>
13463 </glossentry>
13464
13465 <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
13466 <info>
13467 SRC_URI_OVERRIDES_PACKAGE_ARCH[doc] = "By default, the OpenEmbedded build system automatically detects whether SRC_URI contains files that are machine-specific. If so, the build system automatically changes PACKAGE_ARCH. Setting this variable to '0' disables this behavior."
13468 </info>
13469 <glossdef>
13470 <para role="glossdeffirst">
13471 By default, the OpenEmbedded build system automatically detects whether
13472 <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
13473 contains files that are machine-specific.
13474 If so, the build system automatically changes
13475 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
13476 Setting this variable to "0" disables this behavior.
13477 </para>
13478 </glossdef>
13479 </glossentry>
13480
13481 <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
13482 <info>
13483 SRCDATE[doc] = "The date of the source code used to build the package. This variable applies only if the source was fetched from a Source Code Manager (SCM)."
13484 </info>
13485 <glossdef>
13486 <para role="glossdeffirst">
13487 The date of the source code used to build the package.
13488 This variable applies only if the source was fetched from a Source Code Manager (SCM).
13489 </para>
13490 </glossdef>
13491 </glossentry>
13492
13493 <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
13494 <info>
13495 SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV."
13496 </info>
13497 <glossdef>
13498 <para role="glossdeffirst">
13499 Returns the version string of the current package.
13500 This string is used to help define the value of
13501 <link linkend='var-PV'><filename>PV</filename></link>.
13502 </para>
13503
13504 <para>
13505 The <filename>SRCPV</filename> variable is defined in the
13506 <filename>meta/conf/bitbake.conf</filename> configuration
13507 file in the
13508 <link linkend='source-directory'>Source Directory</link>
13509 as follows:
13510 <literallayout class='monospaced'>
13511 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
13512 </literallayout>
13513 </para>
13514
13515 <para>
13516 Recipes that need to define <filename>PV</filename> do so
13517 with the help of the <filename>SRCPV</filename>.
13518 For example, the <filename>ofono</filename> recipe
13519 (<filename>ofono_git.bb</filename>) located in
13520 <filename>meta/recipes-connectivity</filename> in the
13521 Source Directory defines <filename>PV</filename> as
13522 follows:
13523 <literallayout class='monospaced'>
13524 PV = "0.12-git${SRCPV}"
13525 </literallayout>
13526 </para>
13527 </glossdef>
13528 </glossentry>
13529
13530 <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
13531 <info>
13532 SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial, and Bazaar only."
13533 </info>
13534 <glossdef>
13535 <para role="glossdeffirst">
13536 The revision of the source code used to build the package.
13537 This variable applies to Subversion, Git, Mercurial, and
13538 Bazaar only.
13539 Note that if you want to build a fixed revision and you
13540 want to avoid performing a query on the remote repository
13541 every time BitBake parses your recipe, you should specify
13542 a <filename>SRCREV</filename> that is a
13543 full revision identifier and not just a tag.
13544 <note>
13545 For information on limitations when inheriting the
13546 latest revision of software using
13547 <filename>SRCREV</filename>, see the
13548 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
13549 variable description and the
13550 "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>"
13551 section, which is in the Yocto Project Development
13552 Tasks Manual.
13553 </note>
13554 </para>
13555
13556 </glossdef>
13557 </glossentry>
13558
13559 <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
13560 <info>
13561 SSTATE_DIR[doc] = "The directory for the shared state cache."
13562 </info>
13563 <glossdef>
13564 <para role="glossdeffirst">
13565 The directory for the shared state cache.
13566 </para>
13567 </glossdef>
13568 </glossentry>
13569
13570 <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm>
13571 <info>
13572 SSTATE_MIRROR_ALLOW_NETWORK[doc] = "If set to "1", allows fetches from mirrors that are specified in SSTATE_MIRRORS to work even when fetching from the network is disabled by setting BB_NO_NETWORK to "1"."
13573 </info>
13574 <glossdef>
13575 <para role="glossdeffirst">
13576 If set to "1", allows fetches from
13577 mirrors that are specified in
13578 <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
13579 to work even when fetching from the network is
13580 disabled by setting <filename>BB_NO_NETWORK</filename>
13581 to "1".
13582 Using the
13583 <filename>SSTATE_MIRROR_ALLOW_NETWORK</filename>
13584 variable is useful if you have set
13585 <filename>SSTATE_MIRRORS</filename> to point to an
13586 internal server for your shared state cache, but
13587 you want to disable any other fetching from the network.
13588 </para>
13589 </glossdef>
13590 </glossentry>
13591
13592 <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
13593 <info>
13594 SSTATE_MIRRORS[doc] = "Configures the OpenEmbedded build system to search other mirror locations for prebuilt cache data objects before building out the data. You can specify a filesystem directory or a remote URL such as HTTP or FTP."
13595 </info>
13596 <glossdef>
13597 <para role="glossdeffirst">
13598 Configures the OpenEmbedded build system to search other
13599 mirror locations for prebuilt cache data objects before
13600 building out the data.
13601 This variable works like fetcher
13602 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
13603 and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
13604 and points to the cache locations to check for the shared
13605 state (sstate) objects.
13606 </para>
13607
13608 <para>
13609 You can specify a filesystem directory or a remote URL such
13610 as HTTP or FTP.
13611 The locations you specify need to contain the shared state
13612 cache (sstate-cache) results from previous builds.
13613 The sstate-cache you point to can also be from builds on
13614 other machines.
13615 </para>
13616
13617 <para>
13618 When pointing to sstate build artifacts on another machine
13619 that uses a different GCC version for native builds,
13620 you must configure <filename>SSTATE_MIRRORS</filename>
13621 with a regular expression that maps local search paths
13622 to server paths.
13623 The paths need to take into account
13624 <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
13625 set by the
13626 <link linkend='ref-classes-uninative'><filename>uninative</filename></link>
13627 class.
13628 For example, the following maps the local search path
13629 <filename>universal-4.9</filename> to the server-provided
13630 path <replaceable>server_url_sstate_path</replaceable>:
13631 <literallayout class='monospaced'>
13632 SSTATE_MIRRORS ?= file://universal-4.9/(.*) http://<replaceable>server_url_sstate_path</replaceable>/universal-4.8/\1 \n
13633 </literallayout>
13634 </para>
13635
13636 <para>
13637 If a mirror uses the same structure as
13638 <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
13639 you need to add
13640 "PATH" at the end as shown in the examples below.
13641 The build system substitutes the correct path within the
13642 directory structure.
13643 <literallayout class='monospaced'>
13644 SSTATE_MIRRORS ?= "\
13645 file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \
13646 file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH"
13647 </literallayout>
13648 </para>
13649 </glossdef>
13650 </glossentry>
13651
13652 <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm>
13653 <info>
13654 SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths."
13655 </info>
13656 <glossdef>
13657 <para role="glossdeffirst">
13658 Controls the list of files the OpenEmbedded build system
13659 scans for hardcoded installation paths. The variable uses a
13660 space-separated list of filenames (not paths) with standard
13661 wildcard characters allowed.
13662 </para>
13663
13664 <para>
13665 During a build, the OpenEmbedded build system creates a
13666 shared state (sstate) object during the first stage of
13667 preparing the sysroots. That object is scanned for
13668 hardcoded paths for original installation locations.
13669 The list of files that are scanned for paths is controlled
13670 by the <filename>SSTATE_SCAN_FILES</filename> variable.
13671 Typically, recipes add files they want to be scanned to the
13672 value of <filename>SSTATE_SCAN_FILES</filename> rather than
13673 the variable being comprehensively set. The
13674 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
13675 class specifies the default list of files.
13676 </para>
13677
13678 <para>
13679 For details on the process, see the
13680 <link linkend='ref-classes-staging'><filename>staging</filename></link>
13681 class.
13682 </para>
13683 </glossdef>
13684 </glossentry>
13685
13686 <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm>
13687 <info>
13688 STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host."
13689 </info>
13690 <glossdef>
13691 <para role="glossdeffirst">
13692 Specifies the path to the <filename>/lib</filename>
13693 subdirectory of the sysroot directory for the
13694 build host.
13695 </para>
13696 </glossdef>
13697 </glossentry>
13698
13699 <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm>
13700 <info>
13701 STAGING_BASELIBDIR[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13702 </info>
13703 <glossdef>
13704 <para role="glossdeffirst">
13705 Specifies the path to the <filename>/lib</filename>
13706 subdirectory of the sysroot directory for the target
13707 for which the current recipe is being built
13708 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13709 </para>
13710 </glossdef>
13711 </glossentry>
13712
13713 <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm>
13714 <info>
13715 STAGING_BINDIR[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13716 </info>
13717 <glossdef>
13718 <para role="glossdeffirst">
13719 Specifies the path to the
13720 <filename>/usr/bin</filename> subdirectory of the
13721 sysroot directory for the target for which the current
13722 recipe is being built
13723 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13724 </para>
13725 </glossdef>
13726 </glossentry>
13727
13728 <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm>
13729 <info>
13730 STAGING_BINDIR_CROSS[doc] = "Specifies the path to the directory containing binary configuration scripts. These scripts provide configuration information for other software that wants to make use of libraries or include files provided by the software associated with the script."
13731 </info>
13732 <glossdef>
13733 <para role="glossdeffirst">
13734 Specifies the path to the directory containing binary
13735 configuration scripts.
13736 These scripts provide configuration information for
13737 other software that wants to make use of libraries or
13738 include files provided by the software associated with
13739 the script.
13740 <note>
13741 This style of build configuration has been largely
13742 replaced by <filename>pkg-config</filename>.
13743 Consequently, if <filename>pkg-config</filename>
13744 is supported by the library to which you are linking,
13745 it is recommended you use
13746 <filename>pkg-config</filename> instead of a
13747 provided configuration script.
13748 </note>
13749 </para>
13750 </glossdef>
13751 </glossentry>
13752
13753 <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm>
13754 <info>
13755 STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host."
13756 </info>
13757 <glossdef>
13758 <para role="glossdeffirst">
13759 Specifies the path to the
13760 <filename>/usr/bin</filename> subdirectory of the
13761 sysroot directory for the build host.
13762 </para>
13763 </glossdef>
13764 </glossentry>
13765
13766 <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm>
13767 <info>
13768 STAGING_DATADIR[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13769 </info>
13770 <glossdef>
13771 <para role="glossdeffirst">
13772 Specifies the path to the <filename>/usr/share</filename>
13773 subdirectory of the sysroot directory for the target
13774 for which the current recipe is being built
13775 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13776 </para>
13777 </glossdef>
13778 </glossentry>
13779
13780 <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm>
13781 <info>
13782 STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host."
13783 </info>
13784 <glossdef>
13785 <para role="glossdeffirst">
13786 Specifies the path to the <filename>/usr/share</filename>
13787 subdirectory of the sysroot directory for the build host.
13788 </para>
13789 </glossdef>
13790 </glossentry>
13791
13792 <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm>
13793 <info>
13794 STAGING_DIR[doc] = "Helps construct the recipe-sysroots directory, which is used during packaging."
13795 </info>
13796 <glossdef>
13797 <para role="glossdeffirst">
13798 Helps construct the <filename>recipe-sysroots</filename>
13799 directory, which is used during packaging.
13800 </para>
13801
13802 <para>
13803 For information on how staging for recipe-specific
13804 sysroots occurs, see the
13805 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
13806 task, the
13807 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes'>Sharing Files Between Recipes</ulink>"
13808 section in the Yocto Project Development Tasks Manual, the
13809 "<ulink url='&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment'>Configuration, Compilation, and Staging</ulink>"
13810 section in the Yocto Project Overview and Concepts Manual,
13811 and the
13812 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
13813 variable.
13814 <note>
13815 Recipes should never write files directly under
13816 the <filename>STAGING_DIR</filename> directory because
13817 the OpenEmbedded build system
13818 manages the directory automatically.
13819 Instead, files should be installed to
13820 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
13821 within your recipe's
13822 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
13823 task and then the OpenEmbedded build system will
13824 stage a subset of those files into the sysroot.
13825 </note>
13826 </para>
13827 </glossdef>
13828 </glossentry>
13829
13830 <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm>
13831 <info>
13832 STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on."
13833 </info>
13834 <glossdef>
13835 <para role="glossdeffirst">
13836 Specifies the path to the sysroot directory for the system
13837 on which the component is built to run (the system that
13838 hosts the component).
13839 For most recipes, this sysroot is the one in which that
13840 recipe's
13841 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
13842 task copies files.
13843 Exceptions include <filename>-native</filename> recipes,
13844 where the <filename>do_populate_sysroot</filename> task
13845 instead uses
13846 <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>.
13847 Depending on the type of recipe and the build target,
13848 <filename>STAGING_DIR_HOST</filename> can have the
13849 following values:
13850 <itemizedlist>
13851 <listitem><para>
13852 For recipes building for the target machine, the
13853 value is
13854 "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}".
13855 </para></listitem>
13856 <listitem><para>
13857 For native recipes building for the build host, the
13858 value is empty given the assumption that when
13859 building for the build host, the build host's own
13860 directories should be used.
13861 <note>
13862 <para><filename>-native</filename> recipes are
13863 not installed into host paths like such as
13864 <filename>/usr</filename>.
13865 Rather, these recipes are installed into
13866 <filename>STAGING_DIR_NATIVE</filename>.
13867 When compiling <filename>-native</filename>
13868 recipes, standard build environment variables
13869 such as
13870 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
13871 and
13872 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
13873 are set up so that both host paths and
13874 <filename>STAGING_DIR_NATIVE</filename> are
13875 searched for libraries and headers using, for
13876 example, GCC's <filename>-isystem</filename>
13877 option.</para>
13878
13879 <para>Thus, the emphasis is that the
13880 <filename>STAGING_DIR*</filename> variables
13881 should be viewed as input variables by tasks
13882 such as
13883 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>,
13884 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>,
13885 and
13886 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
13887 Having the real system root correspond to
13888 <filename>STAGING_DIR_HOST</filename> makes
13889 conceptual sense for
13890 <filename>-native</filename> recipes, as
13891 they make use of host headers and libraries.
13892 </para>
13893 </note>
13894 </para></listitem>
13895 </itemizedlist>
13896 </para>
13897 </glossdef>
13898 </glossentry>
13899
13900 <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm>
13901 <info>
13902 STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself."
13903 </info>
13904 <glossdef>
13905 <para role="glossdeffirst">
13906 Specifies the path to the sysroot directory used when
13907 building components that run on the build host itself.
13908 </para>
13909 </glossdef>
13910 </glossentry>
13911
13912 <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm>
13913 <info>
13914 STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code."
13915 </info>
13916 <glossdef>
13917 <para role="glossdeffirst">
13918 Specifies the path to the sysroot used for the system for
13919 which the component generates code.
13920 For components that do not generate code, which is the
13921 majority, <filename>STAGING_DIR_TARGET</filename> is set
13922 to match
13923 <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>.
13924 </para>
13925
13926 <para>
13927 Some recipes build binaries that can run on the target
13928 system but those binaries in turn generate code for
13929 another different system (e.g. cross-canadian recipes).
13930 Using terminology from GNU, the primary system is referred
13931 to as the "HOST" and the secondary, or different, system is
13932 referred to as the "TARGET".
13933 Thus, the binaries run on the "HOST" system
13934 and generate binaries for the "TARGET" system.
13935 The <filename>STAGING_DIR_HOST</filename> variable points
13936 to the sysroot used for the "HOST" system, while
13937 <filename>STAGING_DIR_TARGET</filename>
13938 points to the sysroot used for the "TARGET" system.
13939 </para>
13940 </glossdef>
13941 </glossentry>
13942
13943 <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm>
13944 <info>
13945 STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host."
13946 </info>
13947 <glossdef>
13948 <para role="glossdeffirst">
13949 Specifies the path to the <filename>/etc</filename>
13950 subdirectory of the sysroot directory for the
13951 build host.
13952 </para>
13953 </glossdef>
13954 </glossentry>
13955
13956 <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm>
13957 <info>
13958 STAGING_EXECPREFIXDIR[doc] = "Specifies the path to the /usr subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
13959 </info>
13960 <glossdef>
13961 <para role="glossdeffirst">
13962 Specifies the path to the <filename>/usr</filename>
13963 subdirectory of the sysroot directory for the target
13964 for which the current recipe is being built
13965 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13966 </para>
13967 </glossdef>
13968 </glossentry>
13969
13970 <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm>
13971 <info>
13972 STAGING_INCDIR[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the target for which the current recipe being built (STAGING_DIR_HOST)."
13973 </info>
13974 <glossdef>
13975 <para role="glossdeffirst">
13976 Specifies the path to the
13977 <filename>/usr/include</filename> subdirectory of the
13978 sysroot directory for the target for which the current
13979 recipe being built
13980 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
13981 </para>
13982 </glossdef>
13983 </glossentry>
13984
13985 <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm>
13986 <info>
13987 STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host."
13988 </info>
13989 <glossdef>
13990 <para role="glossdeffirst">
13991 Specifies the path to the <filename>/usr/include</filename>
13992 subdirectory of the sysroot directory for the build host.
13993 </para>
13994 </glossdef>
13995 </glossentry>
13996
13997 <glossentry id='var-STAGING_KERNEL_BUILDDIR'><glossterm>STAGING_KERNEL_BUILDDIR</glossterm>
13998 <info>
13999 STAGING_KERNEL_BUILDDIR[doc] = "Points to the directory containing the kernel build artifacts."
14000 </info>
14001 <glossdef>
14002 <para role="glossdeffirst">
14003 Points to the directory containing the kernel build
14004 artifacts.
14005 Recipes building software that needs to access kernel
14006 build artifacts
14007 (e.g. <filename>systemtap-uprobes</filename>) can look in
14008 the directory specified with the
14009 <filename>STAGING_KERNEL_BUILDDIR</filename> variable to
14010 find these artifacts after the kernel has been built.
14011 </para>
14012 </glossdef>
14013 </glossentry>
14014
14015 <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
14016 <info>
14017 STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules."
14018 </info>
14019 <glossdef>
14020 <para role="glossdeffirst">
14021 The directory with kernel headers that are required to build out-of-tree
14022 modules.
14023 </para>
14024 </glossdef>
14025 </glossentry>
14026
14027 <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm>
14028 <info>
14029 STAGING_LIBDIR[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)."
14030 </info>
14031 <glossdef>
14032 <para role="glossdeffirst">
14033 Specifies the path to the <filename>/usr/lib</filename>
14034 subdirectory of the sysroot directory for the target for
14035 which the current recipe is being built
14036 (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>).
14037 </para>
14038 </glossdef>
14039 </glossentry>
14040
14041 <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm>
14042 <info>
14043 STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host."
14044 </info>
14045 <glossdef>
14046 <para role="glossdeffirst">
14047 Specifies the path to the <filename>/usr/lib</filename>
14048 subdirectory of the sysroot directory for the build host.
14049 </para>
14050 </glossdef>
14051 </glossentry>
14052
14053 <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
14054 <info>
14055 STAMP[doc] = "Specifies the base path used to create recipe stamp files. The path to an actual stamp file is constructed by evaluating this string and then appending additional information."
14056 </info>
14057 <glossdef>
14058 <para role="glossdeffirst">
14059 Specifies the base path used to create recipe stamp files.
14060 The path to an actual stamp file is constructed by evaluating this
14061 string and then appending additional information.
14062 Currently, the default assignment for <filename>STAMP</filename>
14063 as set in the <filename>meta/conf/bitbake.conf</filename> file
14064 is:
14065 <literallayout class='monospaced'>
14066 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
14067 </literallayout>
14068 </para>
14069
14070 <para>
14071 For information on how BitBake uses stamp files to determine
14072 if a task should be rerun, see the
14073 "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
14074 section in the Yocto Project Overview and Concepts Manual.
14075 </para>
14076
14077 <para>
14078 See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
14079 <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
14080 <link linkend='var-PN'><filename>PN</filename></link>,
14081 <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
14082 <link linkend='var-PV'><filename>PV</filename></link>, and
14083 <link linkend='var-PR'><filename>PR</filename></link> for related variable
14084 information.
14085 </para>
14086 </glossdef>
14087 </glossentry>
14088
14089 <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
14090 <info>
14091 STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps."
14092 </info>
14093 <glossdef>
14094 <para role="glossdeffirst">
14095 Specifies the base directory in which the OpenEmbedded
14096 build system places stamps.
14097 The default directory is
14098 <filename>${TMPDIR}/stamps</filename>.
14099 </para>
14100 </glossdef>
14101 </glossentry>
14102
14103 <glossentry id='var-STRIP'><glossterm>STRIP</glossterm>
14104 <info>
14105 STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)."
14106 </info>
14107 <glossdef>
14108 <para role="glossdeffirst">
14109 The minimal command and arguments to run
14110 <filename>strip</filename>, which is used to strip
14111 symbols.
14112 </para>
14113 </glossdef>
14114 </glossentry>
14115
14116 <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
14117 <info>
14118 SUMMARY[doc] = "The short (80 characters or less) summary of the binary package for packaging systems such as opkg, rpm, or dpkg. By default, SUMMARY is used to define the DESCRIPTION variable if DESCRIPTION is not set in the recipe."
14119 </info>
14120 <glossdef>
14121 <para role="glossdeffirst">
14122 The short (72 characters or less) summary of the binary package for packaging
14123 systems such as <filename>opkg</filename>, <filename>rpm</filename>, or
14124 <filename>dpkg</filename>.
14125 By default, <filename>SUMMARY</filename> is used to define
14126 the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
14127 variable if <filename>DESCRIPTION</filename> is not set
14128 in the recipe.
14129 </para>
14130 </glossdef>
14131 </glossentry>
14132
14133 <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm>
14134 <info>
14135 SVNDIR[doc] = "The directory where Subversion checkouts are stored."
14136 </info>
14137 <glossdef>
14138 <para role="glossdeffirst">
14139 The directory in which files checked out of a Subversion
14140 system are stored.
14141 </para>
14142 </glossdef>
14143 </glossentry>
14144
14145 <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm>
14146 <info>
14147 SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console."
14148 </info>
14149 <glossdef>
14150 <para role="glossdeffirst">
14151 Specifies the kernel boot default console.
14152 If you want to use a console other than the default,
14153 set this variable in your recipe as follows where "X" is
14154 the console number you want to use:
14155 <literallayout class='monospaced'>
14156 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
14157 </literallayout>
14158 </para>
14159
14160 <para>
14161 The
14162 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14163 class initially sets this variable to null but then checks
14164 for a value later.
14165 </para>
14166 </glossdef>
14167 </glossentry>
14168
14169 <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm>
14170 <info>
14171 SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file."
14172 </info>
14173 <glossdef>
14174 <para role="glossdeffirst">
14175 Lists additional options to add to the syslinux file.
14176 You need to set this variable in your recipe.
14177 If you want to list multiple options, separate the options
14178 with a semicolon character (<filename>;</filename>).
14179 </para>
14180
14181 <para>
14182 The
14183 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14184 class uses this variable to create a set of options.
14185 </para>
14186 </glossdef>
14187 </glossentry>
14188
14189 <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm>
14190 <info>
14191 SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off."
14192 </info>
14193 <glossdef>
14194 <para role="glossdeffirst">
14195 Specifies the alternate serial port or turns it off.
14196 To turn off serial, set this variable to an empty string
14197 in your recipe.
14198 The variable's default value is set in the
14199 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14200 class as follows:
14201 <literallayout class='monospaced'>
14202 SYSLINUX_SERIAL ?= "0 115200"
14203 </literallayout>
14204 </para>
14205
14206 <para>
14207 The class checks for and uses the variable as needed.
14208 </para>
14209 </glossdef>
14210 </glossentry>
14211
14212 <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm>
14213 <info>
14214 SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you use the boot menu."
14215 </info>
14216 <glossdef>
14217 <para role="glossdeffirst">
14218 An <filename>.LSS</filename> file used as the background
14219 for the VGA boot menu when you use the boot menu.
14220 You need to set this variable in your recipe.
14221 </para>
14222
14223 <para>
14224 The
14225 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14226 class checks for this variable and if found, the
14227 OpenEmbedded build system installs the splash screen.
14228 </para>
14229 </glossdef>
14230 </glossentry>
14231
14232 <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm>
14233 <info>
14234 SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument."
14235 </info>
14236 <glossdef>
14237 <para role="glossdeffirst">
14238 Specifies the alternate console=tty... kernel boot argument.
14239 The variable's default value is set in the
14240 <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link>
14241 class as follows:
14242 <literallayout class='monospaced'>
14243 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
14244 </literallayout>
14245 </para>
14246
14247 <para>
14248 The class checks for and uses the variable as needed.
14249 </para>
14250 </glossdef>
14251 </glossentry>
14252
14253 <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm>
14254 <info>
14255 SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files populated into the sysroot are assembled during the do_populate_sysroot task."
14256 </info>
14257 <glossdef>
14258 <para role="glossdeffirst">
14259 Points to the temporary directory under the work directory
14260 (default
14261 "<filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destdir</filename>")
14262 where the files populated into the sysroot are assembled
14263 during the
14264 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14265 task.
14266 </para>
14267 </glossdef>
14268 </glossentry>
14269
14270 <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm>
14271 <info>
14272 SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task."
14273 </info>
14274 <glossdef>
14275 <para role="glossdeffirst">
14276 Directories that are staged into the sysroot by the
14277 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14278 task.
14279 By default, the following directories are staged:
14280 <literallayout class='monospaced'>
14281 SYSROOT_DIRS = " \
14282 ${includedir} \
14283 ${libdir} \
14284 ${base_libdir} \
14285 ${nonarch_base_libdir} \
14286 ${datadir} \
14287 "
14288 </literallayout>
14289 </para>
14290 </glossdef>
14291 </glossentry>
14292
14293 <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm>
14294 <info>
14295 SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task."
14296 </info>
14297 <glossdef>
14298 <para role="glossdeffirst">
14299 Directories that are not staged into the sysroot by the
14300 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14301 task.
14302 You can use this variable to exclude certain subdirectories
14303 of directories listed in
14304 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>
14305 from staging.
14306 By default, the following directories are not staged:
14307 <literallayout class='monospaced'>
14308 SYSROOT_DIRS_BLACKLIST = " \
14309 ${mandir} \
14310 ${docdir} \
14311 ${infodir} \
14312 ${datadir}/locale \
14313 ${datadir}/applications \
14314 ${datadir}/fonts \
14315 ${datadir}/pixmaps \
14316 "
14317 </literallayout>
14318 </para>
14319 </glossdef>
14320 </glossentry>
14321
14322 <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm>
14323 <info>
14324 SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged into the sysroot by the do_populate_sysroot task for -native recipes, in addition to those specified in SYSROOT_DIRS."
14325 </info>
14326 <glossdef>
14327 <para role="glossdeffirst">
14328 Extra directories staged into the sysroot by the
14329 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
14330 task for <filename>-native</filename> recipes, in addition
14331 to those specified in
14332 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>.
14333 By default, the following extra directories are staged:
14334 <literallayout class='monospaced'>
14335 SYSROOT_DIRS_NATIVE = " \
14336 ${bindir} \
14337 ${sbindir} \
14338 ${base_bindir} \
14339 ${base_sbindir} \
14340 ${libexecdir} \
14341 ${sysconfdir} \
14342 ${localstatedir} \
14343 "
14344 </literallayout>
14345 <note>
14346 Programs built by <filename>-native</filename> recipes
14347 run directly from the sysroot
14348 (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>),
14349 which is why additional directories containing program
14350 executables and supporting files need to be staged.
14351 </note>
14352 </para>
14353 </glossdef>
14354 </glossentry>
14355
14356 <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
14357 <info>
14358 SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files."
14359 </info>
14360 <glossdef>
14361 <para role="glossdeffirst">
14362 A list of functions to execute after files are staged into
14363 the sysroot.
14364 These functions are usually used to apply additional
14365 processing on the staged files, or to stage additional
14366 files.
14367 </para>
14368 </glossdef>
14369 </glossentry>
14370
14371 <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm>
14372 <info>
14373 SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the specified service in SYSTEMD_SERVICE should start automatically or not."
14374 </info>
14375 <glossdef>
14376 <para role="glossdeffirst">
14377 When inheriting the
14378 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14379 class, this variable specifies whether the specified service
14380 in
14381 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
14382 should start automatically or not.
14383 By default, the service is enabled to automatically start
14384 at boot time.
14385 The default setting is in the
14386 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14387 class as follows:
14388 <literallayout class='monospaced'>
14389 SYSTEMD_AUTO_ENABLE ??= "enable"
14390 </literallayout>
14391 </para>
14392
14393 <para>
14394 You can disable the service by setting the variable to
14395 "disable".
14396 </para>
14397 </glossdef>
14398 </glossentry>
14399
14400 <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm>
14401 <info>
14402 SYSTEMD_BOOT_CFG[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_CFG variable specifies the configuration file that should be used."
14403 </info>
14404 <glossdef>
14405 <para role="glossdeffirst">
14406 When
14407 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14408 is set to "systemd-boot", the
14409 <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the
14410 configuration file that should be used.
14411 By default, the
14412 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14413 class sets the <filename>SYSTEMD_BOOT_CFG</filename> as
14414 follows:
14415 <literallayout class='monospaced'>
14416 SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf"
14417 </literallayout>
14418 </para>
14419
14420 <para>
14421 For information on Systemd-boot, see the
14422 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14423 </para>
14424 </glossdef>
14425 </glossentry>
14426
14427 <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm>
14428 <info>
14429 SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to install that contain one boot entry per file."
14430 </info>
14431 <glossdef>
14432 <para role="glossdeffirst">
14433 When
14434 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14435 is set to "systemd-boot", the
14436 <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies
14437 a list of entry files
14438 (<filename>*.conf</filename>) to install that contain
14439 one boot entry per file.
14440 By default, the
14441 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14442 class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as
14443 follows:
14444 <literallayout class='monospaced'>
14445 SYSTEMD_BOOT_ENTRIES ?= ""
14446 </literallayout>
14447 </para>
14448
14449 <para>
14450 For information on Systemd-boot, see the
14451 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14452 </para>
14453 </glossdef>
14454 </glossentry>
14455
14456 <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm>
14457 <info>
14458 SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds."
14459 </info>
14460 <glossdef>
14461 <para role="glossdeffirst">
14462 When
14463 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
14464 is set to "systemd-boot", the
14465 <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies
14466 the boot menu timeout in seconds.
14467 By default, the
14468 <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link>
14469 class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as
14470 follows:
14471 <literallayout class='monospaced'>
14472 SYSTEMD_BOOT_TIMEOUT ?= "10"
14473 </literallayout>
14474 </para>
14475
14476 <para>
14477 For information on Systemd-boot, see the
14478 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>.
14479 </para>
14480 </glossdef>
14481 </glossentry>
14482
14483 <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm>
14484 <info>
14485 SYSTEMD_PACKAGES[doc] = "For recipes that inherit the systemd class, this variable locates the systemd unit files when they are not found in the main recipe's package."
14486 </info>
14487 <glossdef>
14488 <para role="glossdeffirst">
14489 When inheriting the
14490 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14491 class, this variable locates the systemd unit files when
14492 they are not found in the main recipe's package.
14493 By default, the
14494 <filename>SYSTEMD_PACKAGES</filename> variable is set
14495 such that the systemd unit files are assumed to reside in
14496 the recipes main package:
14497 <literallayout class='monospaced'>
14498 SYSTEMD_PACKAGES ?= "${PN}"
14499 </literallayout>
14500 </para>
14501
14502 <para>
14503 If these unit files are not in this recipe's main
14504 package, you need to use
14505 <filename>SYSTEMD_PACKAGES</filename> to list the package
14506 or packages in which the build system can find the systemd
14507 unit files.
14508 </para>
14509 </glossdef>
14510 </glossentry>
14511
14512 <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm>
14513 <info>
14514 SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package."
14515 </info>
14516 <glossdef>
14517 <para role="glossdeffirst">
14518 When inheriting the
14519 <link linkend='ref-classes-systemd'><filename>systemd</filename></link>
14520 class, this variable specifies the systemd service name for
14521 a package.
14522 </para>
14523
14524 <para>
14525 When you specify this file in your recipe, use a package
14526 name override to indicate the package to which the value
14527 applies.
14528 Here is an example from the connman recipe:
14529 <literallayout class='monospaced'>
14530 SYSTEMD_SERVICE_${PN} = "connman.service"
14531 </literallayout>
14532 </para>
14533 </glossdef>
14534 </glossentry>
14535
14536 <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm>
14537 <info>
14538 SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should run a getty, the default is '1'."
14539 </info>
14540 <glossdef>
14541 <para role="glossdeffirst">
14542 When using
14543 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
14544 specifies a space-separated list of the virtual terminals
14545 that should run a
14546 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
14547 (allowing login), assuming
14548 <link linkend='var-USE_VT'><filename>USE_VT</filename></link>
14549 is not set to "0".
14550 </para>
14551
14552 <para>
14553 The default value for
14554 <filename>SYSVINIT_ENABLED_GETTYS</filename> is "1"
14555 (i.e. only run a getty on the first virtual terminal).
14556 </para>
14557 </glossdef>
14558 </glossentry>
14559
14560 </glossdiv>
14561
14562 <glossdiv id='var-glossary-t'><title>T</title>
14563
14564 <glossentry id='var-T'><glossterm>T</glossterm>
14565 <info>
14566 T[doc] = "This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a particular recipe."
14567 </info>
14568 <glossdef>
14569 <para role="glossdeffirst">
14570 This variable points to a directory were BitBake places
14571 temporary files, which consist mostly of task logs and
14572 scripts, when building a particular recipe.
14573 The variable is typically set as follows:
14574 <literallayout class='monospaced'>
14575 T = "${WORKDIR}/temp"
14576 </literallayout>
14577 </para>
14578
14579 <para>
14580 The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
14581 is the directory into which BitBake unpacks and builds the
14582 recipe.
14583 The default <filename>bitbake.conf</filename> file sets this variable.</para>
14584 <para>The <filename>T</filename> variable is not to be confused with
14585 the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
14586 which points to the root of the directory tree where BitBake
14587 places the output of an entire build.
14588 </para>
14589 </glossdef>
14590 </glossentry>
14591
14592 <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
14593 <info>
14594 TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64."
14595 </info>
14596 <glossdef>
14597 <para role="glossdeffirst">
14598 The target machine's architecture.
14599 The OpenEmbedded build system supports many
14600 architectures.
14601 Here is an example list of architectures supported.
14602 This list is by no means complete as the architecture
14603 is configurable:
14604 <literallayout class='monospaced'>
14605 arm
14606 i586
14607 x86_64
14608 powerpc
14609 powerpc64
14610 mips
14611 mipsel
14612 </literallayout>
14613 </para>
14614
14615 <para>
14616 For additional information on machine architectures, see
14617 the
14618 <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link>
14619 variable.
14620 </para>
14621 </glossdef>
14622 </glossentry>
14623
14624 <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm>
14625 <info>
14626 TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system."
14627 </info>
14628 <glossdef>
14629 <para role="glossdeffirst">
14630 Specifies architecture-specific assembler flags for the
14631 target system.
14632 <filename>TARGET_AS_ARCH</filename> is initialized from
14633 <link linkend='var-TUNE_ASARGS'><filename>TUNE_ASARGS</filename></link>
14634 by default in the BitBake configuration file
14635 (<filename>meta/conf/bitbake.conf</filename>):
14636 <literallayout class='monospaced'>
14637 TARGET_AS_ARCH = "${TUNE_ASARGS}"
14638 </literallayout>
14639 </para>
14640 </glossdef>
14641 </glossentry>
14642
14643 <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm>
14644 <info>
14645 TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system."
14646 </info>
14647 <glossdef>
14648 <para role="glossdeffirst">
14649 Specifies architecture-specific C compiler flags for the
14650 target system.
14651 <filename>TARGET_CC_ARCH</filename> is initialized from
14652 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
14653 by default.
14654 <note>
14655 It is a common workaround to append
14656 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
14657 to <filename>TARGET_CC_ARCH</filename>
14658 in recipes that build software for the target that
14659 would not otherwise respect the exported
14660 <filename>LDFLAGS</filename> variable.
14661 </note>
14662 </para>
14663 </glossdef>
14664 </glossentry>
14665
14666 <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm>
14667 <info>
14668 TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune."
14669 </info>
14670 <glossdef>
14671 <para role="glossdeffirst">
14672 This is a specific kernel compiler flag for a CPU or
14673 Application Binary Interface (ABI) tune.
14674 The flag is used rarely and only for cases where a
14675 userspace
14676 <link linkend='var-TUNE_CCARGS'><filename>TUNE_CCARGS</filename></link>
14677 is not compatible with the kernel compilation.
14678 The <filename>TARGET_CC_KERNEL_ARCH</filename> variable
14679 allows the kernel (and associated modules) to use a
14680 different configuration.
14681 See the
14682 <filename>meta/conf/machine/include/arm/feature-arm-thumb.inc</filename>
14683 file in the
14684 <link linkend='source-directory'>Source Directory</link>
14685 for an example.
14686 </para>
14687 </glossdef>
14688 </glossentry>
14689
14690 <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
14691 <info>
14692 TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS."
14693 </info>
14694 <glossdef>
14695 <para role="glossdeffirst">
14696 Specifies the flags to pass to the C compiler when building
14697 for the target.
14698 When building in the target context,
14699 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
14700 is set to the value of this variable by default.
14701 </para>
14702
14703 <para>
14704 Additionally, the SDK's environment setup script sets
14705 the <filename>CFLAGS</filename> variable in the environment
14706 to the <filename>TARGET_CFLAGS</filename> value so that
14707 executables built using the SDK also have the flags
14708 applied.
14709 </para>
14710 </glossdef>
14711 </glossentry>
14712
14713 <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm>
14714 <info>
14715 TARGET_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the target."
14716 </info>
14717 <glossdef>
14718 <para role="glossdeffirst">
14719 Specifies the flags to pass to the C pre-processor
14720 (i.e. to both the C and the C++ compilers) when building
14721 for the target.
14722 When building in the target context,
14723 <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link>
14724 is set to the value of this variable by default.
14725 </para>
14726
14727 <para>
14728 Additionally, the SDK's environment setup script sets
14729 the <filename>CPPFLAGS</filename> variable in the
14730 environment to the <filename>TARGET_CPPFLAGS</filename>
14731 value so that executables built using the SDK also have
14732 the flags applied.
14733 </para>
14734 </glossdef>
14735 </glossentry>
14736
14737 <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm>
14738 <info>
14739 TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target."
14740 </info>
14741 <glossdef>
14742 <para role="glossdeffirst">
14743 Specifies the flags to pass to the C++ compiler when
14744 building for the target.
14745 When building in the target context,
14746 <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link>
14747 is set to the value of this variable by default.
14748 </para>
14749
14750 <para>
14751 Additionally, the SDK's environment setup script sets
14752 the <filename>CXXFLAGS</filename> variable in the
14753 environment to the <filename>TARGET_CXXFLAGS</filename>
14754 value so that executables built using the SDK also have
14755 the flags applied.
14756 </para>
14757 </glossdef>
14758 </glossentry>
14759
14760 <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
14761 <info>
14762 TARGET_FPU[doc] = "Specifies the method for handling FPU code. For FPU-less targets, which include most ARM CPUs, the variable must be set to 'soft'. If not, the kernel emulation gets used, which results in a performance penalty."
14763 </info>
14764 <glossdef>
14765 <para role="glossdeffirst">
14766 Specifies the method for handling FPU code.
14767 For FPU-less targets, which include most ARM CPUs, the variable must be
14768 set to "soft".
14769 If not, the kernel emulation gets used, which results in a performance penalty.
14770 </para>
14771 </glossdef>
14772 </glossentry>
14773
14774 <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm>
14775 <info>
14776 TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system."
14777 </info>
14778 <glossdef>
14779 <para role="glossdeffirst">
14780 Specifies architecture-specific linker flags for the
14781 target system.
14782 <filename>TARGET_LD_ARCH</filename> is initialized from
14783 <link linkend='var-TUNE_LDARGS'><filename>TUNE_LDARGS</filename></link>
14784 by default in the BitBake configuration file
14785 (<filename>meta/conf/bitbake.conf</filename>):
14786 <literallayout class='monospaced'>
14787 TARGET_LD_ARCH = "${TUNE_LDARGS}"
14788 </literallayout>
14789 </para>
14790 </glossdef>
14791 </glossentry>
14792
14793 <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm>
14794 <info>
14795 TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target."
14796 </info>
14797 <glossdef>
14798 <para role="glossdeffirst">
14799 Specifies the flags to pass to the linker when building
14800 for the target.
14801 When building in the target context,
14802 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
14803 is set to the value of this variable by default.
14804 </para>
14805
14806 <para>
14807 Additionally, the SDK's environment setup script sets
14808 the
14809 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
14810 variable in the environment to the
14811 <filename>TARGET_LDFLAGS</filename> value so that
14812 executables built using the SDK also have the flags
14813 applied.
14814 </para>
14815 </glossdef>
14816 </glossentry>
14817
14818 <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
14819 <info>
14820 TARGET_OS[doc] = "Specifies the target's operating system."
14821 </info>
14822 <glossdef>
14823 <para role="glossdeffirst">
14824 Specifies the target's operating system.
14825 The variable can be set to "linux" for glibc-based systems
14826 (GNU C Library) and to "linux-musl" for musl libc.
14827 For ARM/EABI targets, "linux-gnueabi" and "linux-musleabi"
14828 possible values exist.
14829 </para>
14830 </glossdef>
14831 </glossentry>
14832
14833 <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm>
14834 <info>
14835 TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools."
14836 </info>
14837 <glossdef>
14838 <para role="glossdeffirst">
14839 Specifies the prefix used for the toolchain binary target
14840 tools.
14841 </para>
14842
14843 <para>
14844 Depending on the type of recipe and the build target,
14845 <filename>TARGET_PREFIX</filename> is set as follows:
14846 <itemizedlist>
14847 <listitem><para>
14848 For recipes building for the target machine,
14849 the value is
14850 "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-".
14851 </para></listitem>
14852 <listitem><para>
14853 For native recipes, the build system sets the
14854 variable to the value of
14855 <filename>BUILD_PREFIX</filename>.
14856 </para></listitem>
14857 <listitem><para>
14858 For native SDK recipes
14859 (<filename>nativesdk</filename>), the
14860 build system sets the variable to the value of
14861 <filename>SDK_PREFIX</filename>.
14862 </para></listitem>
14863 </itemizedlist>
14864 </para>
14865 </glossdef>
14866 </glossentry>
14867
14868 <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm>
14869 <info>
14870 TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS."
14871 </info>
14872 <glossdef>
14873 <para role="glossdeffirst">
14874 Specifies the system, including the architecture and the
14875 operating system, for which the build is occurring in
14876 the context of the current recipe.
14877 </para>
14878
14879 <para>
14880 The OpenEmbedded build system automatically sets this
14881 variable based on
14882 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
14883 <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>,
14884 and
14885 <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
14886 variables.
14887 <note>
14888 You do not need to set the
14889 <filename>TARGET_SYS</filename> variable yourself.
14890 </note>
14891 </para>
14892
14893 <para>
14894 Consider these two examples:
14895 <itemizedlist>
14896 <listitem><para>
14897 Given a native recipe on a 32-bit, x86 machine
14898 running Linux, the value is "i686-linux".
14899 </para></listitem>
14900 <listitem><para>
14901 Given a recipe being built for a little-endian,
14902 MIPS target running Linux, the value might be
14903 "mipsel-linux".
14904 </para></listitem>
14905 </itemizedlist>
14906 </para>
14907 </glossdef>
14908 </glossentry>
14909
14910 <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm>
14911 <info>
14912 TARGET_VENDOR[doc] = "The name of the target vendor."
14913 </info>
14914 <glossdef>
14915 <para role="glossdeffirst">
14916 Specifies the name of the target vendor.
14917 </para>
14918 </glossdef>
14919 </glossentry>
14920
14921 <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
14922 <info>
14923 TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc', 'musl' or 'newlib'."
14924 </info>
14925 <glossdef>
14926 <para role="glossdeffirst">
14927 Specifies the GNU standard C library
14928 (<filename>libc</filename>) variant to use during the
14929 build process.
14930 This variable replaces <filename>POKYLIBC</filename>,
14931 which is no longer supported.
14932 </para>
14933
14934 <para>
14935 You can select "glibc", "musl", "newlib", or "baremetal"
14936 </para>
14937 </glossdef>
14938 </glossentry>
14939
14940 <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm>
14941 <info>
14942 TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build."
14943 </info>
14944 <glossdef>
14945 <para role="glossdeffirst">
14946 Specifies a suffix to be appended onto the
14947 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
14948 value.
14949 The suffix identifies the <filename>libc</filename> variant
14950 for building.
14951 When you are building for multiple variants with the same
14952 <link linkend='build-directory'>Build Directory</link>,
14953 this mechanism ensures that output for different
14954 <filename>libc</filename> variants is kept separate to
14955 avoid potential conflicts.
14956 </para>
14957
14958 <para>
14959 In the <filename>defaultsetup.conf</filename> file, the
14960 default value of <filename>TCLIBCAPPEND</filename> is
14961 "-${TCLIBC}".
14962 However, distros such as poky, which normally only support
14963 one <filename>libc</filename> variant, set
14964 <filename>TCLIBCAPPEND</filename> to "" in their distro
14965 configuration file resulting in no suffix being applied.
14966 </para>
14967 </glossdef>
14968 </glossentry>
14969
14970 <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
14971 <info>
14972 TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'."
14973 </info>
14974 <glossdef>
14975 <para role="glossdeffirst">
14976 Specifies the toolchain selector.
14977 <filename>TCMODE</filename> controls the characteristics
14978 of the generated packages and images by telling the
14979 OpenEmbedded build system which toolchain profile to use.
14980 By default, the OpenEmbedded build system builds its own
14981 internal toolchain.
14982 The variable's default value is "default", which uses
14983 that internal toolchain.
14984 <note>
14985 If <filename>TCMODE</filename> is set to a value
14986 other than "default", then it is your responsibility
14987 to ensure that the toolchain is compatible with the
14988 default toolchain.
14989 Using older or newer versions of these components
14990 might cause build problems.
14991 See the Release Notes for the Yocto Project release
14992 for the specific components with which the toolchain
14993 must be compatible.
14994 To access the Release Notes, go to the
14995 <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
14996 page on the Yocto Project website and click on the
14997 "RELEASE INFORMATION" link for the appropriate
14998 release.
14999 </note>
15000 </para>
15001
15002 <para>
15003 The <filename>TCMODE</filename> variable is similar to
15004 <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
15005 which controls the variant of the GNU standard C library
15006 (<filename>libc</filename>) used during the build process:
15007 <filename>glibc</filename> or <filename>musl</filename>.
15008 </para>
15009
15010 <para>
15011 With additional layers, it is possible to use a pre-compiled
15012 external toolchain.
15013 One example is the Sourcery G++ Toolchain.
15014 The support for this toolchain resides in the separate
15015 <trademark class='registered'>Mentor Graphics</trademark>
15016 <filename>meta-sourcery</filename> layer at
15017 <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>.
15018 </para>
15019
15020 <para>
15021 The layer's <filename>README</filename> file contains
15022 information on how to use the Sourcery G++ Toolchain as
15023 an external toolchain.
15024 In summary, you must be sure to add the layer to your
15025 <filename>bblayers.conf</filename> file in front of the
15026 <filename>meta</filename> layer and then set the
15027 <filename>EXTERNAL_TOOLCHAIN</filename>
15028 variable in your <filename>local.conf</filename> file
15029 to the location in which you installed the toolchain.
15030 </para>
15031
15032 <para>
15033 The fundamentals used for this example apply to any
15034 external toolchain.
15035 You can use <filename>meta-sourcery</filename> as a
15036 template for adding support for other external toolchains.
15037 </para>
15038 </glossdef>
15039 </glossentry>
15040
15041 <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm>
15042 <info>
15043 TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"."
15044 </info>
15045 <glossdef>
15046 <para role="glossdeffirst">
15047 The location the OpenEmbedded build system uses to export
15048 tests when the
15049 <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link>
15050 variable is set to "1".
15051 </para>
15052
15053 <para>
15054 The <filename>TEST_EXPORT_DIR</filename> variable defaults
15055 to <filename>"${TMPDIR}/testimage/${PN}"</filename>.
15056 </para>
15057 </glossdef>
15058 </glossentry>
15059
15060 <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm>
15061 <info>
15062 TEST_EXPORT_ONLY[doc] = "Specifies to export the tests only. Set this variable to "1" if you do not want to run the tests but you want them to be exported in a manner that you to run them outside of the build system."
15063 </info>
15064 <glossdef>
15065 <para role="glossdeffirst">
15066 Specifies to export the tests only.
15067 Set this variable to "1" if you do not want to run the
15068 tests but you want them to be exported in a manner that
15069 you to run them outside of the build system.
15070 </para>
15071 </glossdef>
15072 </glossentry>
15073
15074 <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm>
15075 <info>
15076 TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The TEST_LOG_DIR variable defaults to "${WORKDIR}/testimage"."
15077 </info>
15078 <glossdef>
15079 <para role="glossdeffirst">
15080 Holds the SSH log and the boot log for QEMU machines.
15081 The <filename>TEST_LOG_DIR</filename> variable defaults
15082 to <filename>"${WORKDIR}/testimage"</filename>.
15083 <note>
15084 Actual test results reside in the task log
15085 (<filename>log.do_testimage</filename>), which is in
15086 the <filename>${WORKDIR}/temp/</filename> directory.
15087 </note>
15088 </para>
15089 </glossdef>
15090 </glossentry>
15091
15092 <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>TEST_POWERCONTROL_CMD</glossterm>
15093 <info>
15094 TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test"
15095 </info>
15096 <glossdef>
15097 <para role="glossdeffirst">
15098 For automated hardware testing, specifies the command to
15099 use to control the power of the target machine under test.
15100 Typically, this command would point to a script that
15101 performs the appropriate action (e.g. interacting
15102 with a web-enabled power strip).
15103 The specified command should expect to receive as the last
15104 argument "off", "on" or "cycle" specifying to power off,
15105 on, or cycle (power off and then power on) the device,
15106 respectively.
15107 </para>
15108 </glossdef>
15109 </glossentry>
15110
15111 <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>TEST_POWERCONTROL_EXTRA_ARGS</glossterm>
15112 <info>
15113 TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD"
15114 </info>
15115 <glossdef>
15116 <para role="glossdeffirst">
15117 For automated hardware testing, specifies additional
15118 arguments to pass through to the command specified in
15119 <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>.
15120 Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename>
15121 is optional.
15122 You can use it if you wish, for example, to separate the
15123 machine-specific and non-machine-specific parts of the
15124 arguments.
15125 </para>
15126 </glossdef>
15127 </glossentry>
15128
15129 <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
15130 <info>
15131 TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image."
15132 </info>
15133 <glossdef>
15134 <para role="glossdeffirst">
15135 The time in seconds allowed for an image to boot before
15136 automated runtime tests begin to run against an
15137 image.
15138 The default timeout period to allow the boot process to
15139 reach the login prompt is 500 seconds.
15140 You can specify a different value in the
15141 <filename>local.conf</filename> file.
15142 </para>
15143
15144 <para>
15145 For more information on testing images, see the
15146 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15147 section in the Yocto Project Development Tasks Manual.
15148 </para>
15149 </glossdef>
15150 </glossentry>
15151
15152 <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>TEST_SERIALCONTROL_CMD</glossterm>
15153 <info>
15154 TEST_SERIALCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to connect to the serial console of the target machine under test."
15155 </info>
15156 <glossdef>
15157 <para role="glossdeffirst">
15158 For automated hardware testing, specifies the command
15159 to use to connect to the serial console of the target
15160 machine under test.
15161 This command simply needs to connect to the serial console
15162 and forward that connection to standard input and output
15163 as any normal terminal program does.
15164 </para>
15165
15166 <para>
15167 For example, to use the Picocom terminal program on
15168 serial device <filename>/dev/ttyUSB0</filename> at
15169 115200bps, you would set the variable as follows:
15170 <literallayout class='monospaced'>
15171 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
15172 </literallayout>
15173 </para>
15174 </glossdef>
15175 </glossentry>
15176
15177 <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>TEST_SERIALCONTROL_EXTRA_ARGS</glossterm>
15178 <info>
15179 TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD."
15180 </info>
15181 <glossdef>
15182 <para role="glossdeffirst">
15183 For automated hardware testing, specifies additional
15184 arguments to pass through to the command specified in
15185 <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>.
15186 Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename>
15187 is optional.
15188 You can use it if you wish, for example, to separate the
15189 machine-specific and non-machine-specific parts of the
15190 command.
15191 </para>
15192 </glossdef>
15193 </glossentry>
15194
15195 <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm>
15196 <info>
15197 TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected."
15198 </info>
15199 <glossdef>
15200 <para role="glossdeffirst">
15201 The IP address of the build machine (host machine).
15202 This IP address is usually automatically detected.
15203 However, if detection fails, this variable needs to be set
15204 to the IP address of the build machine (i.e. where
15205 the build is taking place).
15206 <note>
15207 The <filename>TEST_SERVER_IP</filename> variable
15208 is only used for a small number of tests such as
15209 the "dnf" test suite, which needs to download
15210 packages from
15211 <filename>WORKDIR/oe-rootfs-repo</filename>.
15212 </note>
15213 </para>
15214 </glossdef>
15215 </glossentry>
15216
15217 <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm>
15218 <info>
15219 TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine."
15220 </info>
15221 <glossdef>
15222 <para role="glossdeffirst">
15223 Specifies the target controller to use when running tests
15224 against a test image.
15225 The default controller to use is "qemu":
15226 <literallayout class='monospaced'>
15227 TEST_TARGET = "qemu"
15228 </literallayout>
15229 </para>
15230
15231 <para>
15232 A target controller is a class that defines how an
15233 image gets deployed on a target and how a target is started.
15234 A layer can extend the controllers by adding a module
15235 in the layer's <filename>/lib/oeqa/controllers</filename>
15236 directory and by inheriting the
15237 <filename>BaseTarget</filename> class, which is an abstract
15238 class that cannot be used as a value of
15239 <filename>TEST_TARGET</filename>.
15240 </para>
15241
15242 <para>
15243 You can provide the following arguments with
15244 <filename>TEST_TARGET</filename>:
15245 <itemizedlist>
15246 <listitem><para><emphasis>"qemu":</emphasis>
15247 Boots a QEMU image and runs the tests.
15248 See the
15249 "<ulink url='&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests'>Enabling Runtime Tests on QEMU</ulink>"
15250 section in the Yocto Project Development Tasks
15251 Manual for more information.
15252 </para></listitem>
15253 <listitem><para><emphasis>"simpleremote":</emphasis>
15254 Runs the tests on target hardware that is already
15255 up and running.
15256 The hardware can be on the network or it can be
15257 a device running an image on QEMU.
15258 You must also set
15259 <link linkend='var-TEST_TARGET_IP'><filename>TEST_TARGET_IP</filename></link>
15260 when you use "simpleremote".
15261 <note>
15262 This argument is defined in
15263 <filename>meta/lib/oeqa/controllers/simpleremote.py</filename>.
15264 </note>
15265 </para></listitem>
15266 </itemizedlist>
15267 </para>
15268
15269 <para>
15270 For information on running tests on hardware, see the
15271 "<ulink url='&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests'>Enabling Runtime Tests on Hardware</ulink>"
15272 section in the Yocto Project Development Tasks Manual.
15273 </para>
15274 </glossdef>
15275 </glossentry>
15276
15277 <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm>
15278 <info>
15279 TEST_TARGET_IP[doc] = "The IP address of your hardware under test."
15280 </info>
15281 <glossdef>
15282 <para role="glossdeffirst">
15283 The IP address of your hardware under test.
15284 The <filename>TEST_TARGET_IP</filename> variable has no
15285 effect when
15286 <link linkend='var-TEST_TARGET'><filename>TEST_TARGET</filename></link>
15287 is set to "qemu".
15288 </para>
15289
15290 <para>
15291 When you specify the IP address, you can also include a
15292 port.
15293 Here is an example:
15294 <literallayout class='monospaced'>
15295 TEST_TARGET_IP = "192.168.1.4:2201"
15296 </literallayout>
15297 Specifying a port is useful when SSH is started on a
15298 non-standard port or in cases when your hardware under test
15299 is behind a firewall or network that is not directly
15300 accessible from your host and you need to do port address
15301 translation.
15302 </para>
15303 </glossdef>
15304 </glossentry>
15305
15306 <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
15307 <info>
15308 TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing."
15309 </info>
15310 <glossdef>
15311 <para role="glossdeffirst">
15312 An ordered list of tests (modules) to run against
15313 an image when performing automated runtime testing.
15314 </para>
15315
15316 <para>
15317 The OpenEmbedded build system provides a core set of tests
15318 that can be used against images.
15319 <note>
15320 Currently, there is only support for running these tests
15321 under QEMU.
15322 </note>
15323 Tests include <filename>ping</filename>,
15324 <filename>ssh</filename>, <filename>df</filename> among
15325 others.
15326 You can add your own tests to the list of tests by
15327 appending <filename>TEST_SUITES</filename> as follows:
15328 <literallayout class='monospaced'>
15329 TEST_SUITES_append = " <replaceable>mytest</replaceable>"
15330 </literallayout>
15331 Alternatively, you can provide the "auto" option to
15332 have all applicable tests run against the image.
15333 <literallayout class='monospaced'>
15334 TEST_SUITES_append = " auto"
15335 </literallayout>
15336 Using this option causes the build system to automatically
15337 run tests that are applicable to the image.
15338 Tests that are not applicable are skipped.
15339 </para>
15340
15341 <para>
15342 The order in which tests are run is important.
15343 Tests that depend on another test must appear later in the
15344 list than the test on which they depend.
15345 For example, if you append the list of tests with two
15346 tests (<filename>test_A</filename> and
15347 <filename>test_B</filename>) where
15348 <filename>test_B</filename> is dependent on
15349 <filename>test_A</filename>, then you must order the tests
15350 as follows:
15351 <literallayout class='monospaced'>
15352 TEST_SUITES = " test_A test_B"
15353 </literallayout>
15354 </para>
15355
15356 <para>
15357 For more information on testing images, see the
15358 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15359 section in the Yocto Project Development Tasks Manual.
15360 </para>
15361 </glossdef>
15362 </glossentry>
15363
15364 <glossentry id='var-TESTIMAGE_AUTO'><glossterm>TESTIMAGE_AUTO</glossterm>
15365 <info>
15366 TESTIMAGE_AUTO[doc] = "Enables automatic testing of an image once it is built."
15367 </info>
15368 <glossdef>
15369 <para role="glossdeffirst">
15370 Automatically runs the series of automated tests for
15371 images when an image is successfully built.
15372 Setting <filename>TESTIMAGE_AUTO</filename> to "1"
15373 causes any image that successfully builds to automatically
15374 boot under QEMU.
15375 Using the variable also adds in dependencies so that any
15376 SDK for which testing is requested is automatically built
15377 first.
15378 </para>
15379
15380 <para>
15381 These tests are written in Python making use of the
15382 <filename>unittest</filename> module, and the majority of
15383 them run commands on the target system over
15384 <filename>ssh</filename>.
15385 You can set this variable to "1" in your
15386 <filename>local.conf</filename> file in the
15387 <link linkend='build-directory'>Build Directory</link>
15388 to have the OpenEmbedded build system automatically run
15389 these tests after an image successfully builds:
15390 <literallayout class='monospaced'>
15391 TESTIMAGE_AUTO = "1"
15392 </literallayout>
15393 For more information on enabling, running, and writing
15394 these tests, see the
15395 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
15396 section in the Yocto Project Development Tasks Manual and
15397 the
15398 "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
15399 section.
15400 </para>
15401 </glossdef>
15402 </glossentry>
15403
15404 <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
15405 <info>
15406 THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located."
15407 </info>
15408 <glossdef>
15409 <para role="glossdeffirst">
15410 The directory in which the file BitBake is currently
15411 parsing is located.
15412 Do not manually set this variable.
15413 </para>
15414 </glossdef>
15415 </glossentry>
15416
15417 <glossentry id='var-TIME'><glossterm>TIME</glossterm>
15418 <info>
15419 TIME[doc] = "The time the build was started using HMS format."
15420 </info>
15421 <glossdef>
15422 <para role="glossdeffirst">
15423 The time the build was started.
15424 Times appear using the hour, minute, and second (HMS)
15425 format (e.g. "140159" for one minute and fifty-nine
15426 seconds past 1400 hours).
15427 </para>
15428 </glossdef>
15429 </glossentry>
15430
15431 <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
15432 <info>
15433 TMPDIR[doc] = "The temporary directory the OpenEmbedded build system uses when it does its work building images. By default, the TMPDIR variable is named tmp within the Build Directory."
15434 </info>
15435 <glossdef>
15436 <para role="glossdeffirst">
15437 This variable is the base directory the OpenEmbedded
15438 build system uses for all build output and intermediate
15439 files (other than the shared state cache).
15440 By default, the <filename>TMPDIR</filename> variable points
15441 to <filename>tmp</filename> within the
15442 <link linkend='build-directory'>Build Directory</link>.
15443 </para>
15444
15445 <para>
15446 If you want to establish this directory in a location other
15447 than the default, you can uncomment and edit the following
15448 statement in the
15449 <filename>conf/local.conf</filename> file in the
15450 <link linkend='source-directory'>Source Directory</link>:
15451 <literallayout class='monospaced'>
15452 #TMPDIR = "${TOPDIR}/tmp"
15453 </literallayout>
15454 An example use for this scenario is to set
15455 <filename>TMPDIR</filename> to a local disk, which does
15456 not use NFS, while having the Build Directory use NFS.
15457 </para>
15458
15459 <para>
15460 The filesystem used by <filename>TMPDIR</filename> must
15461 have standard filesystem semantics (i.e. mixed-case files
15462 are unique, POSIX file locking, and persistent inodes).
15463 Due to various issues with NFS and bugs in some
15464 implementations, NFS does not meet this minimum
15465 requirement.
15466 Consequently, <filename>TMPDIR</filename> cannot be on
15467 NFS.
15468 </para>
15469 </glossdef>
15470 </glossentry>
15471
15472 <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
15473 <info>
15474 TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment."
15475 </info>
15476 <glossdef>
15477 <para role="glossdeffirst">
15478 This variable lists packages the OpenEmbedded build system
15479 uses when building an SDK, which contains a
15480 cross-development environment.
15481 The packages specified by this variable are part of the
15482 toolchain set that runs on the
15483 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
15484 and each package should usually have the prefix
15485 <filename>nativesdk-</filename>.
15486 For example, consider the following command when
15487 building an SDK:
15488 <literallayout class='monospaced'>
15489 $ bitbake -c populate_sdk <replaceable>imagename</replaceable>
15490 </literallayout>
15491 In this case, a default list of packages is set in this
15492 variable, but you can add additional packages to the list.
15493 See the
15494 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
15495 section in the Yocto Project Application Development and
15496 the Extensible Software Development Kit (eSDK) manual
15497 for more information.
15498 </para>
15499
15500 <para>
15501 For background information on cross-development toolchains
15502 in the Yocto Project development environment, see the
15503 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15504 section in the Yocto Project Overview and Concepts Manual.
15505 For information on setting up a cross-development
15506 environment, see the
15507 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15508 manual.
15509 </para>
15510 </glossdef>
15511 </glossentry>
15512
15513 <glossentry id='var-TOOLCHAIN_OUTPUTNAME'><glossterm>TOOLCHAIN_OUTPUTNAME</glossterm>
15514 <info>
15515 TOOLCHAIN_OUTPUTNAME[doc] = "Defines the name used for the toolchain output."
15516 </info>
15517 <glossdef>
15518 <para role="glossdeffirst">
15519 This variable defines the name used for the toolchain
15520 output.
15521 The
15522 <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_base</filename></link>
15523 class sets the
15524 <filename>TOOLCHAIN_OUTPUTNAME</filename> variable as
15525 follows:
15526 <literallayout class='monospaced'>
15527 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
15528 </literallayout>
15529 See the
15530 <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
15531 and
15532 <link linkend='var-SDK_VERSION'><filename>SDK_VERSION</filename></link>
15533 variables for additional information.
15534 </para>
15535 </glossdef>
15536 </glossentry>
15537
15538 <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
15539 <info>
15540 TOOLCHAIN_TARGET_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when it creates the target part of an SDK, which includes libraries and headers."
15541 </info>
15542 <glossdef>
15543 <para role="glossdeffirst">
15544 This variable lists packages the OpenEmbedded build system
15545 uses when it creates the target part of an SDK
15546 (i.e. the part built for the target hardware), which
15547 includes libraries and headers.
15548 Use this variable to add individual packages to the
15549 part of the SDK that runs on the target.
15550 See the
15551 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages'>Adding Individual Packages to the Standard SDK</ulink>"
15552 section in the Yocto Project Application Development and
15553 the Extensible Software Development Kit (eSDK) manual for
15554 more information.
15555 </para>
15556
15557 <para>
15558 For background information on cross-development toolchains
15559 in the Yocto Project development environment, see the
15560 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
15561 section in the Yocto Project Overview and Concepts Manual.
15562 For information on setting up a cross-development
15563 environment, see the
15564 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
15565 manual.
15566 </para>
15567 </glossdef>
15568 </glossentry>
15569
15570 <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
15571 <info>
15572 TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images."
15573 </info>
15574 <glossdef>
15575 <para role="glossdeffirst">
15576 The top-level
15577 <link linkend='build-directory'>Build Directory</link>.
15578 BitBake automatically sets this variable when you
15579 initialize your build environment using
15580 <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>.
15581 </para>
15582 </glossdef>
15583 </glossentry>
15584
15585 <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
15586 <info>
15587 TRANSLATED_TARGET_ARCH[doc] = "A sanitized version of TARGET_ARCH. This variable is used where the architecture is needed in a value where underscores are not allowed."
15588 </info>
15589 <glossdef>
15590 <para role="glossdeffirst">
15591 A sanitized version of
15592 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
15593 This variable is used where the architecture is needed in
15594 a value where underscores are not allowed, for example
15595 within package filenames.
15596 In this case, dash characters replace any underscore
15597 characters used in <filename>TARGET_ARCH</filename>.
15598 </para>
15599
15600 <para>
15601 Do not edit this variable.
15602 </para>
15603 </glossdef>
15604 </glossentry>
15605
15606 <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm>
15607 <info>
15608 TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)."
15609 </info>
15610 <glossdef>
15611 <para role="glossdeffirst">
15612 The GNU canonical architecture for a specific architecture
15613 (i.e. <filename>arm</filename>,
15614 <filename>armeb</filename>,
15615 <filename>mips</filename>,
15616 <filename>mips64</filename>, and so forth).
15617 BitBake uses this value to setup configuration.
15618 </para>
15619
15620 <para>
15621 <filename>TUNE_ARCH</filename> definitions are specific to
15622 a given architecture.
15623 The definitions can be a single static definition, or
15624 can be dynamically adjusted.
15625 You can see details for a given CPU family by looking at
15626 the architecture's <filename>README</filename> file.
15627 For example, the
15628 <filename>meta/conf/machine/include/mips/README</filename>
15629 file in the
15630 <link linkend='source-directory'>Source Directory</link>
15631 provides information for <filename>TUNE_ARCH</filename>
15632 specific to the <filename>mips</filename> architecture.
15633 </para>
15634
15635 <para>
15636 <filename>TUNE_ARCH</filename> is tied closely to
15637 <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>,
15638 which defines the target machine's architecture.
15639 The BitBake configuration file
15640 (<filename>meta/conf/bitbake.conf</filename>) sets
15641 <filename>TARGET_ARCH</filename> as follows:
15642 <literallayout class='monospaced'>
15643 TARGET_ARCH = "${TUNE_ARCH}"
15644 </literallayout>
15645 </para>
15646
15647 <para>
15648 The following list, which is by no means complete since
15649 architectures are configurable, shows supported machine
15650 architectures:
15651 <literallayout class='monospaced'>
15652 arm
15653 i586
15654 x86_64
15655 powerpc
15656 powerpc64
15657 mips
15658 mipsel
15659 </literallayout>
15660 </para>
15661 </glossdef>
15662 </glossentry>
15663
15664 <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm>
15665 <info>
15666 TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system."
15667 </info>
15668 <glossdef>
15669 <para role="glossdeffirst">
15670 Specifies architecture-specific assembler flags for
15671 the target system.
15672 The set of flags is based on the selected tune features.
15673 <filename>TUNE_ASARGS</filename> is set using
15674 the tune include files, which are typically under
15675 <filename>meta/conf/machine/include/</filename> and are
15676 influenced through
15677 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
15678 For example, the
15679 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
15680 file defines the flags for the x86 architecture as follows:
15681 <literallayout class='monospaced'>
15682 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
15683 </literallayout>
15684 <note>
15685 Board Support Packages (BSPs) select the tune.
15686 The selected tune, in turn, affects the tune variables
15687 themselves (i.e. the tune can supply its own
15688 set of flags).
15689 </note>
15690 </para>
15691 </glossdef>
15692 </glossentry>
15693
15694 <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm>
15695 <info>
15696 TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system."
15697 </info>
15698 <glossdef>
15699 <para role="glossdeffirst">
15700 Specifies architecture-specific C compiler flags for
15701 the target system.
15702 The set of flags is based on the selected tune features.
15703 <filename>TUNE_CCARGS</filename> is set using
15704 the tune include files, which are typically under
15705 <filename>meta/conf/machine/include/</filename> and are
15706 influenced through
15707 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
15708 <note>
15709 Board Support Packages (BSPs) select the tune.
15710 The selected tune, in turn, affects the tune variables
15711 themselves (i.e. the tune can supply its own
15712 set of flags).
15713 </note>
15714 </para>
15715 </glossdef>
15716 </glossentry>
15717
15718 <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm>
15719 <info>
15720 TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system."
15721 </info>
15722 <glossdef>
15723 <para role="glossdeffirst">
15724 Specifies architecture-specific linker flags for
15725 the target system.
15726 The set of flags is based on the selected tune features.
15727 <filename>TUNE_LDARGS</filename> is set using
15728 the tune include files, which are typically under
15729 <filename>meta/conf/machine/include/</filename> and are
15730 influenced through
15731 <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>.
15732 For example, the
15733 <filename>meta/conf/machine/include/x86/arch-x86.inc</filename>
15734 file defines the flags for the x86 architecture as follows:
15735 <literallayout class='monospaced'>
15736 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
15737 </literallayout>
15738 <note>
15739 Board Support Packages (BSPs) select the tune.
15740 The selected tune, in turn, affects the tune variables
15741 themselves (i.e. the tune can supply its own
15742 set of flags).
15743 </note>
15744 </para>
15745 </glossdef>
15746 </glossentry>
15747
15748 <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm>
15749 <info>
15750 TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor."
15751 </info>
15752 <glossdef>
15753 <para role="glossdeffirst">
15754 Features used to "tune" a compiler for optimal use
15755 given a specific processor.
15756 The features are defined within the tune files and allow
15757 arguments (i.e. <filename>TUNE_*ARGS</filename>) to be
15758 dynamically generated based on the features.
15759 </para>
15760
15761 <para>
15762 The OpenEmbedded build system verifies the features
15763 to be sure they are not conflicting and that they are
15764 supported.
15765 </para>
15766
15767 <para>
15768 The BitBake configuration file
15769 (<filename>meta/conf/bitbake.conf</filename>) defines
15770 <filename>TUNE_FEATURES</filename> as follows:
15771 <literallayout class='monospaced'>
15772 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
15773 </literallayout>
15774 See the
15775 <link linkend='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></link>
15776 variable for more information.
15777 </para>
15778 </glossdef>
15779 </glossentry>
15780
15781 <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
15782 <info>
15783 TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages."
15784 </info>
15785 <glossdef>
15786 <para role="glossdeffirst">
15787 The package architecture understood by the packaging
15788 system to define the architecture, ABI, and tuning of
15789 output packages.
15790 The specific tune is defined using the "_tune" override
15791 as follows:
15792 <literallayout class='monospaced'>
15793 TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>"
15794 </literallayout>
15795 </para>
15796
15797 <para>
15798 These tune-specific package architectures are defined in
15799 the machine include files.
15800 Here is an example of the "core2-32" tuning as used
15801 in the
15802 <filename>meta/conf/machine/include/tune-core2.inc</filename>
15803 file:
15804 <literallayout class='monospaced'>
15805 TUNE_PKGARCH_tune-core2-32 = "core2-32"
15806 </literallayout>
15807 </para>
15808 </glossdef>
15809 </glossentry>
15810
15811 <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm>
15812 <info>
15813 TUNEABI[doc] = "An underlying ABI used by a particular tuning in a given toolchain layer. This feature allows providers using prebuilt libraries to check compatibility of a tuning against their selection of libraries."
15814 </info>
15815 <glossdef>
15816 <para role="glossdeffirst">
15817 An underlying Application Binary Interface (ABI) used by
15818 a particular tuning in a given toolchain layer.
15819 Providers that use prebuilt libraries can use the
15820 <filename>TUNEABI</filename>,
15821 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
15822 and
15823 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
15824 variables to check compatibility of tunings against their
15825 selection of libraries.
15826 </para>
15827
15828 <para>
15829 If <filename>TUNEABI</filename> is undefined, then every
15830 tuning is allowed.
15831 See the
15832 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
15833 class to see how the variable is used.
15834 </para>
15835 </glossdef>
15836 </glossentry>
15837
15838 <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm>
15839 <info>
15840 TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST."
15841 </info>
15842 <glossdef>
15843 <para role="glossdeffirst">
15844 If set, the OpenEmbedded system ignores the
15845 <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link>
15846 variable.
15847 Providers that use prebuilt libraries can use the
15848 <filename>TUNEABI_OVERRIDE</filename>,
15849 <filename>TUNEABI_WHITELIST</filename>,
15850 and
15851 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
15852 variables to check compatibility of a tuning against their
15853 selection of libraries.
15854 </para>
15855
15856 <para>
15857 See the
15858 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
15859 class to see how the variable is used.
15860 </para>
15861 </glossdef>
15862 </glossentry>
15863
15864 <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm>
15865 <info>
15866 TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed."
15867 </info>
15868 <glossdef>
15869 <para role="glossdeffirst">
15870 A whitelist of permissible
15871 <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link>
15872 values.
15873 If <filename>TUNEABI_WHITELIST</filename> is not set,
15874 all tunes are allowed.
15875 Providers that use prebuilt libraries can use the
15876 <filename>TUNEABI_WHITELIST</filename>,
15877 <link linkend='var-TUNEABI_OVERRIDE'><filename>TUNEABI_OVERRIDE</filename></link>,
15878 and <filename>TUNEABI</filename> variables to check
15879 compatibility of a tuning against their selection of
15880 libraries.
15881 </para>
15882
15883 <para>
15884 See the
15885 <link linkend='ref-classes-sanity'><filename>sanity</filename></link>
15886 class to see how the variable is used.
15887 </para>
15888 </glossdef>
15889 </glossentry>
15890
15891 <glossentry id='var-TUNECONFLICTS'><glossterm>TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm>
15892 <info>
15893 TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature."
15894 </info>
15895 <glossdef>
15896 <para role="glossdeffirst">
15897 Specifies CPU or Application Binary Interface (ABI)
15898 tuning features that conflict with <replaceable>feature</replaceable>.
15899 </para>
15900
15901 <para>
15902 Known tuning conflicts are specified in the machine include
15903 files in the
15904 <link linkend='source-directory'>Source Directory</link>.
15905 Here is an example from the
15906 <filename>meta/conf/machine/include/mips/arch-mips.inc</filename>
15907 include file that lists the "o32" and "n64" features as
15908 conflicting with the "n32" feature:
15909 <literallayout class='monospaced'>
15910 TUNECONFLICTS[n32] = "o32 n64"
15911 </literallayout>
15912 </para>
15913 </glossdef>
15914 </glossentry>
15915
15916 <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm>
15917 <info>
15918 TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features."
15919 </info>
15920 <glossdef>
15921 <para role="glossdeffirst">
15922 Specifies a valid CPU or Application Binary Interface (ABI)
15923 tuning feature.
15924 The specified feature is stored as a flag.
15925 Valid features are specified in the machine include files
15926 (e.g. <filename>meta/conf/machine/include/arm/arch-arm.inc</filename>).
15927 Here is an example from that file:
15928 <literallayout class='monospaced'>
15929 TUNEVALID[bigendian] = "Enable big-endian mode."
15930 </literallayout>
15931 </para>
15932
15933 <para>
15934 See the machine include files in the
15935 <link linkend='source-directory'>Source Directory</link>
15936 for these features.
15937 </para>
15938 </glossdef>
15939 </glossentry>
15940
15941 </glossdiv>
15942
15943 <glossdiv id='var-glossary-u'><title>U</title>
15944
15945 <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm>
15946 <info>
15947 UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases."
15948 </info>
15949 <glossdef>
15950 <para role="glossdeffirst">
15951 Configures the
15952 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
15953 and can also define
15954 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
15955 for individual cases.
15956 </para>
15957
15958 <para>
15959 Following is an example from the
15960 <filename>meta-fsl-arm</filename> layer.
15961 <literallayout class='monospaced'>
15962 UBOOT_CONFIG ??= "sd"
15963 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
15964 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
15965 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
15966 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
15967 </literallayout>
15968 In this example, "sd" is selected as the configuration
15969 of the possible four for the
15970 <filename>UBOOT_MACHINE</filename>.
15971 The "sd" configuration defines "mx6qsabreauto_config"
15972 as the value for <filename>UBOOT_MACHINE</filename>, while
15973 the "sdcard" specifies the
15974 <filename>IMAGE_FSTYPES</filename> to use for the U-boot
15975 image.
15976 </para>
15977
15978 <para>
15979 For more information on how the
15980 <filename>UBOOT_CONFIG</filename> is handled, see the
15981 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass'><filename>uboot-config</filename></ulink>
15982 class.
15983 </para>
15984 </glossdef>
15985 </glossentry>
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
16019 <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
16020 <info>
16021 UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image."
16022 </info>
16023 <glossdef>
16024 <para role="glossdeffirst">
16025 Specifies the entry point for the U-Boot image.
16026 During U-Boot image creation, the
16027 <filename>UBOOT_ENTRYPOINT</filename> variable is passed
16028 as a command-line parameter to the
16029 <filename>uboot-mkimage</filename> utility.
16030 </para>
16031 </glossdef>
16032 </glossentry>
16033
16034 <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
16035 <info>
16036 UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image."
16037 </info>
16038 <glossdef>
16039 <para role="glossdeffirst">
16040 Specifies the load address for the U-Boot image.
16041 During U-Boot image creation, the
16042 <filename>UBOOT_LOADADDRESS</filename> variable is passed
16043 as a command-line parameter to the
16044 <filename>uboot-mkimage</filename> utility.
16045 </para>
16046 </glossdef>
16047 </glossentry>
16048
16049 <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm>
16050 <info>
16051 UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image."
16052 </info>
16053 <glossdef>
16054 <para role="glossdeffirst">
16055 Appends a string to the name of the local version of the
16056 U-Boot image.
16057 For example, assuming the version of the U-Boot image
16058 built was "2013.10", the full version string reported by
16059 U-Boot would be "2013.10-yocto" given the following
16060 statement:
16061 <literallayout class='monospaced'>
16062 UBOOT_LOCALVERSION = "-yocto"
16063 </literallayout>
16064 </para>
16065 </glossdef>
16066 </glossentry>
16067
16068 <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
16069 <info>
16070 UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image."
16071 </info>
16072 <glossdef>
16073 <para role="glossdeffirst">
16074 Specifies the value passed on the
16075 <filename>make</filename> command line when building
16076 a U-Boot image.
16077 The value indicates the target platform configuration.
16078 You typically set this variable from the machine
16079 configuration file (i.e.
16080 <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>).
16081 </para>
16082
16083 <para>
16084 Please see the "Selection of Processor Architecture and
16085 Board Type" section in the U-Boot README for valid values
16086 for this variable.
16087 </para>
16088 </glossdef>
16089 </glossentry>
16090
16091 <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm>
16092 <info>
16093 UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile."
16094 </info>
16095 <glossdef>
16096 <para role="glossdeffirst">
16097 Specifies the target called in the
16098 <filename>Makefile</filename>.
16099 The default target is "all".
16100 </para>
16101 </glossdef>
16102 </glossentry>
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
16149 <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm>
16150 <info>
16151 UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension."
16152 </info>
16153 <glossdef>
16154 <para role="glossdeffirst">
16155 Points to the generated U-Boot extension.
16156 For example, <filename>u-boot.sb</filename> has a
16157 <filename>.sb</filename> extension.
16158 </para>
16159
16160 <para>
16161 The default U-Boot extension is
16162 <filename>.bin</filename>
16163 </para>
16164 </glossdef>
16165 </glossentry>
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
16208 <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
16209 <info>
16210 UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot."
16211 </info>
16212 <glossdef>
16213 <para role="glossdeffirst">
16214 Specifies the target used for building U-Boot.
16215 The target is passed directly as part of the "make" command
16216 (e.g. SPL and AIS).
16217 If you do not specifically set this variable, the
16218 OpenEmbedded build process passes and uses "all" for the
16219 target during the U-Boot building process.
16220 </para>
16221 </glossdef>
16222 </glossentry>
16223
16224 <glossentry id='var-UNKNOWN_CONFIGURE_WHITELIST'><glossterm>UNKNOWN_CONFIGURE_WHITELIST</glossterm>
16225 <info>
16226 UNKNOWN_CONFIGURE_WHITELIST[doc] = "Specifies a list of options that, if reported by the configure script as being invalid, should not generate a warning during the do_configure task."
16227 </info>
16228 <glossdef>
16229 <para role="glossdeffirst">
16230 Specifies a list of options that, if reported by the
16231 configure script as being invalid, should not generate a
16232 warning during the
16233 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
16234 task.
16235 Normally, invalid configure options are simply not passed
16236 to the configure script (e.g. should be removed from
16237 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
16238 or
16239 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>).
16240 However, common options, for example, exist that are passed
16241 to all configure scripts at a class level that might not
16242 be valid for some configure scripts.
16243 It follows that no benefit exists in seeing a warning about
16244 these options.
16245 For these cases, the options are added to
16246 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename>.
16247 </para>
16248
16249 <para>
16250 The configure arguments check that uses
16251 <filename>UNKNOWN_CONFIGURE_WHITELIST</filename> is part
16252 of the
16253 <link linkend='ref-classes-insane'><filename>insane</filename></link>
16254 class and is only enabled if the recipe inherits the
16255 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
16256 class.
16257 </para>
16258 </glossdef>
16259 </glossentry>
16260
16261 <glossentry id='var-UPDATERCPN'><glossterm>UPDATERCPN</glossterm>
16262 <info>
16263 UPDATERCPN[doc] = "Specifies the package that contains the initscript that is enabled."
16264 </info>
16265 <glossdef>
16266 <para role="glossdeffirst">
16267 For recipes inheriting the
16268 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
16269 class, <filename>UPDATERCPN</filename> specifies
16270 the package that contains the initscript that is
16271 enabled.
16272 </para>
16273
16274 <para>
16275 The default value is "${PN}".
16276 Given that almost all recipes that install initscripts
16277 package them in the main package for the recipe, you
16278 rarely need to set this variable in individual recipes.
16279 </para>
16280 </glossdef>
16281 </glossentry>
16282
16283 <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm>
16284 <info>
16285 UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository."
16286 </info>
16287 <glossdef>
16288 <para role="glossdeffirst">
16289 You can perform a per-recipe check for what the latest
16290 upstream source code version is by calling
16291 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16292 If the recipe source code is provided from Git
16293 repositories, the OpenEmbedded build system determines the
16294 latest upstream version by picking the latest tag from the
16295 list of all repository tags.
16296 </para>
16297
16298 <para>
16299 You can use the
16300 <filename>UPSTREAM_CHECK_GITTAGREGEX</filename>
16301 variable to provide a regular expression to filter only the
16302 relevant tags should the default filter not work
16303 correctly.
16304 <literallayout class='monospaced'>
16305 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
16306 </literallayout>
16307 </para>
16308 </glossdef>
16309 </glossentry>
16310
16311 <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm>
16312 <info>
16313 UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI."
16314 </info>
16315 <glossdef>
16316 <para role="glossdeffirst">
16317 Use the <filename>UPSTREAM_CHECK_REGEX</filename> variable
16318 to specify a different regular expression instead of the
16319 default one when the package checking system is parsing
16320 the page found using
16321 <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>.
16322 <literallayout class='monospaced'>
16323 UPSTREAM_CHECK_REGEX = "package_regex"
16324 </literallayout>
16325 </para>
16326 </glossdef>
16327 </glossentry>
16328
16329 <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm>
16330 <info>
16331 UPSTREAM_CHECK_URI[doc] = "The URL used by the package checking system to get the latest version of the package when source files are fetched from an upstream Git repository."
16332 </info>
16333 <glossdef>
16334 <para role="glossdeffirst">
16335 You can perform a per-recipe check for what the latest
16336 upstream source code version is by calling
16337 <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>.
16338 If the source code is provided from tarballs, the latest
16339 version is determined by fetching the directory listing
16340 where the tarball is and attempting to find a later tarball.
16341 When this approach does not work, you can use
16342 <filename>UPSTREAM_CHECK_URI</filename> to
16343 provide a different URI that contains the link to the
16344 latest tarball.
16345 <literallayout class='monospaced'>
16346 UPSTREAM_CHECK_URI = "recipe_url"
16347 </literallayout>
16348 </para>
16349 </glossdef>
16350 </glossentry>
16351
16352 <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm>
16353 <info>
16354 USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population."
16355 </info>
16356 <glossdef>
16357 <para role="glossdeffirst">
16358 Determines if <filename>devtmpfs</filename> is used for
16359 <filename>/dev</filename> population.
16360 The default value used for <filename>USE_DEVFS</filename>
16361 is "1" when no value is specifically set.
16362 Typically, you would set <filename>USE_DEVFS</filename>
16363 to "0" for a statically populated <filename>/dev</filename>
16364 directory.
16365 </para>
16366
16367 <para>
16368 See the
16369 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>"
16370 section in the Yocto Project Development Tasks Manual for
16371 information on how to use this variable.
16372 </para>
16373 </glossdef>
16374 </glossentry>
16375
16376 <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm>
16377 <info>
16378 USE_VT[doc] = "When using SysVinit, determines whether or not to run a getty on any virtual terminals in order to enable logging in through those terminals."
16379 </info>
16380 <glossdef>
16381 <para role="glossdeffirst">
16382 When using
16383 <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>,
16384 determines whether or not to run a
16385 <ulink url='http://en.wikipedia.org/wiki/Getty_%28Unix%29'>getty</ulink>
16386 on any virtual terminals in order to enable logging in
16387 through those terminals.
16388 </para>
16389
16390 <para>
16391 The default value used for <filename>USE_VT</filename>
16392 is "1" when no default value is specifically set.
16393 Typically, you would set <filename>USE_VT</filename>
16394 to "0" in the machine configuration file for machines
16395 that do not have a graphical display attached and
16396 therefore do not need virtual terminal functionality.
16397 </para>
16398 </glossdef>
16399 </glossentry>
16400
16401 <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
16402 <info>
16403 USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features."
16404 </info>
16405 <glossdef>
16406 <para role="glossdeffirst">
16407 A list of classes to globally inherit.
16408 These classes are used by the OpenEmbedded build system
16409 to enable extra features (e.g.
16410 <filename>buildstats</filename>,
16411 <filename>image-mklibs</filename>, and so forth).
16412 </para>
16413
16414 <para>
16415 The default list is set in your
16416 <filename>local.conf</filename> file:
16417 <literallayout class='monospaced'>
16418 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
16419 </literallayout>
16420 For more information, see
16421 <filename>meta-poky/conf/local.conf.sample</filename> in
16422 the
16423 <link linkend='source-directory'>Source Directory</link>.
16424 </para>
16425 </glossdef>
16426 </glossentry>
16427
16428 <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm>
16429 <info>
16430 USERADD_ERROR_DYNAMIC[doc] = "If set to 'error', forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in any of the files listed in USERADD_UID_TABLES and USERADD_GID_TABLES. If set to 'warn', a warning will be issued instead."
16431 </info>
16432 <glossdef>
16433 <para role="glossdeffirst">
16434
16435 If set to <filename>error</filename>, forces the
16436 OpenEmbedded build system to produce an error if the user
16437 identification (<filename>uid</filename>) and group
16438 identification (<filename>gid</filename>) values are not
16439 defined in any of the files listed
16440 in <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16441 and <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>. If
16442 set to <filename>warn</filename>, a warning will be issued
16443 instead.
16444 </para>
16445
16446 <para>
16447 The default behavior for the build system is to dynamically
16448 apply <filename>uid</filename> and
16449 <filename>gid</filename> values.
16450 Consequently, the <filename>USERADD_ERROR_DYNAMIC</filename>
16451 variable is by default not set.
16452 If you plan on using statically assigned
16453 <filename>gid</filename> and <filename>uid</filename>
16454 values, you should set
16455 the <filename>USERADD_ERROR_DYNAMIC</filename> variable in
16456 your <filename>local.conf</filename> file as
16457 follows:
16458 <literallayout class='monospaced'>
16459 USERADD_ERROR_DYNAMIC = "error"
16460 </literallayout>
16461 Overriding the default behavior implies you are going to
16462 also take steps to set static <filename>uid</filename> and
16463 <filename>gid</filename> values through use of the
16464 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
16465 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
16466 and
16467 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16468 variables.
16469 </para>
16470
16471 <note>
16472 There is a difference in behavior between
16473 setting <filename>USERADD_ERROR_DYNAMIC</filename>
16474 to <filename>error</filename> and setting it
16475 to <filename>warn</filename>. When it is set
16476 to <filename>warn</filename>, the build system will report a
16477 warning for every undefined <filename>uid</filename> and
16478 <filename>gid</filename> in any recipe. But when it is set
16479 to <filename>error</filename>, it will only report errors
16480 for recipes that are actually built. This saves you from
16481 having to add static IDs for recipes that you know will
16482 never be built.
16483 </note>
16484 </glossdef>
16485 </glossentry>
16486
16487 <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm>
16488 <info>
16489 USERADD_GID_TABLES[doc] = "Specifies a password file to use for obtaining static group identification (gid) values when the OpenEmbedded build system adds a group to the system during package installation."
16490 </info>
16491 <glossdef>
16492 <para role="glossdeffirst">
16493 Specifies a password file to use for obtaining static
16494 group identification (<filename>gid</filename>) values
16495 when the OpenEmbedded build system adds a group to the
16496 system during package installation.
16497 </para>
16498
16499 <para>
16500 When applying static group identification
16501 (<filename>gid</filename>) values, the OpenEmbedded build
16502 system looks in
16503 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16504 for a <filename>files/group</filename> file and then applies
16505 those <filename>uid</filename> values.
16506 Set the variable as follows in your
16507 <filename>local.conf</filename> file:
16508 <literallayout class='monospaced'>
16509 USERADD_GID_TABLES = "files/group"
16510 </literallayout>
16511 </para>
16512
16513 <note>
16514 Setting the
16515 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16516 variable to "useradd-staticids" causes the build system
16517 to use static <filename>gid</filename> values.
16518 </note>
16519 </glossdef>
16520 </glossentry>
16521
16522 <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm>
16523 <info>
16524 USERADD_PACKAGES[doc] = "When a recipe inherits the useradd class, this variable specifies the individual packages within the recipe that require users and/or groups to be added."
16525 </info>
16526 <glossdef>
16527 <para role="glossdeffirst">
16528 When inheriting the
16529 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16530 class, this variable
16531 specifies the individual packages within the recipe that
16532 require users and/or groups to be added.
16533 </para>
16534
16535 <para>
16536 You must set this variable if the recipe inherits the
16537 class.
16538 For example, the following enables adding a user for the
16539 main package in a recipe:
16540 <literallayout class='monospaced'>
16541 USERADD_PACKAGES = "${PN}"
16542 </literallayout>
16543 <note>
16544 It follows that if you are going to use the
16545 <filename>USERADD_PACKAGES</filename> variable,
16546 you need to set one or more of the
16547 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
16548 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
16549 or
16550 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
16551 variables.
16552 </note>
16553 </para>
16554
16555 </glossdef>
16556 </glossentry>
16557
16558 <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm>
16559 <info>
16560 USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should pass to the useradd command if you add a user to the system when the package is installed."
16561 </info>
16562 <glossdef>
16563 <para role="glossdeffirst">
16564 When inheriting the
16565 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
16566 class, this variable
16567 specifies for a package what parameters should pass
16568 to the <filename>useradd</filename> command
16569 if you add a user to the system when the package
16570 is installed.
16571 </para>
16572
16573 <para>
16574 Here is an example from the <filename>dbus</filename>
16575 recipe:
16576 <literallayout class='monospaced'>
16577 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
16578 --no-create-home --shell /bin/false \
16579 --user-group messagebus"
16580 </literallayout>
16581 For information on the standard Linux shell command
16582 <filename>useradd</filename>, see
16583 <ulink url='http://linux.die.net/man/8/useradd'></ulink>.
16584 </para>
16585 </glossdef>
16586 </glossentry>
16587
16588 <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm>
16589 <info>
16590 USERADD_UID_TABLES[doc] = "Specifies a password file to use for obtaining static user identification (uid) values when the OpenEmbedded build system adds a user to the system during package installation."
16591 </info>
16592 <glossdef>
16593 <para role="glossdeffirst">
16594 Specifies a password file to use for obtaining static
16595 user identification (<filename>uid</filename>) values
16596 when the OpenEmbedded build system adds a user to the
16597 system during package installation.
16598 </para>
16599
16600 <para>
16601 When applying static user identification
16602 (<filename>uid</filename>) values, the OpenEmbedded build
16603 system looks in
16604 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
16605 for a <filename>files/passwd</filename> file and then applies
16606 those <filename>uid</filename> values.
16607 Set the variable as follows in your
16608 <filename>local.conf</filename> file:
16609 <literallayout class='monospaced'>
16610 USERADD_UID_TABLES = "files/passwd"
16611 </literallayout>
16612 </para>
16613
16614 <note>
16615 Setting the
16616 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>
16617 variable to "useradd-staticids" causes the build system
16618 to use static <filename>uid</filename> values.
16619 </note>
16620 </glossdef>
16621 </glossentry>
16622
16623 <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm>
16624 <info>
16625 USERADDEXTENSION[doc] = "When set to 'useradd-staticids', causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH."
16626 </info>
16627 <glossdef>
16628 <para role="glossdeffirst">
16629 When set to "useradd-staticids", causes the
16630 OpenEmbedded build system to base all user and group
16631 additions on a static
16632 <filename>passwd</filename> and
16633 <filename>group</filename> files found in
16634 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>.
16635 </para>
16636
16637 <para>
16638 To use static user identification (<filename>uid</filename>)
16639 and group identification (<filename>gid</filename>)
16640 values, set the variable
16641 as follows in your <filename>local.conf</filename> file:
16642 <literallayout class='monospaced'>
16643 USERADDEXTENSION = "useradd-staticids"
16644 </literallayout>
16645 <note>
16646 Setting this variable to use static
16647 <filename>uid</filename> and <filename>gid</filename>
16648 values causes the OpenEmbedded build system to employ
16649 the
16650 <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
16651 class.
16652 </note>
16653 </para>
16654
16655 <para>
16656 If you use static <filename>uid</filename> and
16657 <filename>gid</filename> information, you must also
16658 specify the <filename>files/passwd</filename> and
16659 <filename>files/group</filename> files by setting the
16660 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>
16661 and
16662 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>
16663 variables.
16664 Additionally, you should also set the
16665 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
16666 variable.
16667 </para>
16668 </glossdef>
16669 </glossentry>
16670
16671 </glossdiv>
16672
16673 <glossdiv id='var-glossary-v'><title>V</title>
16674
16675 <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm>
16676 <info>
16677 VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files."
16678 </info>
16679 <glossdef>
16680 <para role="glossdeffirst">
16681 Specifies the persistence of the target's
16682 <filename>/var/log</filename> directory, which is used to
16683 house postinstall target log files.
16684 </para>
16685
16686 <para>
16687 By default, <filename>VOLATILE_LOG_DIR</filename> is set
16688 to "yes", which means the file is not persistent.
16689 You can override this setting by setting the
16690 variable to "no" to make the log directory persistent.
16691 </para>
16692 </glossdef>
16693 </glossentry>
16694
16695 </glossdiv>
16696
16697 <glossdiv id='var-glossary-w'><title>W</title>
16698
16699 <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
16700 <info>
16701 WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system."
16702 </info>
16703 <glossdef>
16704 <para role="glossdeffirst">
16705 Specifies the quality assurance checks whose failures are
16706 reported as warnings by the OpenEmbedded build system.
16707 You set this variable in your distribution configuration
16708 file.
16709 For a list of the checks you can control with this variable,
16710 see the
16711 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
16712 section.
16713 </para>
16714 </glossdef>
16715 </glossentry>
16716
16717 <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm>
16718 <info>
16719 WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic."
16720 </info>
16721 <glossdef>
16722 <para role="glossdeffirst">
16723 When placed in the recipe that builds your image, this
16724 variable lists build-time dependencies.
16725 The <filename>WKS_FILE_DEPENDS</filename> variable is only
16726 applicable when Wic images are active (i.e. when
16727 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
16728 contains entries related to Wic).
16729 If your recipe does not create Wic images, the variable
16730 has no effect.
16731 </para>
16732
16733 <para>
16734 The <filename>WKS_FILE_DEPENDS</filename> variable is
16735 similar to the
16736 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
16737 variable.
16738 When you use the variable in your recipe that builds the
16739 Wic image, dependencies you list in the
16740 <filename>WIC_FILE_DEPENDS</filename> variable are added to
16741 the <filename>DEPENDS</filename> variable.
16742 </para>
16743
16744 <para>
16745 With the <filename>WKS_FILE_DEPENDS</filename> variable,
16746 you have the possibility to specify a list of additional
16747 dependencies (e.g. native tools, bootloaders, and so forth),
16748 that are required to build Wic images.
16749 Following is an example:
16750 <literallayout class='monospaced'>
16751 WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>"
16752 </literallayout>
16753 In the previous example,
16754 <replaceable>some-native-tool</replaceable> would be
16755 replaced with an actual native tool on which the build
16756 would depend.
16757 </para>
16758 </glossdef>
16759 </glossentry>
16760
16761 <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm>
16762 <info>
16763 WKS_FILE[doc] = "Specifies the name of the wic kickstart file."
16764 </info>
16765 <glossdef>
16766 <para role="glossdeffirst">
16767 Specifies the location of the Wic
16768 kickstart file that is used by the OpenEmbedded build
16769 system to create a partitioned image
16770 (<replaceable>image</replaceable><filename>.wic</filename>).
16771 For information on how to create a partitioned image, see
16772 the
16773 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic'>Creating Partitioned Images Using Wic</ulink>"
16774 section in the Yocto Project Development Tasks Manual.
16775 For details on the kickstart file format, see the
16776 "<link linkend='ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</link>"
16777 Chapter.
16778 </para>
16779 </glossdef>
16780 </glossentry>
16781
16782 <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
16783 <info>
16784 WORKDIR[doc] = "The pathname of the working directory in which the OpenEmbedded build system builds a recipe. This directory is located within the TMPDIR directory structure and changes as different packages are built."
16785 </info>
16786 <glossdef>
16787 <para role="glossdeffirst">
16788 The pathname of the work directory in which the OpenEmbedded
16789 build system builds a recipe.
16790 This directory is located within the
16791 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
16792 directory structure and is specific to the recipe being
16793 built and the system for which it is being built.
16794 </para>
16795
16796 <para>
16797 The <filename>WORKDIR</filename> directory is defined as
16798 follows:
16799 <literallayout class='monospaced'>
16800 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
16801 </literallayout>
16802 The actual directory depends on several things:
16803 <itemizedlist>
16804 <listitem><filename>TMPDIR</filename>:
16805 The top-level build output directory</listitem>
16806 <listitem><link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>:
16807 The target system identifier</listitem>
16808 <listitem><link linkend='var-PN'><filename>PN</filename></link>:
16809 The recipe name</listitem>
16810 <listitem><link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>:
16811 The epoch - (if
16812 <link linkend='var-PE'><filename>PE</filename></link>
16813 is not specified, which is usually the case for most
16814 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
16815 <listitem><link linkend='var-PV'><filename>PV</filename></link>:
16816 The recipe version</listitem>
16817 <listitem><link linkend='var-PR'><filename>PR</filename></link>:
16818 The recipe revision</listitem>
16819 </itemizedlist>
16820 </para>
16821
16822 <para>
16823 As an example, assume a Source Directory top-level folder
16824 name <filename>poky</filename>, a default Build Directory at
16825 <filename>poky/build</filename>, and a
16826 <filename>qemux86-poky-linux</filename> machine target
16827 system.
16828 Furthermore, suppose your recipe is named
16829 <filename>foo_1.3.0-r0.bb</filename>.
16830 In this case, the work directory the build system uses to
16831 build the package would be as follows:
16832 <literallayout class='monospaced'>
16833 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
16834 </literallayout>
16835 </para>
16836 </glossdef>
16837 </glossentry>
16838
16839 </glossdiv>
16840
16841 <glossdiv id='var-glossary-x'><title>X</title>
16842
16843 <glossentry id='var-XSERVER'><glossterm>XSERVER</glossterm>
16844 <info>
16845 XSERVER[doc] = "Specifies the packages that should be installed to provide an X server and drivers for the current machine."
16846 </info>
16847 <glossdef>
16848 <para role="glossdeffirst">
16849 Specifies the packages that should be installed to
16850 provide an X server and drivers for the current machine,
16851 assuming your image directly includes
16852 <filename>packagegroup-core-x11-xserver</filename> or,
16853 perhaps indirectly, includes "x11-base" in
16854 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
16855 </para>
16856
16857 <para>
16858 The default value of <filename>XSERVER</filename>, if not
16859 specified in the machine configuration, is
16860 "xserver-xorg xf86-video-fbdev xf86-input-evdev".
16861 </para>
16862 </glossdef>
16863 </glossentry>
16864
16865 </glossdiv>
16866
16867<!-- <glossdiv id='var-glossary-y'><title>Y</title>-->
16868<!-- </glossdiv>-->
16869
16870<!-- <glossdiv id='var-glossary-z'><title>Z</title>-->
16871<!-- </glossdiv>-->
16872
16873</glossary>
16874</chapter>
16875<!--
16876vim: expandtab tw=80 ts=4
16877-->
diff --git a/documentation/ref-manual/ref-varlocality.xml b/documentation/ref-manual/ref-varlocality.xml
deleted file mode 100644
index a2436fb310..0000000000
--- a/documentation/ref-manual/ref-varlocality.xml
+++ /dev/null
@@ -1,199 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-varlocality'>
7 <title>Variable Context</title>
8
9 <para>
10 While you can use most variables in almost any context such as
11 <filename>.conf</filename>, <filename>.bbclass</filename>,
12 <filename>.inc</filename>, and <filename>.bb</filename> files,
13 some variables are often associated with a particular locality or context.
14 This chapter describes some common associations.
15 </para>
16
17 <section id='ref-varlocality-configuration'>
18 <title>Configuration</title>
19
20 <para>
21 The following subsections provide lists of variables whose context is
22 configuration: distribution, machine, and local.
23 </para>
24
25 <section id='ref-varlocality-config-distro'>
26 <title>Distribution (Distro)</title>
27
28 <para>
29 This section lists variables whose configuration context is the
30 distribution, or distro.
31 <itemizedlist>
32 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename></para></listitem>
33 <listitem><para><filename><link linkend='var-DISTRO_NAME'>DISTRO_NAME</link></filename>
34 </para></listitem>
35 <listitem><para><filename><link linkend='var-DISTRO_VERSION'>DISTRO_VERSION</link>
36 </filename></para></listitem>
37 <listitem><para><filename><link linkend='var-MAINTAINER'>MAINTAINER</link></filename>
38 </para></listitem>
39 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
40 </filename></para></listitem>
41 <listitem><para><filename><link linkend='var-TARGET_OS'>TARGET_OS</link></filename>
42 </para></listitem>
43 <listitem><para><filename><link linkend='var-TARGET_FPU'>TARGET_FPU</link></filename>
44 </para></listitem>
45 <listitem><para><filename><link linkend='var-TCMODE'>TCMODE</link></filename>
46 </para></listitem>
47 <listitem><para><filename><link linkend='var-TCLIBC'>TCLIBC</link></filename>
48 </para></listitem>
49 </itemizedlist>
50 </para>
51 </section>
52
53 <section id='ref-varlocality-config-machine'>
54 <title>Machine</title>
55
56 <para>
57 This section lists variables whose configuration context is the
58 machine.
59 <itemizedlist>
60 <listitem><para><filename><link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></filename>
61 </para></listitem>
62 <listitem><para><filename><link linkend='var-SERIAL_CONSOLES'>SERIAL_CONSOLES</link>
63 </filename></para></listitem>
64 <listitem><para><filename><link linkend='var-PACKAGE_EXTRA_ARCHS'>PACKAGE_EXTRA_ARCHS</link>
65 </filename></para></listitem>
66 <listitem><para><filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link>
67 </filename></para></listitem>
68 <listitem><para><filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link>
69 </filename></para></listitem>
70 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS
71 </link></filename></para></listitem>
72 <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS
73 </link></filename></para></listitem>
74 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS
75 </link></filename></para></listitem>
76 <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>
77 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename></para></listitem>
78 </itemizedlist>
79 </para>
80 </section>
81
82 <section id='ref-varlocality-config-local'>
83 <title>Local</title>
84
85 <para>
86 This section lists variables whose configuration context is the
87 local configuration through the <filename>local.conf</filename>
88 file.
89 <itemizedlist>
90 <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename>
91 </para></listitem>
92 <listitem><para><filename><link linkend='var-MACHINE'>MACHINE</link></filename>
93 </para></listitem>
94 <listitem><para><filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>
95 </para></listitem>
96 <listitem><para><filename><link linkend='var-BBFILES'>BBFILES</link></filename>
97 </para></listitem>
98 <listitem><para><filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES
99 </link></filename></para></listitem>
100 <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
101 </filename></para></listitem>
102 <listitem><para><filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
103 </filename></para></listitem>
104 <listitem><para><filename><link linkend='var-BBINCLUDELOGS'>BBINCLUDELOGS</link>
105 </filename></para></listitem>
106 <listitem><para><filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>
107 ENABLE_BINARY_LOCALE_GENERATION</link></filename></para></listitem>
108 </itemizedlist>
109 </para>
110 </section>
111 </section>
112
113 <section id='ref-varlocality-recipes'>
114 <title>Recipes</title>
115
116 <para>
117 The following subsections provide lists of variables whose context is
118 recipes: required, dependencies, path, and extra build information.
119 </para>
120
121 <section id='ref-varlocality-recipe-required'>
122 <title>Required</title>
123
124 <para>
125 This section lists variables that are required for recipes.
126 <itemizedlist>
127 <listitem><para><filename><link linkend='var-LICENSE'>LICENSE</link>
128 </filename></para></listitem>
129 <listitem><para><filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
130 </filename></para></listitem>
131 <listitem><para><filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> - used
132 in recipes that fetch local or remote files.
133 </para></listitem>
134 </itemizedlist>
135 </para>
136 </section>
137
138 <section id='ref-varlocality-recipe-dependencies'>
139 <title>Dependencies</title>
140
141 <para>
142 This section lists variables that define recipe dependencies.
143 <itemizedlist>
144 <listitem><para><filename><link linkend='var-DEPENDS'>DEPENDS</link>
145 </filename></para></listitem>
146 <listitem><para><filename><link linkend='var-RDEPENDS'>RDEPENDS</link>
147 </filename></para></listitem>
148 <listitem><para><filename><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link>
149 </filename></para></listitem>
150 <listitem><para><filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link>
151 </filename></para></listitem>
152 <listitem><para><filename><link linkend='var-RREPLACES'>RREPLACES</link>
153 </filename></para></listitem>
154 </itemizedlist>
155 </para>
156 </section>
157
158 <section id='ref-varlocality-recipe-paths'>
159 <title>Paths</title>
160
161 <para>
162 This section lists variables that define recipe paths.
163 <itemizedlist>
164 <listitem><para><filename><link linkend='var-WORKDIR'>WORKDIR</link>
165 </filename></para></listitem>
166 <listitem><para><filename><link linkend='var-S'>S</link>
167 </filename></para></listitem>
168 <listitem><para><filename><link linkend='var-FILES'>FILES</link>
169 </filename></para></listitem>
170 </itemizedlist>
171 </para>
172 </section>
173
174 <section id='ref-varlocality-recipe-build'>
175 <title>Extra Build Information</title>
176
177 <para>
178 This section lists variables that define extra build information for recipes.
179 <itemizedlist>
180 <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE
181 </link></filename></para></listitem>
182 <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link>
183 </filename></para></listitem>
184 <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link>
185 </filename></para></listitem>
186 <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
187 </filename></para></listitem>
188 <listitem><para><filename><link linkend='var-PACKAGECONFIG_CONFARGS'>PACKAGECONFIG_CONFARGS</link>
189 </filename></para></listitem>
190 <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
191 </para></listitem>
192 </itemizedlist>
193 </para>
194 </section>
195 </section>
196</chapter>
197<!--
198vim: expandtab tw=80 ts=4 spell spelllang=en_gb
199-->
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml
deleted file mode 100644
index 4899b2e599..0000000000
--- a/documentation/ref-manual/resources.xml
+++ /dev/null
@@ -1,298 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='resources'>
7<title>Contributions and Additional Information</title>
8
9<section id='resources-intro'>
10 <title>Introduction</title>
11 <para>
12 The Yocto Project team is happy for people to experiment with the
13 Yocto Project.
14 A number of places exist to find help if you run into difficulties
15 or find bugs.
16 This presents information about contributing and participating in
17 the Yocto Project.
18 </para>
19</section>
20
21<section id='resources-contributions'>
22 <title>Contributions</title>
23
24 <para>
25 The Yocto Project gladly accepts contributions.
26 You can submit changes to the project either by creating and sending
27 pull requests,
28 or by submitting patches through email.
29 For information on how to do both as well as information on how
30 to identify the maintainer for each area of code, see the
31 "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>"
32 section in the Yocto Project Development Tasks Manual.
33 </para>
34</section>
35
36<section id='resources-bugtracker'>
37 <title>Yocto Project Bugzilla</title>
38
39 <para>
40 The Yocto Project uses its own implementation of
41 <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink> to
42 track defects (bugs).
43 Implementations of Bugzilla work well for group development because
44 they track bugs and code changes, can be used to communicate changes
45 and problems with developers, can be used to submit and review patches,
46 and can be used to manage quality assurance.
47 </para>
48
49 <para>
50 Sometimes it is helpful to submit, investigate, or track a bug against
51 the Yocto Project itself (e.g. when discovering an issue with some
52 component of the build system that acts contrary to the documentation
53 or your expectations).
54 </para>
55
56 <para>
57 A general procedure and guidelines exist for when you use Bugzilla to
58 submit a bug.
59 For information on how to use Bugzilla to submit a bug against the
60 Yocto Project, see the following:
61 <itemizedlist>
62 <listitem><para>
63 The
64 "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
65 section in the Yocto Project Development Tasks Manual.
66 </para></listitem>
67 <listitem><para>
68 The Yocto Project
69 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>
70 </para></listitem>
71 </itemizedlist>
72 For information on Bugzilla in general, see
73 <ulink url='http://www.bugzilla.org/about/'></ulink>.
74 </para>
75</section>
76
77<section id='resources-mailinglist'>
78 <title>Mailing lists</title>
79
80 <para>
81 A number of mailing lists maintained by the Yocto Project exist
82 as well as related OpenEmbedded mailing lists for discussion,
83 patch submission and announcements.
84 To subscribe to one of the following mailing lists, click on the
85 appropriate URL in the following list and follow the instructions:
86 <itemizedlist>
87 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> -
88 General Yocto Project discussion mailing list. </para></listitem>
89 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'></ulink> -
90 Discussion mailing list about OpenEmbedded-Core (the core metadata).</para></listitem>
91 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'></ulink> -
92 Discussion mailing list about OpenEmbedded.</para></listitem>
93 <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
94 Discussion mailing list about the
95 <link linkend='bitbake-term'>BitBake</link>
96 build tool.</para></listitem>
97 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
98 Discussion mailing list about
99 <link linkend='poky'>Poky</link>.
100 </para></listitem>
101 <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> -
102 Mailing list to receive official Yocto Project release and milestone
103 announcements.</para></listitem>
104 </itemizedlist>
105 </para>
106 For more Yocto Project-related mailing lists, see the
107 <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
108</section>
109
110<section id='resources-irc'>
111 <title>Internet Relay Chat (IRC)</title>
112
113 <para>
114 Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
115 <itemizedlist>
116 <listitem><para><filename>#yocto</filename></para></listitem>
117 <listitem><para><filename>#poky</filename></para></listitem>
118 </itemizedlist>
119 </para>
120</section>
121
122<section id='resources-links-and-related-documentation'>
123 <title>Links and Related Documentation</title>
124
125 <para>
126 Here is a list of resources you might find helpful:
127 <itemizedlist>
128 <listitem><para>
129 <emphasis>
130 <ulink url='&YOCTO_HOME_URL;'>The Yocto Project website</ulink>:
131 </emphasis> The home site for the Yocto Project.
132 </para></listitem>
133 <listitem><para>
134 <emphasis>
135 <ulink url='&YOCTO_WIKI_URL;/wiki/Main_Page'>The Yocto Project Main Wiki Page</ulink>:
136 </emphasis>
137 The main wiki page for the Yocto Project.
138 This page contains information about project planning,
139 release engineering, QA &amp; automation, a reference
140 site map, and other resources related to the Yocto Project.
141 </para></listitem>
142 <listitem><para>
143 <emphasis>
144 <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:
145 </emphasis>
146 The build system used by the Yocto Project.
147 This project is the upstream, generic, embedded distribution
148 from which the Yocto Project derives its build system (Poky)
149 and to which it contributes.
150 </para></listitem>
151 <listitem><para>
152 <emphasis>
153 <ulink url='http://www.openembedded.org/wiki/BitBake'>
154 BitBake</ulink>:
155 </emphasis> The tool used to process metadata.
156 </para></listitem>
157 <listitem><para>
158 <emphasis>
159 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>:
160 </emphasis>
161 A comprehensive guide to the BitBake tool.
162 If you want information on BitBake, see this manual.
163 </para></listitem>
164 <listitem><para>
165 <emphasis>
166 <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>:
167 </emphasis>
168 This short document lets you experience building an image using
169 the Yocto Project without having to understand any concepts or
170 details.
171 </para></listitem>
172 <listitem><para>
173 <emphasis>
174 <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>:
175 </emphasis>
176 This manual provides overview and conceptual information
177 about the Yocto Project.
178 </para></listitem>
179 <listitem><para>
180 <emphasis>
181 <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>:
182 </emphasis>
183 This manual is a "how-to" guide that presents procedures
184 useful to both application and system developers who use the
185 Yocto Project.
186 </para></listitem>
187 <listitem><para>
188 <emphasis>
189 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
190 manual:</emphasis>
191 This guide provides information that lets you get going
192 with the standard or extensible SDK.
193 An SDK, with its cross-development toolchains, allows you
194 to develop projects inside or outside of the Yocto Project
195 environment.
196 </para></listitem>
197 <listitem><para>
198 <emphasis>
199 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:
200 </emphasis>
201 This guide defines the structure for BSP components.
202 Having a commonly understood structure encourages
203 standardization.
204 </para></listitem>
205 <listitem><para>
206 <emphasis>
207 <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>:
208 </emphasis>
209 This manual describes how to work with Linux Yocto kernels as
210 well as provides a bit of conceptual information on the
211 construction of the Yocto Linux kernel tree.
212 </para></listitem>
213 <listitem><para>
214 <emphasis>
215 <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:
216 </emphasis>
217 This manual provides reference material such as variable,
218 task, and class descriptions.
219 </para></listitem>
220 <listitem><para>
221 <emphasis>
222 <ulink url='&YOCTO_DOCS_MM_URL;'>Yocto Project Mega-Manual</ulink>:
223 </emphasis>
224 This manual is simply a single HTML file comprised of the
225 bulk of the Yocto Project manuals.
226 The Mega-Manual primarily exists as a vehicle by which you can
227 easily search for phrases and terms used in the Yocto Project
228 documentation set.
229 </para></listitem>
230 <listitem><para>
231 <emphasis>
232 <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>:
233 </emphasis>
234 This manual presents a set of common and generally useful
235 tracing and profiling schemes along with their applications
236 (as appropriate) to each tool.
237 </para></listitem>
238 <listitem><para>
239 <emphasis>
240 <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>:
241 </emphasis>
242 This manual introduces and describes how to set up and use
243 Toaster.
244 Toaster is an Application Programming Interface (API) and
245 web-based interface to the
246 <link linkend='build-system-term'>OpenEmbedded Build System</link>,
247 which uses BitBake, that reports build information.
248 </para></listitem>
249 <listitem><para>
250 <emphasis>
251 <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:
252 </emphasis>
253 A list of commonly asked questions and their answers.
254 </para></listitem>
255 <listitem><para>
256 <emphasis>Release Notes:</emphasis>
257 Features, updates and known issues for the current
258 release of the Yocto Project.
259 To access the Release Notes, go to the
260 <ulink url='&YOCTO_HOME_URL;/software-overview/downloads/'>Downloads</ulink>
261 page on the Yocto Project website and click on the
262 "RELEASE INFORMATION" link for the appropriate release.
263 </para></listitem>
264 <listitem><para>
265 <emphasis>
266 <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:
267 </emphasis>
268 The bug tracking application the Yocto Project uses.
269 If you find problems with the Yocto Project, you should report
270 them using this application.
271 </para></listitem>
272 <listitem><para>
273 <emphasis>
274 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla Configuration and Bug Tracking Wiki Page</ulink>:
275 </emphasis>
276 Information on how to get set up and use the Yocto Project
277 implementation of Bugzilla for logging and tracking Yocto
278 Project defects.
279 </para></listitem>
280 <listitem><para>
281 <emphasis>Internet Relay Chat (IRC):</emphasis>
282 Two IRC channels on freenode are available
283 for Yocto Project and Poky discussions: <filename>#yocto</filename> and
284 <filename>#poky</filename>, respectively.
285 </para></listitem>
286 <listitem><para>
287 <emphasis>
288 <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:
289 </emphasis>
290 An open-source machine emulator and virtualizer.
291 </para></listitem>
292 </itemizedlist>
293 </para>
294</section>
295</chapter>
296<!--
297vim: expandtab tw=80 ts=4
298-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-28 05:38:50 +0000