summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-classes.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/ref-manual/ref-classes.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-classes.xml')
-rw-r--r--documentation/ref-manual/ref-classes.xml3974
1 files changed, 0 insertions, 3974 deletions
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-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-04-18 21:46:15 +0000