summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-classes.xml
diff options
context:
space:
mode:
authorAdrian Dudau <adrian.dudau@enea.com>2014-06-26 14:38:37 +0200
committerAdrian Dudau <adrian.dudau@enea.com>2014-06-26 14:38:37 +0200
commit067445c1487c1a73e0ee8a9ae3e82d446406ab57 (patch)
treed47aa232ce1c82cf47aa348f20902937e073239a /documentation/ref-manual/ref-classes.xml
downloadyocto-docs-daisy.tar.gz
initial commit for Enea Linux 4.0daisy
Migrated from the internal git server on the daisy-enea branch Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>
Diffstat (limited to 'documentation/ref-manual/ref-classes.xml')
-rw-r--r--documentation/ref-manual/ref-classes.xml3300
1 files changed, 3300 insertions, 0 deletions
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
new file mode 100644
index 0000000..e7e9942
--- /dev/null
+++ b/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,3300 @@
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
5<chapter id='ref-classes'>
6<title>Classes</title>
7
8<para>
9 Class files are used to abstract common functionality and share it amongst
10 multiple recipe (<filename>.bb</filename>) files.
11 To use a class file, you simply make sure the recipe inherits the class.
12 In most cases, when a recipe inherits a class it is enough to enable its
13 features.
14 There are cases, however, where in the recipe you might need to set
15 variables or override some default behavior.
16</para>
17
18<para>
19 Any <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> usually
20 found in a recipe can also be placed in a class file.
21 Class files are identified by the extension <filename>.bbclass</filename>
22 and are usually placed in a <filename>classes/</filename> directory beneath
23 the <filename>meta*/</filename> directory found in the
24 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
25 Class files can also be pointed to by
26 <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
27 (e.g. <filename>build/</filename>) in the same way as
28 <filename>.conf</filename> files in the <filename>conf</filename> directory.
29 Class files are searched for in
30 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
31 using the same method by which <filename>.conf</filename> files are
32 searched.
33</para>
34
35<para>
36 This chapter discusses only the most useful and important classes.
37 Other classes do exist within the <filename>meta/classes</filename>
38 directory in the
39 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
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 </para>
55
56 <para>
57 By default, all recipes inherit the
58 <link linkend='ref-classes-base'><filename>base</filename></link> and
59 <link linkend='ref-classes-package'><filename>package</filename></link>
60 classes, which enable functionality
61 needed for recipes that produce executable output.
62 If your recipe, for example, only produces packages that contain
63 configuration files, media files, or scripts (e.g. Python and Perl),
64 then it should inherit the <filename>allarch</filename> class.
65 </para>
66</section>
67
68<section id='ref-classes-archiver'>
69 <title><filename>archiver.bbclass</filename></title>
70
71 <para>
72 The <filename>archiver</filename> class supports releasing
73 source code and other materials with the binaries.
74 </para>
75
76 <para>
77 For more details on the source archiver, see the
78 "<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>"
79 section in the Yocto Project Development Manual.
80 </para>
81</section>
82
83<section id='ref-classes-autotools'>
84 <title><filename>autotools.bbclass</filename></title>
85
86 <para>
87 The <filename>autotools</filename> class supports Autotooled
88 packages.
89 </para>
90
91 <para>
92 The <filename>autoconf</filename>, <filename>automake</filename>,
93 and <filename>libtool</filename> bring standardization.
94 This class defines a set of tasks (configure, compile etc.) that
95 work for all Autotooled packages.
96 It should usually be enough to define a few standard variables
97 and then simply <filename>inherit autotools</filename>.
98 This class can also work with software that emulates Autotools.
99 For more information, see the
100 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
101 section in the Yocto Project Development Manual.
102 </para>
103
104 <para>
105 It's useful to have some idea of how the tasks defined by this class work
106 and what they do behind the scenes.
107 <itemizedlist>
108 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> &dash; Regenerates the
109 configure script (using <filename>autoreconf</filename>) and then launches it
110 with a standard set of arguments used during cross-compilation.
111 You can pass additional parameters to <filename>configure</filename> through the
112 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
113 </para></listitem>
114 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> &dash; Runs <filename>make</filename> with
115 arguments that specify the compiler and linker.
116 You can pass additional arguments through
117 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
118 </para></listitem>
119 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> &dash; Runs <filename>make install</filename>
120 and passes in
121 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
122 as <filename>DESTDIR</filename>.
123 </para></listitem>
124 </itemizedlist>
125 </para>
126
127 <note>
128 It is planned for future Yocto Project releases that by default, the
129 <filename>autotools</filename> class supports out-of-tree builds
130 (<link linkend='var-B'><filename>B</filename></link> !=
131 <link linkend='var-S'><filename>S</filename></link>).
132 If your recipes do not support out-of-tree builds, you should
133 have them inherit the
134 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
135 class.
136 </note>
137</section>
138
139<section id='ref-classes-autotools-brokensep'>
140 <title><filename>autotools-brokensep.bbclass</filename></title>
141
142 <para>
143 The <filename>autotools-brokensep</filename> class behaves the same
144 as the
145 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
146 class but builds with
147 <link linkend='var-B'><filename>B</filename></link> ==
148 <link linkend='var-S'><filename>S</filename></link>.
149 This method is useful when out-of-tree build support is either not
150 present or is broken.
151 <note>
152 It is recommended that out-of-tree support be fixed and used
153 if at all possible.
154 </note>
155 </para>
156</section>
157
158<section id='ref-classes-base'>
159 <title><filename>base.bbclass</filename></title>
160
161 <para>
162 The <filename>base</filename> class is special in that every
163 <filename>.bb</filename> file implicitly inherits the class.
164 This class contains definitions for standard basic
165 tasks such as fetching, unpacking, configuring (empty by default),
166 compiling (runs any <filename>Makefile</filename> present), installing
167 (empty by default) and packaging (empty by default).
168 These classes are often overridden or extended by other classes
169 such as the
170 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
171 class or the
172 <link linkend='ref-classes-package'><filename>package</filename></link>
173 class.
174 The class also contains some commonly used functions such as
175 <filename>oe_runmake</filename>.
176 </para>
177</section>
178
179<section id='ref-classes-bin-package'>
180 <title><filename>bin_package.bbclass</filename></title>
181
182 <para>
183 The <filename>bin_package</filename> class is a
184 helper class for recipes that extract the contents of a binary package
185 (e.g. an RPM) and install those contents rather than building the
186 binary from source.
187 The binary package is extracted and new packages in the configured
188 output package format are created.
189 <note>
190 For RPMs and other packages that do not contain a subdirectory,
191 you should specify a "subdir" parameter.
192 Here is an example where <filename>${BP}</filename> is used so that
193 the files are extracted into the subdirectory expected by the
194 default value of
195 <link linkend='var-S'><filename>S</filename></link>:
196 <literallayout class='monospaced'>
197 SRC_URI = "http://example.com/downloads/somepackage.rpm;subdir=${BP}"
198 </literallayout>
199 </note>
200 </para>
201</section>
202
203<section id='ref-classes-binconfig'>
204 <title><filename>binconfig.bbclass</filename></title>
205
206 <para>
207 The <filename>binconfig</filename> class helps to correct paths in
208 shell scripts.
209 </para>
210
211 <para>
212 Before <filename>pkg-config</filename> had become widespread, libraries
213 shipped shell scripts to give information about the libraries and
214 include paths needed to build software (usually named
215 <filename>LIBNAME-config</filename>).
216 This class assists any recipe using such scripts.
217 </para>
218
219 <para>
220 During staging, the OpenEmbedded build system installs such scripts
221 into the <filename>sysroots/</filename> directory.
222 Inheriting this class results in all paths in these scripts being
223 changed to point into the <filename>sysroots/</filename> directory so
224 that all builds that use the script use the correct directories
225 for the cross compiling layout.
226 See the
227 <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
228 variable for more information.
229 </para>
230</section>
231
232<section id='ref-classes-blacklist'>
233 <title><filename>blacklist.bbclass</filename></title>
234
235 <para>
236 The <filename>blacklist</filename> class prevents
237 the OpenEmbedded build system from building specific recipes
238 (blacklists them).
239 To use this class, inherit the class globally and set
240 <link linkend='var-PNBLACKLIST'><filename>PNBLACKLIST</filename></link>
241 for each recipe you wish to blacklist.
242 Specify the <link linkend='var-PN'><filename>PN</filename></link>
243 value as a variable flag (varflag) and provide a reason, which is
244 reported, if the package is requested to be built as the value.
245 For example, if you want to blacklist a recipe called "exoticware",
246 you add the following to your <filename>local.conf</filename>
247 or distribution configuration:
248 <literallayout class='monospaced'>
249 INHERIT += "blacklist"
250 PNBLACKLIST[exoticware] = "Not supported by our organization."
251 </literallayout>
252 </para>
253</section>
254
255<section id='ref-classes-boot-directdisk'>
256 <title><filename>boot-directdisk.bbclass</filename></title>
257
258 <para>
259 The <filename>boot-directdisk</filename> class
260 creates an image that can be placed directly onto a hard disk using
261 <filename>dd</filename> and then booted.
262 The image uses SYSLINUX.
263 </para>
264
265 <para>
266 The end result is a 512 boot sector populated with a
267 Master Boot Record (MBR) and partition table followed by an MSDOS
268 FAT16 partition containing SYSLINUX and a Linux kernel completed by
269 the <filename>ext2</filename> and <filename>ext3</filename>
270 root filesystems.
271 </para>
272</section>
273
274<section id='ref-classes-bootimg'>
275 <title><filename>bootimg.bbclass</filename></title>
276
277 <para>
278 The <filename>bootimg</filename> class creates a bootable
279 image using SYSLINUX, your kernel, and an optional initial RAM disk
280 (<filename>initrd</filename>).
281 </para>
282
283 <para>
284 When you use this class, two things happen:
285 <itemizedlist>
286 <listitem><para>
287 A <filename>.hddimg</filename> file is created.
288 This file is an MSDOS filesystem that contains SYSLINUX,
289 a kernel, an <filename>initrd</filename>, and a root filesystem
290 image.
291 All three of these can be written to hard drives directly and
292 also booted on a USB flash disks using <filename>dd</filename>.
293 </para></listitem>
294 <listitem><para>
295 A CD <filename>.iso</filename> image is created.
296 When this file is booted, the <filename>initrd</filename>
297 boots and processes the label selected in SYSLINUX.
298 Actions based on the label are then performed (e.g. installing
299 to a hard drive).</para></listitem>
300 </itemizedlist>
301 </para>
302
303 <para>
304 The <filename>bootimg</filename> class supports the
305 <link linkend='var-INITRD'><filename>INITRD</filename></link>,
306 <link linkend='var-NOISO'><filename>NOISO</filename></link>,
307 <link linkend='var-NOHDD'><filename>NOHDD</filename></link>, and
308 <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>
309 variables.
310 </para>
311</section>
312
313<section id='ref-classes-bugzilla'>
314 <title><filename>bugzilla.bbclass</filename></title>
315
316 <para>
317 The <filename>bugzilla</filename> class supports setting up an
318 instance of Bugzilla in which you can automatically files bug reports
319 in response to build failures.
320 For this class to work, you need to enable the XML-RPC interface in
321 the instance of Bugzilla.
322 </para>
323</section>
324
325<section id='ref-classes-buildhistory'>
326 <title><filename>buildhistory.bbclass</filename></title>
327
328 <para>
329 The <filename>buildhistory</filename> class records a
330 history of build output metadata, which can be used to detect possible
331 regressions as well as used for analysis of the build output.
332 For more information on using Build History, see the
333 "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
334 section.
335 </para>
336</section>
337
338<section id='ref-classes-buildstats'>
339 <title><filename>buildstats.bbclass</filename></title>
340
341 <para>
342 The <filename>buildstats</filename> class records
343 performance statistics about each task executed during the build
344 (e.g. elapsed time, CPU usage, and I/O usage).
345 </para>
346
347 <para>
348 When you use this class, the output goes into the
349 <link linkend='var-BUILDSTATS_BASE'><filename>BUILDSTATS_BASE</filename></link>
350 directory, which defaults to <filename>${TMPDIR}/buildstats/</filename>.
351 You can analyze the elapsed time using
352 <filename>scripts/pybootchartgui/pybootchartgui.py</filename>, which
353 produces a cascading chart of the entire build process and can be
354 useful for highlighting bottlenecks.
355 </para>
356
357 <para>
358 Collecting build statistics is enabled by default through the
359 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
360 variable from your <filename>local.conf</filename> file.
361 Consequently, you do not have to do anything to enable the class.
362 However, if you want to disable the class, simply remove "buildstats"
363 from the <filename>USER_CLASSES</filename> list.
364 </para>
365</section>
366
367<section id='ref-classes-ccache'>
368 <title><filename>ccache.bbclass</filename></title>
369
370 <para>
371 The <filename>ccache</filename> class enables the
372 <ulink url='http://ccache.samba.org/'>C/C++ Compiler Cache</ulink>
373 for the build.
374 This class is used to give a minor performance boost during the build.
375 However, using the class can lead to unexpected side-effects.
376 Thus, it is recommended that you do not use this class.
377 See <ulink url='http://ccache.samba.org/'></ulink> for information on
378 the C/C++ Compiler Cache.
379 </para>
380</section>
381
382<section id='ref-classes-chrpath'>
383 <title><filename>chrpath.bbclass</filename></title>
384
385 <para>
386 The <filename>chrpath</filename> class
387 is a wrapper around the "chrpath" utility, which is used during the
388 build process for <filename>nativesdk</filename>,
389 <filename>cross</filename>, and
390 <filename>cross-canadian</filename> recipes to change
391 <filename>RPATH</filename> records within binaries in order to make
392 them relocatable.
393 </para>
394</section>
395
396<section id='ref-classes-clutter'>
397 <title><filename>clutter.bbclass</filename></title>
398
399 <para>
400 The <filename>clutter</filename> class consolidates the
401 major and minor version naming and other common items used by Clutter
402 and related recipes.
403 <note>
404 Unlike some other classes related to specific libraries, recipes
405 building other software that uses Clutter do not need to
406 inherit this class unless they use the same recipe versioning
407 scheme that the Clutter and related recipes do.
408 </note>
409 </para>
410</section>
411
412<section id='ref-classes-cmake'>
413 <title><filename>cmake.bbclass</filename></title>
414
415 <para>
416 The <filename>cmake</filename> class allows for
417 recipes that need to build software using the CMake build system.
418 You can use the
419 <link linkend='var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></link>
420 variable to specify additional configuration options to be passed on
421 the <filename>cmake</filename> command line.
422 </para>
423</section>
424
425<section id='ref-classes-cml1'>
426 <title><filename>cml1.bbclass</filename></title>
427
428 <para>
429 The <filename>cml1</filename> class provides basic support for the
430 Linux kernel style build configuration system.
431 </para>
432</section>
433
434<section id='ref-classes-copyleft_compliance'>
435 <title><filename>copyleft_compliance.bbclass</filename></title>
436
437 <para>
438 The <filename>copyleft_compliance</filename> class
439 preserves source code for the purposes of license compliance.
440 This class is an alternative to the <filename>archiver</filename>
441 class and is still used by some users even though it has been
442 deprecated in favor of the
443 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
444 class.
445 </para>
446</section>
447
448<section id='ref-classes-core-image'>
449 <title><filename>core-image.bbclass</filename></title>
450
451 <para>
452 The <filename>core-image</filename> class
453 provides common definitions for the
454 <filename>core-image-*</filename> image recipes, such as support for
455 additional
456 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
457 </para>
458</section>
459
460<section id='ref-classes-cpan'>
461 <title><filename>cpan.bbclass</filename></title>
462
463 <para>
464 The <filename>cpan</filename> class supports Perl modules.
465 </para>
466
467 <para>
468 Recipes for Perl modules are simple.
469 These recipes usually only need to point to the source's archive and
470 then inherit the proper class file.
471 Building is split into two methods depending on which method the module
472 authors used.
473 <itemizedlist>
474 <listitem><para>Modules that use old
475 <filename>Makefile.PL</filename>-based build system require
476 <filename>cpan.bbclass</filename> in their recipes.
477 </para></listitem>
478 <listitem><para>Modules that use
479 <filename>Build.PL</filename>-based build system require
480 using <filename>cpan_build.bbclass</filename> in their recipes.
481 </para></listitem>
482 </itemizedlist>
483 </para>
484</section>
485
486<section id='ref-classes-cross'>
487 <title><filename>cross.bbclass</filename></title>
488
489 <para>
490 The <filename>cross</filename> class provides support for the recipes
491 that build the cross-compilation tools.
492 </para>
493</section>
494
495<section id='ref-classes-cross-canadian'>
496 <title><filename>cross-canadian.bbclass</filename></title>
497
498 <para>
499 The <filename>cross-canadian</filename> class
500 provides support for the recipes that build the Canadian
501 Cross-compilation tools for SDKs.
502 See the
503 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
504 section for more discussion on these cross-compilation tools.
505 </para>
506</section>
507
508<section id='ref-classes-crosssdk'>
509 <title><filename>crosssdk.bbclass</filename></title>
510
511 <para>
512 The <filename>crosssdk</filename> class
513 provides support for the recipes that build the cross-compilation
514 tools used for building SDKs.
515 See the
516 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
517 section for more discussion on these cross-compilation tools.
518 </para>
519</section>
520
521<section id='ref-classes-debian'>
522 <title><filename>debian.bbclass</filename></title>
523
524 <para>
525 The <filename>debian</filename> class renames output packages so that
526 they follow the Debian naming policy (i.e. <filename>eglibc</filename>
527 becomes <filename>libc6</filename> and <filename>eglibc-devel</filename>
528 becomes <filename>libc6-dev</filename>.)
529 Renaming includes the library name and version as part of the package
530 name.
531 </para>
532
533 <para>
534 If a recipe creates packages for multiple libraries
535 (shared object files of <filename>.so</filename> type), use the
536 <link linkend='var-LEAD_SONAME'><filename>LEAD_SONAME</filename></link>
537 variable in the recipe to specify the library on which to apply the
538 naming scheme.
539 </para>
540</section>
541
542<section id='ref-classes-deploy'>
543 <title><filename>deploy.bbclass</filename></title>
544
545 <para>
546 The <filename>deploy</filename> class handles deploying files
547 to the
548 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
549 directory.
550 The main function of this class is to allow the deploy step to be
551 accelerated by shared state.
552 Recipes that inherit this class should define their own
553 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
554 function to copy the files to be deployed to
555 <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>,
556 and use <filename>addtask</filename> to add the task at the appropriate
557 place, which is usually after
558 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
559 or
560 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
561 The class then takes care of staging the files from
562 <filename>DEPLOYDIR</filename> to
563 <filename>DEPLOY_DIR_IMAGE</filename>.
564 </para>
565</section>
566
567<section id='ref-classes-devshell'>
568 <title><filename>devshell.bbclass</filename></title>
569
570 <para>
571 The <filename>devshell</filename> class adds the
572 <filename>do_devshell</filename> task.
573 Distribution policy dictates whether to include this class.
574 See the
575 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
576 in the Yocto Project Development Manual for more information about
577 using <filename>devshell</filename>.
578 </para>
579</section>
580
581<section id='ref-classes-distro_features_check'>
582 <title><filename>distro_features_check.bbclass</filename></title>
583
584 <para>
585 The <filename>distro_features_check</filename> class
586 allows individual recipes to check for required and conflicting
587 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
588 </para>
589
590 <para>
591 This class provides support for the
592 <link linkend='var-REQUIRED_DISTRO_FEATURES'><filename>REQUIRED_DISTRO_FEATURES</filename></link>
593 and
594 <link linkend='var-CONFLICT_DISTRO_FEATURES'><filename>CONFLICT_DISTRO_FEATURES</filename></link>
595 variables.
596 If any conditions specified in the recipe using the above variables are
597 not met, the recipe will be skipped.
598 </para>
599</section>
600
601<section id='ref-classes-distrodata'>
602 <title><filename>distrodata.bbclass</filename></title>
603
604 <para>
605 The <filename>distrodata</filename> class
606 provides for automatic checking for upstream recipe updates.
607 The class creates a comma-separated value (CSV) spreadsheet that
608 contains information about the recipes.
609 The information provides the <filename>do_distrodata</filename> and
610 <filename>do_distro_check</filename> tasks, which do upstream checking
611 and also verify if a package is used in multiple major distributions.
612 </para>
613
614 <para>
615 The class is not included by default.
616 To use it, you must include the following files and set the
617 <link linkend='var-INHERIT'><filename>INHERIT</filename></link>
618 variable:
619 <literallayout class='monospaced'>
620 include conf/distro/include/distro_alias.inc
621 include conf/distro/include/recipe_color.inc
622 include conf/distro/include/maintainers.inc
623 include conf/distro/include/upstream_tracking.inc
624 include conf/distro/include/package_regex.inc
625 INHERIT+= "distrodata"
626 </literallayout>
627 </para>
628</section>
629
630<section id='ref-classes-distutils'>
631 <title><filename>distutils.bbclass</filename></title>
632
633 <para>
634 The <filename>distutils</filename> class supports recipes for Python
635 version 2.x extensions, which are simple.
636 These recipes usually only need to point to the source's archive and
637 then inherit the proper class.
638 Building is split into two methods depending on which method the
639 module authors used.
640 <itemizedlist>
641 <listitem><para>Extensions that use an Autotools-based build system
642 require Autotools and
643 <filename>distutils</filename>-based classes in their recipes.
644 </para></listitem>
645 <listitem><para>Extensions that use build systems based on
646 <filename>distutils</filename> require
647 the <filename>distutils</filename> class in their recipes.
648 </para></listitem>
649 <listitem><para>Extensions that use build systems based on
650 <filename>setuptools</filename> require the
651 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
652 class in their recipes.
653 </para></listitem>
654 </itemizedlist>
655 </para>
656</section>
657
658<section id='ref-classes-distutils3'>
659 <title><filename>distutils3.bbclass</filename></title>
660
661 <para>
662 The <filename>distutils3</filename> class supports recipes for Python
663 version 3.x extensions, which are simple.
664 These recipes usually only need to point to the source's archive and
665 then inherit the proper class.
666 Building is split into two methods depending on which method the
667 module authors used.
668 <itemizedlist>
669 <listitem><para>Extensions that use an Autotools-based build system
670 require Autotools and
671 <filename>distutils</filename>-based classes in their recipes.
672 </para></listitem>
673 <listitem><para>Extensions that use
674 <filename>distutils</filename>-based build systems require
675 the <filename>distutils</filename> class in their recipes.
676 </para></listitem>
677 <listitem><para>Extensions that use build systems based on
678 <filename>setuptools3</filename> require the
679 <link linkend='ref-classes-setuptools'><filename>setuptools3</filename></link>
680 class in their recipes.
681 </para></listitem>
682 </itemizedlist>
683 </para>
684</section>
685
686<section id='ref-classes-externalsrc'>
687 <title><filename>externalsrc.bbclass</filename></title>
688
689 <para>
690 The <filename>externalsrc</filename> class supports building software
691 from source code that is external to the OpenEmbedded build system.
692 Building software from an external source tree means that the build
693 system's normal fetch, unpack, and patch process is not used.
694 </para>
695
696 <para>
697 By default, the OpenEmbedded build system uses the
698 <link linkend='var-S'><filename>S</filename></link> and
699 <link linkend='var-B'><filename>B</filename></link> variables to
700 locate unpacked recipe source code and to build it, respectively.
701 When your recipe inherits the <filename>externalsrc</filename> class,
702 you use the
703 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
704 and
705 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
706 variables to ultimately define <filename>S</filename> and
707 <filename>B</filename>.
708 </para>
709
710 <para>
711 By default, this class expects the source code to support recipe builds
712 that use the <link linkend='var-B'><filename>B</filename></link>
713 variable to point to the directory in which the OpenEmbedded build
714 system places the generated objects built from the recipes.
715 By default, the <filename>B</filename> directory is set to the
716 following, which is separate from the source directory
717 (<filename>S</filename>):
718 <literallayout class='monospaced'>
719 ${WORKDIR}/${BPN}/{PV}/
720 </literallayout>
721 See these variables for more information:
722 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
723 <link linkend='var-BPN'><filename>BPN</filename></link>, and
724 <link linkend='var-PV'><filename>PV</filename></link>,
725 </para>
726
727 <para>
728 For more information on the
729 <filename>externalsrc</filename> class, see the comments in
730 <filename>meta/classes/externalsrc.bbclass</filename> in the
731 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
732 For information on how to use the <filename>externalsrc</filename>
733 class, see the
734 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
735 section in the Yocto Project Development Manual.
736 </para>
737</section>
738
739<section id='ref-classes-extrausers'>
740 <title><filename>extrausers.bbclass</filename></title>
741
742 <para>
743 The <filename>extrausers</filename> class allows
744 additional user and group configuration to be applied at the image
745 level.
746 Inheriting this class either globally or from an image recipe allows
747 additional user and group operations to be performed using the
748 <link linkend='var-EXTRA_USERS_PARAMS'><filename>EXTRA_USERS_PARAMS</filename></link>
749 variable.
750 <note>
751 The user and group operations added using the
752 <filename>extrausers</filename> class are not tied to a specific
753 recipe outside of the recipe for the image.
754 Thus, the operations can be performed across the image as a whole.
755 Use the
756 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
757 class to add user and group configuration to a specific recipe.
758 </note>
759 Here is an example that uses this class in an image recipe:
760 <literallayout class='monospaced'>
761 inherit extrausers
762 EXTRA_USERS_PARAMS = "\
763 useradd -p '' tester; \
764 groupadd developers; \
765 userdel nobody; \
766 groupdel -g video; \
767 groupmod -g 1020 developers; \
768 usermod -s /bin/sh tester; \
769 "
770 </literallayout>
771 Here is an example that adds two users named "tester-jim" and
772 "tester-sue" and assigns passwords:
773 <literallayout class='monospaced'>
774 inherit extrausers
775 EXTRA_USERS_PARAMS = "\
776 useradd -P tester01 tester-jim; \
777 useradd -P tester01 tester-sue; \
778 "
779 </literallayout>
780 Finally, here is an example that sets the root password to
781 "1876*18":
782 <literallayout class='monospaced'>
783 inherit extrausers
784 EXTRA_USERS_PARAMS = "\
785 useradd -P 1876*18 root; \
786 "
787 </literallayout>
788 </para>
789</section>
790
791<section id='ref-classes-fontcache'>
792 <title><filename>fontcache.bbclass</filename></title>
793
794 <para>
795 The <filename>fontcache</filename> class generates the
796 proper post-install and post-remove (postinst and postrm)
797 scriptlets for font packages.
798 These scriptlets call <filename>fc-cache</filename> (part of
799 <filename>Fontconfig</filename>) to add the fonts to the font
800 information cache.
801 Since the cache files are architecture-specific,
802 <filename>fc-cache</filename> runs using QEMU if the postinst
803 scriptlets need to be run on the build host during image creation.
804 </para>
805
806 <para>
807 If the fonts being installed are in packages other than the main
808 package, set
809 <link linkend='var-FONT_PACKAGES'><filename>FONT_PACKAGES</filename></link>
810 to specify the packages containing the fonts.
811 </para>
812</section>
813
814<section id='ref-classes-gconf'>
815 <title><filename>gconf.bbclass</filename></title>
816
817 <para>
818 The <filename>gconf</filename> class provides common
819 functionality for recipes that need to install GConf schemas.
820 The schemas will be put into a separate package
821 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-gconf</filename>)
822 that is created automatically when this class is inherited.
823 This package uses the appropriate post-install and post-remove
824 (postinst/postrm) scriptlets to register and unregister the schemas
825 in the target image.
826 </para>
827</section>
828
829<section id='ref-classes-gettext'>
830 <title><filename>gettext.bbclass</filename></title>
831
832 <para>
833 The <filename>gettext</filename> class provides support for
834 building software that uses the GNU <filename>gettext</filename>
835 internationalization and localization system.
836 All recipes building software that use
837 <filename>gettext</filename> should inherit this class.
838 </para>
839</section>
840
841<section id='ref-classes-gnome'>
842 <title><filename>gnome.bbclass</filename></title>
843
844 <para>
845 The <filename>gnome</filename> class supports recipes that
846 build software from the GNOME stack.
847 This class inherits the
848 <link linkend='ref-classes-gnomebase'><filename>gnomebase</filename></link>,
849 <link linkend='ref-classes-gtk-icon-cache'><filename>gtk-icon-cache</filename></link>,
850 <link linkend='ref-classes-gconf'><filename>gconf</filename></link> and
851 <link linkend='ref-classes-mime'><filename>mime</filename></link> classes.
852 The class also disables GObject introspection where applicable.
853 </para>
854</section>
855
856<section id='ref-classes-gnomebase'>
857 <title><filename>gnomebase.bbclass</filename></title>
858
859 <para>
860 The <filename>gnomebase</filename> class is the base
861 class for recipes that build software from the GNOME stack.
862 This class sets
863 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> to
864 download the source from the GNOME mirrors as well as extending
865 <link linkend='var-FILES'><filename>FILES</filename></link>
866 with the typical GNOME installation paths.
867 </para>
868</section>
869
870<section id='ref-classes-grub-efi'>
871 <title><filename>grub-efi.bbclass</filename></title>
872
873 <para>
874 The <filename>grub-efi</filename>
875 class provides <filename>grub-efi</filename>-specific functions for
876 building bootable images.
877 </para>
878
879 <para>
880 This class supports several variables:
881 <itemizedlist>
882 <listitem><para>
883 <link linkend='var-INITRD'><filename>INITRD</filename></link>:
884 Indicates a filesystem image to use as an initrd (optional).
885 </para></listitem>
886 <listitem><para>
887 <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
888 Indicates a filesystem image to include as the root filesystem
889 (optional).</para></listitem>
890 <listitem><para>
891 <link linkend='var-GRUB_GFXSERIAL'><filename>GRUB_GFXSERIAL</filename></link>:
892 Set this to "1" to have graphics and serial in the boot menu.
893 </para></listitem>
894 <listitem><para>
895 <link linkend='var-LABELS'><filename>LABELS</filename></link>:
896 A list of targets for the automatic configuration.
897 </para></listitem>
898 <listitem><para>
899 <link linkend='var-APPEND'><filename>APPEND</filename></link>:
900 An override list of append strings for each
901 <filename>LABEL</filename>.
902 </para></listitem>
903 <listitem><para>
904 <link linkend='var-GRUB_OPTS'><filename>GRUB_OPTS</filename></link>:
905 Additional options to add to the configuration (optional).
906 Options are delimited using semi-colon characters
907 (<filename>;</filename>).</para></listitem>
908 <listitem><para>
909 <link linkend='var-GRUB_TIMEOUT'><filename>GRUB_TIMEOUT</filename></link>:
910 Timeout before executing the default <filename>LABEL</filename>
911 (optional).
912 </para></listitem>
913 </itemizedlist>
914 </para>
915</section>
916
917<section id='ref-classes-gsettings'>
918 <title><filename>gsettings.bbclass</filename></title>
919
920 <para>
921 The <filename>gsettings</filename> class
922 provides common functionality for recipes that need to install
923 GSettings (glib) schemas.
924 The schemas are assumed to be part of the main package.
925 Appropriate post-install and post-remove (postinst/postrm)
926 scriptlets are added to register and unregister the schemas in the
927 target image.
928 </para>
929</section>
930
931<section id='ref-classes-gtk-doc'>
932 <title><filename>gtk-doc.bbclass</filename></title>
933
934 <para>
935 The <filename>gtk-doc</filename> class
936 is a helper class to pull in the appropriate
937 <filename>gtk-doc</filename> dependencies and disable
938 <filename>gtk-doc</filename>.
939 </para>
940</section>
941
942<section id='ref-classes-gtk-icon-cache'>
943 <title><filename>gtk-icon-cache.bbclass</filename></title>
944
945 <para>
946 The <filename>gtk-icon-cache</filename> class
947 generates the proper post-install and post-remove (postinst/postrm)
948 scriptlets for packages that use GTK+ and install icons.
949 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
950 the fonts to GTK+'s icon cache.
951 Since the cache files are architecture-specific,
952 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
953 postinst scriptlets need to be run on the build host during image
954 creation.
955 </para>
956</section>
957
958<section id='ref-classes-gtk-immodules-cache'>
959 <title><filename>gtk-immodules-cache.bbclass</filename></title>
960
961 <para>
962 The <filename>gtk-immodules-cache</filename> class
963 generates the proper post-install and post-remove (postinst/postrm)
964 scriptlets for packages that install GTK+ input method modules for
965 virtual keyboards.
966 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
967 the input method modules to the cache.
968 Since the cache files are architecture-specific,
969 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
970 postinst scriptlets need to be run on the build host during image
971 creation.
972 </para>
973
974 <para>
975 If the input method modules being installed are in packages other than
976 the main package, set
977 <link linkend='var-GTKIMMODULES_PACKAGES'><filename>GTKIMMODULES_PACKAGES</filename></link>
978 to specify the packages containing the modules.
979 </para>
980</section>
981
982<section id='ref-classes-gzipnative'>
983 <title><filename>gzipnative.bbclass</filename></title>
984
985 <para>
986 The <filename>gzipnative</filename>
987 class enables the use of native versions of <filename>gzip</filename>
988 and <filename>pigz</filename> rather than the versions of these tools
989 from the build host.
990 </para>
991</section>
992
993<section id='ref-classes-icecc'>
994 <title><filename>icecc.bbclass</filename></title>
995
996 <para>
997 The <filename>icecc</filename> class supports
998 <ulink url='https://github.com/icecc/icecream'>Icecream</ulink>, which
999 facilitates taking compile jobs and distributing them among remote
1000 machines.
1001 </para>
1002
1003 <para>
1004 The class stages directories with symlinks from <filename>gcc</filename>
1005 and <filename>g++</filename> to <filename>icecc</filename>, for both
1006 native and cross compilers.
1007 Depending on each configure or compile, the OpenEmbedded build system
1008 adds the directories at the head of the <filename>PATH</filename> list
1009 and then sets the <filename>ICECC_CXX</filename> and
1010 <filename>ICEC_CC</filename> variables, which are the paths to the
1011 <filename>g++</filename> and <filename>gcc</filename> compilers,
1012 respectively.
1013 </para>
1014
1015 <para>
1016 For the cross compiler, the class creates a <filename>tar.gz</filename>
1017 file that contains the Yocto Project toolchain and sets
1018 <filename>ICECC_VERSION</filename>, which is the version of the
1019 cross-compiler used in the cross-development toolchain, accordingly.
1020 </para>
1021
1022 <para>
1023 The class handles all three different compile stages
1024 (i.e native ,cross-kernel and target) and creates the necessary
1025 environment <filename>tar.gz</filename> file to be used by the remote
1026 machines.
1027 The class also supports SDK generation.
1028 </para>
1029
1030 <para>
1031 If <link linkend='var-ICECC_PATH'><filename>ICECC_PATH</filename></link>
1032 is not set in your <filename>local.conf</filename> file, then the
1033 class tries to locate the <filename>icecc</filename> binary
1034 using <filename>which</filename>.
1035
1036 If
1037 <link linkend='var-ICECC_ENV_EXEC'><filename>ICECC_ENV_EXEC</filename></link>
1038 is set in your <filename>local.conf</filename> file, the variable should
1039 point to the <filename>icecc-create-env</filename> script
1040 provided by the user.
1041 If you do not point to a user-provided script, the build system
1042 uses the default script provided by the recipe
1043 <filename>icecc-create-env-native.bb</filename>.
1044 <note>
1045 This script is a modified version and not the one that comes with
1046 <filename>icecc</filename>.
1047 </note>
1048 </para>
1049
1050 <para>
1051 If you do not want the Icecream distributed compile support to apply
1052 to specific recipes or classes, you can effectively "blacklist" them
1053 by listing the recipes and classes using the
1054 <link linkend='var-ICECC_USER_PACKAGE_BL'><filename>ICECC_USER_PACKAGE_BL</filename></link>
1055 and
1056 <link linkend='var-ICECC_USER_CLASS_BL'><filename>ICECC_USER_CLASS_BL</filename></link>,
1057 variables, respectively, in your <filename>local.conf</filename> file.
1058 Doing so causes the OpenEmbedded build system to handle these
1059 compilations locally.
1060 </para>
1061
1062 <para>
1063 Additionally, you can list recipes using the
1064 <link linkend='var-ICECC_USER_PACKAGE_WL'><filename>ICECC_USER_PACKAGE_WL</filename></link>
1065 variable in your <filename>local.conf</filename> file to force
1066 <filename>icecc</filename> to be enabled for recipes using an empty
1067 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
1068 variable.
1069 </para>
1070
1071 <para>
1072 Inheriting the <filename>icecc</filename> class changes all sstate
1073 signatures.
1074 Consequently, if a development team has a dedicated build system
1075 that populates
1076 <link linkend='var-SSTATE_MIRRORS'><filename>STATE_MIRRORS</filename></link>
1077 and they want to reuse sstate from
1078 <filename>STATE_MIRRORS</filename>, then all developers and the
1079 build system need to either inherit the <filename>icecc</filename>
1080 class or nobody should.
1081 </para>
1082
1083 <para>
1084 At the distribution level, you can inherit the
1085 <filename>icecc</filename> class to be sure that all builders start
1086 with the same sstate signatures.
1087 After inheriting the class, you can then disable the feature by setting
1088 the
1089 <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link>
1090 variable to "1" as follows:
1091 <literallayout class='monospaced'>
1092 INHERIT_DISTRO += "icecc"
1093 ICECC_DISABLED ??= "1"
1094 </literallayout>
1095 This practice makes sure everyone is using the same signatures but also
1096 requires individuals that do want to use Icecream to enable the feature
1097 individually as follows in your <filename>local.conf</filename> file:
1098 <literallayout class='monospaced'>
1099 ICECC_DISABLED = ""
1100 </literallayout>
1101 </para>
1102</section>
1103
1104<section id='ref-classes-image'>
1105 <title><filename>image.bbclass</filename></title>
1106
1107 <para>
1108 The <filename>image</filename> class helps support creating images
1109 in different formats.
1110 First, the root filesystem is created from packages using
1111 one of the <filename>rootfs*.bbclass</filename>
1112 files (depending on the package format used) and then one or more image
1113 files are created.
1114 <itemizedlist>
1115 <listitem><para>The
1116 <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
1117 variable controls the types of images to generate.
1118 </para></listitem>
1119 <listitem><para>The
1120 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
1121 variable controls the list of packages to install into the
1122 image.</para></listitem>
1123 </itemizedlist>
1124 For information on customizing images, see the
1125 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
1126 section in the Yocto Project Development Manual.
1127 For information on how images are created, see the
1128 "<link linkend='images-dev-environment'>Images</link>" section elsewhere
1129 in this manual.
1130 </para>
1131</section>
1132
1133<section id='ref-classes-image_types'>
1134 <title><filename>image_types.bbclass</filename></title>
1135
1136 <para>
1137 The <filename>image_types</filename> class defines all of
1138 the standard image output types that you can enable through the
1139 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1140 variable.
1141 You can use this class as a reference on how to add support for custom
1142 image output types.
1143 </para>
1144
1145 <para>
1146 By default, this class is enabled through the
1147 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
1148 variable in
1149 <link linkend='ref-classes-image'><filename>image.bbclass</filename></link>.
1150 If you define your own image types using a custom BitBake class and
1151 then use <filename>IMAGE_CLASSES</filename> to enable it, the custom
1152 class must either inherit <filename>image_types</filename> or
1153 <filename>image_types</filename> must also appear in
1154 <filename>IMAGE_CLASSES</filename>.
1155 </para>
1156</section>
1157
1158<section id='ref-classes-image_types_uboot'>
1159 <title><filename>image_types_uboot.bbclass</filename></title>
1160
1161 <para>
1162 The <filename>image_types_uboot</filename> class
1163 defines additional image types specifically for the U-Boot bootloader.
1164 </para>
1165</section>
1166
1167<section id='ref-classes-image-live'>
1168 <title><filename>image-live.bbclass</filename></title>
1169
1170 <para>
1171 The <filename>image-live</filename> class supports building "live"
1172 images.
1173 </para>
1174
1175 <para>
1176 Normally, you do not use this class directly.
1177 Instead, you add "live" to
1178 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
1179 For example, if you were building an ISO image, you would add "live"
1180 to <filename>IMAGE_FSTYPES</filename>, set the
1181 <link linkend='var-NOISO'><filename>NOISO</filename></link> variable to
1182 "0" and the build system would use the <filename>image-live</filename>
1183 class to build the ISO image.
1184 </para>
1185</section>
1186
1187<section id='ref-classes-image-mklibs'>
1188 <title><filename>image-mklibs.bbclass</filename></title>
1189
1190 <para>
1191 The <filename>image-mklibs</filename> class
1192 enables the use of the <filename>mklibs</filename> utility during the
1193 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1194 task, which optimizes the size of
1195 libraries contained in the image.
1196 </para>
1197
1198 <para>
1199 By default, the class is enabled in the
1200 <filename>local.conf.template</filename> using the
1201 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1202 variable as follows:
1203 <literallayout class='monospaced'>
1204 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1205 </literallayout>
1206 </para>
1207</section>
1208
1209<section id='ref-classes-image-prelink'>
1210 <title><filename>image-prelink.bbclass</filename></title>
1211
1212 <para>
1213 The <filename>image-prelink</filename> class
1214 enables the use of the <filename>prelink</filename> utility during
1215 the
1216 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1217 task, which optimizes the dynamic
1218 linking of shared libraries to reduce executable startup time.
1219 </para>
1220
1221 <para>
1222 By default, the class is enabled in the
1223 <filename>local.conf.template</filename> using the
1224 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1225 variable as follows:
1226 <literallayout class='monospaced'>
1227 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1228 </literallayout>
1229 </para>
1230</section>
1231
1232<section id='ref-classes-image-swab'>
1233 <title><filename>image-swab.bbclass</filename></title>
1234
1235 <para>
1236 The <filename>image-swab</filename> class enables the
1237 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/swabber'>Swabber</ulink>
1238 tool in order to detect and log accesses to the host system during
1239 the OpenEmbedded build process.
1240 <note>
1241 This class is currently unmaintained.
1242 </note>
1243 </para>
1244</section>
1245
1246<section id='ref-classes-image-vmdk'>
1247 <title><filename>image-vmdk.bbclass</filename></title>
1248
1249 <para>
1250 The <filename>image-vmdk</filename> class supports building VMware
1251 VMDK images.
1252 Normally, you do not use this class directly.
1253 Instead, you add "vmdk" to
1254 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
1255 </para>
1256</section>
1257
1258<section id='ref-classes-insane'>
1259 <title><filename>insane.bbclass</filename></title>
1260
1261 <para>
1262 The <filename>insane</filename> class adds a step to the package
1263 generation process so that output quality assurance checks are
1264 generated by the OpenEmbedded build system.
1265 A range of checks are performed that check the build's output
1266 for common problems that show up during runtime.
1267 Distribution policy usually dictates whether to include this class.
1268 </para>
1269
1270 <para>
1271 You can configure the sanity checks so that specific test failures
1272 either raise a warning or an error message.
1273 Typically, failures for new tests generate a warning.
1274 Subsequent failures for the same test would then generate an error
1275 message once the metadata is in a known and good condition.
1276 See the
1277 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1278 Chapter for a list of all the warning and error messages
1279 you might encounter using a default configuration.
1280 </para>
1281
1282 <para>
1283 Use the
1284 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1285 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1286 variables to control the behavior of
1287 these checks at the global level (i.e. in your custom distro
1288 configuration).
1289 However, to skip one or more checks in recipes, you should use
1290 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1291 For example, to skip the check for symbolic link
1292 <filename>.so</filename> files in the main package of a recipe,
1293 add the following to the recipe.
1294 You need to realize that the package name override, in this example
1295 <filename>${PN}</filename>, must be used:
1296 <literallayout class='monospaced'>
1297 INSANE_SKIP_${PN} += "dev-so"
1298 </literallayout>
1299 Please keep in mind that the QA checks exist in order to detect real
1300 or potential problems in the packaged output.
1301 So exercise caution when disabling these checks.
1302 </para>
1303
1304 <para>
1305 The following list shows the tests you can list with the
1306 <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
1307 variables:
1308 <itemizedlist>
1309 <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
1310 Checks that produced binaries have not already been
1311 stripped prior to the build system extracting debug symbols.
1312 It is common for upstream software projects to default to
1313 stripping debug symbols for output binaries.
1314 In order for debugging to work on the target using
1315 <filename>-dbg</filename> packages, this stripping must be
1316 disabled.
1317 </para></listitem>
1318 <listitem><para><emphasis><filename>arch:</filename></emphasis>
1319 Checks the Executable and Linkable Format (ELF) type, bit size,
1320 and endianness of any binaries to ensure they match the target
1321 architecture.
1322 This test fails if any binaries do not match the type since
1323 there would be an incompatibility.
1324 The test could indicate that the
1325 wrong compiler or compiler options have been used.
1326 Sometimes software, like bootloaders, might need to bypass
1327 this check.
1328 </para></listitem>
1329 <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
1330 Checks for paths to locations on the build host inside the
1331 output files.
1332 Currently, this test triggers too many false positives and
1333 thus is not normally enabled.
1334 </para></listitem>
1335 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
1336 Checks the
1337 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1338 log for indications
1339 that paths to locations on the build host were used.
1340 Using such paths might result in host contamination of the
1341 build output.
1342 </para></listitem>
1343 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
1344 Checks that all packages except <filename>-dbg</filename>
1345 packages do not depend on <filename>-dbg</filename>
1346 packages, which would cause a packaging bug.
1347 </para></listitem>
1348 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
1349 Checks for <filename>.debug</filename> directories in anything but the
1350 <filename>-dbg</filename> package.
1351 The debug files should all be in the <filename>-dbg</filename> package.
1352 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
1353 <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
1354 Checks for invalid version comparison statements in runtime
1355 dependency relationships between packages (i.e. in
1356 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1357 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1358 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1359 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1360 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1361 and
1362 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
1363 variable values).
1364 Any invalid comparisons might trigger failures or undesirable
1365 behavior when passed to the package manager.
1366 </para></listitem>
1367 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
1368 Runs the <filename>desktop-file-validate</filename> program
1369 against any <filename>.desktop</filename> files to validate
1370 their contents against the specification for
1371 <filename>.desktop</filename> files.</para></listitem>
1372 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
1373 Checks that all packages except <filename>-dev</filename>
1374 or <filename>-staticdev</filename> packages do not depend on
1375 <filename>-dev</filename> packages, which would be a
1376 packaging bug.</para></listitem>
1377 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
1378 Checks that the <filename>.so</filename> symbolic links are in the
1379 <filename>-dev</filename> package and not in any of the other packages.
1380 In general, these symlinks are only useful for development purposes.
1381 Thus, the <filename>-dev</filename> package is the correct location for
1382 them.
1383 Some very rare cases do exist for dynamically loaded modules where
1384 these symlinks are needed instead in the main package.
1385 </para></listitem>
1386 <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
1387 Checks for
1388 <link linkend='var-FILES'><filename>FILES</filename></link>
1389 variable values that contain "//", which is invalid.
1390 </para></listitem>
1391 <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
1392 Report when packages are excluded from being created due to
1393 being marked with a license that is in
1394 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
1395 </para></listitem>
1396 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
1397 Checks the
1398 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1399 log for indications
1400 that paths to locations on the build host were used.
1401 Using such paths might result in host contamination of the
1402 build output.
1403 </para></listitem>
1404 <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
1405 Reports when files have been installed within
1406 <filename>do_install</filename> but have not been included in
1407 any package by way of the
1408 <link linkend='var-FILES'><filename>FILES</filename></link>
1409 variable.
1410 Files that do not appear in any package cannot be present in
1411 an image later on in the build process.
1412 Ideally, all installed files should be packaged or not
1413 installed at all.
1414 These files can be deleted at the end of
1415 <filename>do_install</filename> if the files are not
1416 needed in any package.
1417 </para></listitem>
1418 <listitem><para><emphasis><filename>la:</filename></emphasis>
1419 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
1420 paths.
1421 Any <filename>.la</filename> file containing these paths is incorrect since
1422 <filename>libtool</filename> adds the correct sysroot prefix when using the
1423 files automatically itself.</para></listitem>
1424 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
1425 Ensures that the binaries were linked with the
1426 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1427 options provided by the build system.
1428 If this test fails, check that the <filename>LDFLAGS</filename> variable
1429 is being passed to the linker command.</para></listitem>
1430 <listitem><para><emphasis><filename>libdir:</filename></emphasis>
1431 Checks for libraries being installed into incorrect
1432 (possibly hardcoded) installation paths.
1433 For example, this test will catch recipes that install
1434 <filename>/lib/bar.so</filename> when
1435 <filename>${base_libdir}</filename> is "lib32".
1436 Another example is when recipes install
1437 <filename>/usr/lib64/foo.so</filename> when
1438 <filename>${libdir}</filename> is "/usr/lib".
1439 </para></listitem>
1440 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
1441 Checks if a package contains files in
1442 <filename>/usr/libexec</filename>.
1443 This check is not performed if the
1444 <filename>libexecdir</filename> variable has been set
1445 explicitly to <filename>/usr/libexec</filename>.
1446 </para></listitem>
1447 <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
1448 Checks for the same package being listed multiple times through
1449 the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1450 variable value.
1451 Installing the package in this manner can cause errors during
1452 packaging.
1453 </para></listitem>
1454 <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
1455 Reports lines in <filename>fs-perms.txt</filename> that have
1456 an invalid format.
1457 </para></listitem>
1458 <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
1459 Reports lines in <filename>fs-perms.txt</filename> that have
1460 an invalid format.
1461 </para></listitem>
1462 <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
1463 Reports lines in <filename>fs-perms.txt</filename> that
1464 specify 'link' where the specified target already exists.
1465 </para></listitem>
1466 <listitem><para><emphasis><filename>perms:</filename></emphasis>
1467 Currently, this check is unused but reserved.
1468 </para></listitem>
1469 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
1470 Checks <filename>.pc</filename> files for any
1471 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
1472 paths.
1473 Any <filename>.pc</filename> file containing these paths is incorrect
1474 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
1475 when the files are accessed.</para></listitem>
1476 <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
1477 Checks that all packages in
1478 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1479 have names that do not contain invalid characters (i.e.
1480 characters other than 0-9, a-z, ., +, and -).
1481 </para></listitem>
1482 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
1483 Checks to see if the <filename>PKGV</filename> variable
1484 is undefined during
1485 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1486 </para></listitem>
1487 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
1488 Checks through the variables
1489 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1490 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1491 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1492 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
1493 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1494 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1495 <link linkend='var-FILES'><filename>FILES</filename></link>,
1496 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
1497 <filename>pkg_preinst</filename>,
1498 <filename>pkg_postinst</filename>,
1499 <filename>pkg_prerm</filename>
1500 and <filename>pkg_postrm</filename>, and reports if there are
1501 variable sets that are not package-specific.
1502 Using these variables without a package suffix is bad practice,
1503 and might unnecessarily complicate dependencies of other packages
1504 within the same recipe or have other unintended consequences.
1505 </para></listitem>
1506 <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
1507 Checks that a recipe does not have a name
1508 (<link linkend='var-PN'><filename>PN</filename></link>) value
1509 that appears in
1510 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
1511 If a recipe is named such that its <filename>PN</filename>
1512 value matches something already in
1513 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
1514 happens to be the same as
1515 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
1516 or
1517 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
1518 it can have unexpected consequences.
1519 For example, assignments such as
1520 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
1521 <filename>FILES = "xyz"</filename>.
1522 </para></listitem>
1523 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
1524 Checks for rpaths in the binaries that contain build system paths such
1525 as <filename>TMPDIR</filename>.
1526 If this test fails, bad <filename>-rpath</filename> options are being
1527 passed to the linker commands and your binaries have potential security
1528 issues.</para></listitem>
1529 <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
1530 Reports that splitting or stripping debug symbols from binaries
1531 has failed.
1532 </para></listitem>
1533 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
1534 Checks for static library files (<filename>*.a</filename>) in
1535 non-<filename>staticdev</filename> packages.
1536 </para></listitem>
1537 <listitem><para><emphasis><filename>symlink-to-sysroot:</filename></emphasis>
1538 Checks for symlinks in packages that point into
1539 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1540 on the host.
1541 Such symlinks will work on the host, but are clearly invalid
1542 when running on the target.
1543 </para></listitem>
1544 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
1545 Checks for ELF binaries that contain relocations in their
1546 <filename>.text</filename> sections, which can result in a
1547 performance impact at runtime.</para></listitem>
1548 <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
1549 Reports when a binary installed in
1550 <filename>${base_libdir}</filename>,
1551 <filename>${base_bindir}</filename>, or
1552 <filename>${base_sbindir}</filename>, depends on another
1553 binary installed under <filename>${exec_prefix}</filename>.
1554 This dependency is a concern if you want the system to remain
1555 basically operable if <filename>/usr</filename> is mounted
1556 separately and is not mounted.
1557 <note>
1558 Defaults for binaries installed in
1559 <filename>${base_libdir}</filename>,
1560 <filename>${base_bindir}</filename>, and
1561 <filename>${base_sbindir}</filename> are
1562 <filename>/lib</filename>, <filename>/bin</filename>, and
1563 <filename>/sbin</filename>, respectively.
1564 The default for a binary installed
1565 under <filename>${exec_prefix}</filename> is
1566 <filename>/usr</filename>.
1567 </note>
1568 </para></listitem>
1569 <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
1570 Reports when a script file installed in
1571 <filename>${base_libdir}</filename>,
1572 <filename>${base_bindir}</filename>, or
1573 <filename>${base_sbindir}</filename>, depends on files
1574 installed under <filename>${exec_prefix}</filename>.
1575 This dependency is a concern if you want the system to remain
1576 basically operable if <filename>/usr</filename> is mounted
1577 separately and is not mounted.
1578 <note>
1579 Defaults for binaries installed in
1580 <filename>${base_libdir}</filename>,
1581 <filename>${base_bindir}</filename>, and
1582 <filename>${base_sbindir}</filename> are
1583 <filename>/lib</filename>, <filename>/bin</filename>, and
1584 <filename>/sbin</filename>, respectively.
1585 The default for a binary installed
1586 under <filename>${exec_prefix}</filename> is
1587 <filename>/usr</filename>.
1588 </note>
1589 </para></listitem>
1590 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
1591 Checks for dynamic library load paths (rpaths) in the binaries that
1592 by default on a standard system are searched by the linker (e.g.
1593 <filename>/lib</filename> and <filename>/usr/lib</filename>).
1594 While these paths will not cause any breakage, they do waste space and
1595 are unnecessary.</para></listitem>
1596 <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
1597 Reports when variables fundamental to packaging (i.e.
1598 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
1599 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
1600 <link linkend='var-D'><filename>D</filename></link>,
1601 <link linkend='var-PN'><filename>PN</filename></link>, and
1602 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
1603 undefined during
1604 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1605 </para></listitem>
1606 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
1607 If Build History is enabled, reports when a package
1608 being written out has a lower version than the previously
1609 written package under the same name.
1610 If you are placing output packages into a feed and
1611 upgrading packages on a target system using that feed, the
1612 version of a package going backwards can result in the target
1613 system not correctly upgrading to the "new" version of the
1614 package.
1615 <note>
1616 If you are not using runtime package management on your
1617 target system, then you do not need to worry about
1618 this situation.
1619 </note>
1620 </para></listitem>
1621 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
1622 Checks that all packages containing Xorg drivers have ABI
1623 dependencies.
1624 The <filename>xserver-xorg</filename> recipe provides driver
1625 ABI names.
1626 All drivers should depend on the ABI versions that they have
1627 been built against.
1628 Driver recipes that include
1629 <filename>xorg-driver-input.inc</filename>
1630 or <filename>xorg-driver-video.inc</filename> will
1631 automatically get these versions.
1632 Consequently, you should only need to explicitly add
1633 dependencies to binary driver recipes.
1634 </para></listitem>
1635 </itemizedlist>
1636 </para>
1637</section>
1638
1639<section id='ref-classes-insserv'>
1640 <title><filename>insserv.bbclass</filename></title>
1641
1642 <para>
1643 The <filename>insserv</filename> class
1644 uses the <filename>insserv</filename> utility to update the order of
1645 symbolic links in <filename>/etc/rc?.d/</filename> within an image
1646 based on dependencies specified by LSB headers in the
1647 <filename>init.d</filename> scripts themselves.
1648 </para>
1649</section>
1650
1651<section id='ref-classes-kernel'>
1652 <title><filename>kernel.bbclass</filename></title>
1653
1654 <para>
1655 The <filename>kernel</filename> class handles building Linux kernels.
1656 The class contains code to build all kernel trees.
1657 All needed headers are staged into the
1658 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
1659 directory to allow out-of-tree module builds using
1660 the
1661 <link linkend='ref-classes-module'><filename>module</filename></link>
1662 class.
1663 </para>
1664
1665 <para>
1666 This means that each built kernel module is packaged separately and inter-module
1667 dependencies are created by parsing the <filename>modinfo</filename> output.
1668 If all modules are required, then installing the <filename>kernel-modules</filename>
1669 package installs all packages with modules and various other kernel packages
1670 such as <filename>kernel-vmlinux</filename>.
1671 </para>
1672
1673 <para>
1674 Various other classes are used by the <filename>kernel</filename>
1675 and <filename>module</filename> classes internally including the
1676 <link linkend='ref-classes-kernel-arch'><filename>kernel-arch</filename></link>,
1677 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>,
1678 and
1679 <link linkend='ref-classes-linux-kernel-base'><filename>linux-kernel-base</filename></link>
1680 classes.
1681 </para>
1682</section>
1683
1684<section id='ref-classes-kernel-arch'>
1685 <title><filename>kernel-arch.bbclass</filename></title>
1686
1687 <para>
1688 The <filename>kernel-arch</filename> class
1689 sets the <filename>ARCH</filename> environment variable for Linux
1690 kernel compilation (including modules).
1691 </para>
1692</section>
1693
1694<section id='ref-classes-kernel-module-split'>
1695 <title><filename>kernel-module-split.bbclass</filename></title>
1696
1697 <para>
1698 The <filename>kernel-module-split</filename> class
1699 provides common functionality for splitting Linux kernel modules into
1700 separate packages.
1701 </para>
1702</section>
1703
1704<section id='ref-classes-kernel-yocto'>
1705 <title><filename>kernel-yocto.bbclass</filename></title>
1706
1707 <para>
1708 The <filename>kernel-yocto</filename> class
1709 provides common functionality for building from linux-yocto style
1710 kernel source repositories.
1711 </para>
1712</section>
1713
1714<section id='ref-classes-lib_package'>
1715 <title><filename>lib_package.bbclass</filename></title>
1716
1717 <para>
1718 The <filename>lib_package</filename> class
1719 supports recipes that build libraries and produce executable
1720 binaries, where those binaries should not be installed by default
1721 along with the library.
1722 Instead, the binaries are added to a separate
1723 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-bin</filename>
1724 package to make their installation optional.
1725 </para>
1726</section>
1727
1728<section id='ref-classes-license'>
1729 <title><filename>license.bbclass</filename></title>
1730
1731 <para>
1732 The <filename>license</filename> class provides license
1733 manifest creation and license exclusion.
1734 This class is enabled by default using the default value for the
1735 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
1736 variable.
1737 </para>
1738</section>
1739
1740<section id='ref-classes-linux-kernel-base'>
1741 <title><filename>linux-kernel-base.bbclass</filename></title>
1742
1743 <para>
1744 The <filename>linux-kernel-base</filename> class
1745 provides common functionality for recipes that build out of the Linux
1746 kernel source tree.
1747 These builds goes beyond the kernel itself.
1748 For example, the Perf recipe also inherits this class.
1749 </para>
1750</section>
1751
1752<section id='ref-classes-logging'>
1753 <title><filename>logging.bbclass</filename></title>
1754
1755 <para>
1756 The <filename>logging</filename> class provides the standard
1757 shell functions used to log messages for various BitBake severity levels
1758 (i.e. <filename>bbplain</filename>, <filename>bbnote</filename>,
1759 <filename>bbwarn</filename>, <filename>bberror</filename>,
1760 <filename>bbfatal</filename>, and <filename>bbdebug</filename>).
1761 </para>
1762
1763 <para>
1764 This class is enabled by default since it is inherited by
1765 the <filename>base</filename> class.
1766 </para>
1767</section>
1768
1769<section id='ref-classes-meta'>
1770 <title><filename>meta.bbclass</filename></title>
1771
1772 <para>
1773 The <filename>meta</filename> class is inherited by recipes
1774 that do not build any output packages themselves, but act as a "meta"
1775 target for building other recipes.
1776 </para>
1777</section>
1778
1779<section id='ref-classes-metadata_scm'>
1780 <title><filename>metadata_scm.bbclass</filename></title>
1781
1782 <para>
1783 The <filename>metadata_scm</filename> class provides functionality for
1784 querying the branch and revision of a Source Code Manager (SCM)
1785 repository.
1786 </para>
1787
1788 <para>
1789 The <link linkend='ref-classes-base'><filename>base</filename></link>
1790 class uses this class to print the revisions of each layer before
1791 starting every build.
1792 The <filename>metadata_scm</filename> class is enabled by default
1793 because it is inherited by the <filename>base</filename> class.
1794 </para>
1795</section>
1796
1797<section id='ref-classes-mime'>
1798 <title><filename>mime.bbclass</filename></title>
1799
1800 <para>
1801 The <filename>mime</filename> class generates the proper
1802 post-install and post-remove (postinst/postrm) scriptlets for packages
1803 that install MIME type files.
1804 These scriptlets call <filename>update-mime-database</filename> to add
1805 the MIME types to the shared database.
1806 </para>
1807</section>
1808
1809<section id='ref-classes-mirrors'>
1810 <title><filename>mirrors.bbclass</filename></title>
1811
1812 <para>
1813 The <filename>mirrors</filename> class sets up some standard
1814 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> entries
1815 for source code mirrors.
1816 These mirrors provide a fall-back path in case the upstream source
1817 specified in
1818 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
1819 within recipes is unavailable.
1820 </para>
1821
1822 <para>
1823 This class is enabled by default since it is inherited by the
1824 <link linkend='ref-classes-base'><filename>base</filename></link> class.
1825 </para>
1826</section>
1827
1828<section id='ref-classes-module'>
1829 <title><filename>module.bbclass</filename></title>
1830
1831 <para>
1832 The <filename>module</filename> class provides support for building
1833 out-of-tree Linux kernel modules.
1834 The class inherits the
1835 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>
1836 and
1837 <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link>
1838 classes, and implements the
1839 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1840 and
1841 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1842 tasks.
1843 The class provides everything needed to build and package a kernel
1844 module.
1845 </para>
1846
1847 <para>
1848 For general information on out-of-tree Linux kernel modules, see the
1849 "<ulink url='&YOCTO_DOCS_KERNEL_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
1850 section in the Yocto Project Linux Kernel Development Manual.
1851 </para>
1852</section>
1853
1854<section id='ref-classes-module-base'>
1855 <title><filename>module-base.bbclass</filename></title>
1856
1857 <para>
1858 The <filename>module-base</filename> class provides the base
1859 functionality for building Linux kernel modules.
1860 Typically, a recipe that builds software that includes one or
1861 more kernel modules and has its own means of building
1862 the module inherits this class as opposed to inheriting the
1863 <link linkend='ref-classes-module'><filename>module</filename></link>
1864 class.
1865 </para>
1866</section>
1867
1868<section id='ref-classes-multilib*'>
1869 <title><filename>multilib*.bbclass</filename></title>
1870
1871 <para>
1872 The <filename>multilib*</filename> classes provide support
1873 for building libraries with different target optimizations or target
1874 architectures and installing them side-by-side in the same image.
1875 </para>
1876
1877 <para>
1878 For more information on using the Multilib feature, see the
1879 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
1880 section in the Yocto Project Development Manual.
1881 </para>
1882</section>
1883
1884<section id='ref-classes-native'>
1885 <title><filename>native.bbclass</filename></title>
1886
1887 <para>
1888 The <filename>native</filename> class provides common
1889 functionality for recipes that wish to build tools to run on the build
1890 host (i.e. tools that use the compiler or other tools from the
1891 build host).
1892 </para>
1893
1894 <para>
1895 You can create a recipe that builds tools that run natively on the
1896 host a couple different ways:
1897 <itemizedlist>
1898 <listitem><para>Create a <filename>myrecipe-native.bb</filename>
1899 that inherits the <filename>native</filename> class.
1900 If you use this method, you must order the inherit statement
1901 in the recipe after all other inherit statements so that the
1902 <filename>native</filename> class is inherited last.
1903 </para></listitem>
1904 <listitem><para>Create or modify a target recipe that has adds
1905 the following:
1906 <literallayout class='monospaced'>
1907 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native"
1908 </literallayout>
1909 Inside the recipe, use <filename>_class-native</filename> and
1910 <filename>_class-target</filename> overrides to specify any
1911 functionality specific to the respective native or target
1912 case.</para></listitem>
1913 </itemizedlist>
1914 </para>
1915
1916 <para>
1917 Although applied differently, the <filename>native</filename> class is
1918 used with both methods.
1919 The advantage of the second method is that you do not need to have two
1920 separate recipes (assuming you need both) for native and target.
1921 All common parts of the recipe are automatically shared.
1922 </para>
1923</section>
1924
1925<section id='ref-classes-nativesdk'>
1926 <title><filename>nativesdk.bbclass</filename></title>
1927
1928 <para>
1929 The <filename>nativesdk</filename> class provides common
1930 functionality for recipes that wish to build tools to run as part of
1931 an SDK (i.e. tools that run on
1932 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
1933 </para>
1934
1935 <para>
1936 You can create a recipe that builds tools that run on the SDK machine
1937 a couple different ways:
1938 <itemizedlist>
1939 <listitem><para>Create a <filename>myrecipe-nativesdk.bb</filename>
1940 recipe that inherits the <filename>nativesdk</filename> class.
1941 If you use this method, you must order the inherit statement
1942 in the recipe after all other inherit statements so that the
1943 <filename>nativesdk</filename> class is inherited last.
1944 </para></listitem>
1945 <listitem><para>Create a <filename>nativesdk</filename> variant
1946 of any recipe by adding the following:
1947 <literallayout class='monospaced'>
1948 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "nativesdk"
1949 </literallayout>
1950 Inside the recipe, use <filename>_class-nativesdk</filename> and
1951 <filename>_class-target</filename> overrides to specify any
1952 functionality specific to the respective SDK machine or target
1953 case.</para></listitem>
1954 </itemizedlist>
1955 </para>
1956
1957 <para>
1958 Although applied differently, the <filename>nativesdk</filename> class
1959 is used with both methods.
1960 The advantage of the second method is that you do not need to have two
1961 separate recipes (assuming you need both) for the SDK machine and the
1962 target.
1963 All common parts of the recipe are automatically shared.
1964 </para>
1965</section>
1966
1967<section id='ref-classes-oelint'>
1968 <title><filename>oelint.bbclass</filename></title>
1969
1970 <para>
1971 The <filename>oelint</filename> class is an
1972 obsolete lint checking tool that exists in
1973 <filename>meta/classes</filename> in the
1974 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
1975 </para>
1976
1977 <para>
1978 A number of classes exist that are could be generally useful in
1979 OE-Core but are never actually used within OE-Core itself.
1980 The <filename>oelint</filename> class is one such example.
1981 However, being aware of this class can reduce the proliferation of
1982 different versions of similar classes across multiple layers.
1983 </para>
1984</section>
1985
1986<section id='ref-classes-own-mirrors'>
1987 <title><filename>own-mirrors.bbclass</filename></title>
1988
1989 <para>
1990 The <filename>own-mirrors</filename> class makes it
1991 easier to set up your own
1992 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
1993 from which to first fetch source before attempting to fetch it from the
1994 upstream specified in
1995 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
1996 within each recipe.
1997 </para>
1998
1999 <para>
2000 To use this class, inherit it globally and specify
2001 <link linkend='var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></link>.
2002 Here is an example:
2003 <literallayout class='monospaced'>
2004 INHERIT += "own-mirrors"
2005 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
2006 </literallayout>
2007 You can specify only a single URL in
2008 <filename>SOURCE_MIRROR_URL</filename>.
2009 </para>
2010</section>
2011
2012<section id='ref-classes-package'>
2013 <title><filename>package.bbclass</filename></title>
2014
2015 <para>
2016 The <filename>package</filename> class supports generating
2017 packages from a build's output.
2018 The core generic functionality is in
2019 <filename>package.bbclass</filename>.
2020 The code specific to particular package types resides in these
2021 package-specific classes:
2022 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
2023 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
2024 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
2025 and
2026 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
2027 </para>
2028
2029 <para>
2030 You can control the list of resulting package formats by using the
2031 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
2032 variable defined in your <filename>conf/local.conf</filename>
2033 configuration file, which is located in the
2034 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2035 When defining the variable, you can specify one or more package types.
2036 Since images are generated from packages, a packaging class is
2037 needed to enable image generation.
2038 The first class listed in this variable is used for image generation.
2039 </para>
2040
2041 <para>
2042 If you take the optional step to set up a repository (package feed)
2043 on the development host that can be used by Smart, you can
2044 install packages from the feed while you are running the image
2045 on the target (i.e. runtime installation of packages).
2046 For more information, see the
2047 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
2048 section in the Yocto Project Development Manual.
2049 </para>
2050
2051 <para>
2052 The package-specific class you choose can affect build-time performance
2053 and has space ramifications.
2054 In general, building a package with IPK takes about thirty percent less
2055 time as compared to using RPM to build the same or similar package.
2056 This comparison takes into account a complete build of the package with
2057 all dependencies previously built.
2058 The reason for this discrepancy is because the RPM package manager
2059 creates and processes more
2060 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the
2061 IPK package manager.
2062 Consequently, you might consider setting
2063 <filename>PACKAGE_CLASSES</filename> to "package_ipk" if you are
2064 building smaller systems.
2065 </para>
2066
2067 <para>
2068 Before making your package manager decision, however, you should
2069 consider some further things about using RPM:
2070 <itemizedlist>
2071 <listitem><para>
2072 RPM starts to provide more abilities than IPK due to
2073 the fact that it processes more Metadata.
2074 For example, this information includes individual file types,
2075 file checksum generation and evaluation on install, sparse file
2076 support, conflict detection and resolution for Multilib systems,
2077 ACID style upgrade, and repackaging abilities for rollbacks.
2078 </para></listitem>
2079 <listitem><para>
2080 For smaller systems, the extra space used for the Berkeley
2081 Database and the amount of metadata when using RPM can affect
2082 your ability to perform on-device upgrades.
2083 </para></listitem>
2084 </itemizedlist>
2085 </para>
2086
2087 <para>
2088 You can find additional information on the effects of the package
2089 class at these two Yocto Project mailing list links:
2090 <itemizedlist>
2091 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
2092 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
2093 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
2094 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
2095 </itemizedlist>
2096 </para>
2097</section>
2098
2099<section id='ref-classes-package_deb'>
2100 <title><filename>package_deb.bbclass</filename></title>
2101
2102 <para>
2103 The <filename>package_deb</filename> class
2104 provides support for creating packages that use the
2105 <filename>.deb</filename> file format.
2106 The class ensures the packages are written out to the
2107 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/deb</filename>
2108 directory in a <filename>.deb</filename> file format.
2109 </para>
2110
2111 <para>
2112 This class inherits the
2113 <link linkend='ref-classes-package'><filename>package</filename></link>
2114 class and is enabled through the
2115 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2116 variable in the <filename>local.conf</filename> file.
2117 </para>
2118</section>
2119
2120<section id='ref-classes-package_ipk'>
2121 <title><filename>package_ipk.bbclass</filename></title>
2122
2123 <para>
2124 The <filename>package_ipk</filename> class
2125 provides support for creating packages that use the
2126 <filename>.ipk</filename> file format.
2127 The class ensures the packages are written out to the
2128 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/ipk</filename>
2129 directory in a <filename>.ipk</filename> file format.
2130 </para>
2131
2132 <para>
2133 This class inherits the
2134 <link linkend='ref-classes-package'><filename>package</filename></link>
2135 class and is enabled through the
2136 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2137 variable in the <filename>local.conf</filename> file.
2138 </para>
2139</section>
2140
2141<section id='ref-classes-package_rpm'>
2142 <title><filename>package_rpm.bbclass</filename></title>
2143
2144 <para>
2145 The <filename>package_deb</filename> class
2146 provides support for creating packages that use the
2147 <filename>.rpm</filename> file format.
2148 The class ensures the packages are written out to the
2149 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/rpm</filename>
2150 directory in a <filename>.rpm</filename> file format.
2151 </para>
2152
2153 <para>
2154 This class inherits the
2155 <link linkend='ref-classes-package'><filename>package</filename></link>
2156 class and is enabled through the
2157 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2158 variable in the <filename>local.conf</filename> file.
2159 </para>
2160</section>
2161
2162<section id='ref-classes-package_tar'>
2163 <title><filename>package_tar.bbclass</filename></title>
2164
2165 <para>
2166 The <filename>package_tar</filename>
2167 class provides support for creating packages that use the
2168 <filename>.tar</filename> file format.
2169 The class ensures the packages are written out to the
2170 <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/tar</filename>
2171 directory in a <filename>.tar</filename> file format.
2172 </para>
2173
2174 <para>
2175 This class inherits the
2176 <link linkend='ref-classes-package'><filename>package</filename></link>
2177 class and is enabled through the
2178 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2179 variable in the <filename>local.conf</filename> file.
2180 <note>
2181 You cannot specify the <filename>package_tar</filename> class
2182 first using the <filename>PACKAGE_CLASSES</filename> variable.
2183 You must use <filename>.deb</filename>,
2184 <filename>.ipk</filename>, or <filename>.rpm</filename> file
2185 formats for your image or SDK.
2186 </note>
2187 </para>
2188</section>
2189
2190<section id='ref-classes-packagedata'>
2191 <title><filename>packagedata.bbclass</filename></title>
2192
2193 <para>
2194 The <filename>packagedata</filename> class provides
2195 common functionality for reading <filename>pkgdata</filename> files
2196 found in
2197 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
2198 These files contain information about each output package produced by
2199 the OpenEmbedded build system.
2200 </para>
2201
2202 <para>
2203 This class is enabled by default because it is inherited by the
2204 <link linkend='ref-classes-package'><filename>package</filename></link>
2205 class.
2206 </para>
2207</section>
2208
2209<section id='ref-classes-packagegroup'>
2210 <title><filename>packagegroup.bbclass</filename></title>
2211
2212 <para>
2213 The <filename>packagegroup</filename> class sets default values
2214 appropriate for package group recipes (e.g.
2215 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
2216 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
2217 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
2218 and so forth).
2219 It is highly recommended that all package group recipes inherit this class.
2220 </para>
2221
2222 <para>
2223 For information on how to use this class, see the
2224 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
2225 section in the Yocto Project Development Manual.
2226 </para>
2227
2228 <para>
2229 Previously, this class was called the <filename>task</filename> class.
2230 </para>
2231</section>
2232
2233<section id='ref-classes-packageinfo'>
2234 <title><filename>packageinfo.bbclass</filename></title>
2235
2236 <para>
2237 The <filename>packageinfo</filename> class
2238 gives a BitBake user interface the ability to retrieve information
2239 about output packages from the <filename>pkgdata</filename> files.
2240 </para>
2241
2242 <para>
2243 This class is enabled automatically when using the
2244 <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>
2245 user interface.
2246 </para>
2247</section>
2248
2249<section id='ref-classes-patch'>
2250 <title><filename>patch.bbclass</filename></title>
2251
2252 <para>
2253 The <filename>patch</filename> class provides all functionality for
2254 applying patches during the
2255 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
2256 task.
2257 </para>
2258
2259 <para>
2260 This class is enabled by default because it is inherited by the
2261 <link linkend='ref-classes-base'><filename>base</filename></link>
2262 class.
2263 </para>
2264</section>
2265
2266<section id='ref-classes-perlnative'>
2267 <title><filename>perlnative.bbclass</filename></title>
2268
2269 <para>
2270 When inherited by a recipe, the <filename>perlnative</filename> class
2271 supports using the native version of Perl built by the build system
2272 rather than using the version provided by the build host.
2273 </para>
2274</section>
2275
2276<section id='ref-classes-pixbufcache'>
2277 <title><filename>pixbufcache.bbclass</filename></title>
2278
2279 <para>
2280 The <filename>pixbufcache</filename> class generates the proper
2281 post-install and post-remove (postinst/postrm) scriptlets for packages
2282 that install pixbuf loaders, which are used with
2283 <filename>gdk-pixbuf</filename>.
2284 These scriptlets call <filename>update_pixbuf_cache</filename>
2285 to add the pixbuf loaders to the cache.
2286 Since the cache files are architecture-specific,
2287 <filename>update_pixbuf_cache</filename> is run using QEMU if the
2288 postinst scriptlets need to be run on the build host during image
2289 creation.
2290 </para>
2291
2292 <para>
2293 If the pixbuf loaders being installed are in packages other
2294 than the recipe's main package, set
2295 <link linkend='var-PIXBUF_PACKAGES'><filename>PIXBUF_PACKAGES</filename></link>
2296 to specify the packages containing the loaders.
2297 </para>
2298</section>
2299
2300<section id='ref-classes-pkgconfig'>
2301 <title><filename>pkgconfig.bbclass</filename></title>
2302
2303 <para>
2304 The <filename>pkg-config</filename> class provides a standard way to get
2305 header and library information.
2306 This class aims to smooth integration of
2307 <filename>pkg-config</filename> into libraries that use it.
2308 </para>
2309
2310 <para>
2311 During staging, BitBake installs <filename>pkg-config</filename> data into the
2312 <filename>sysroots/</filename> directory.
2313 By making use of sysroot functionality within <filename>pkg-config</filename>,
2314 this class no longer has to manipulate the files.
2315 </para>
2316</section>
2317
2318<section id='ref-classes-populate-sdk'>
2319 <title><filename>populate_sdk.bbclass</filename></title>
2320
2321 <para>
2322 The <filename>populate_sdk</filename> class provides support for
2323 SDK-only recipes.
2324 For information on advantages gained when building a cross-development
2325 toolchain using the
2326 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2327 task, see the
2328 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2329 section in the Yocto Project Application Developer's Guide.
2330 </para>
2331</section>
2332
2333<section id='ref-classes-populate-sdk-*'>
2334 <title><filename>populate_sdk_*.bbclass</filename></title>
2335
2336 <para>
2337 The <filename>populate_sdk_*</filename> classes support SDK creation
2338 and consist of the following classes:
2339 <itemizedlist>
2340 <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis>
2341 The base class supporting SDK creation under all package
2342 managers (i.e. DEB, RPM, and IPK).</para></listitem>
2343 <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis>
2344 Supports creation of the SDK given the Debian package manager.
2345 </para></listitem>
2346 <listitem><para><emphasis><filename>populate_sdk_rpm</filename>:</emphasis>
2347 Supports creation of the SDK given the RPM package manager.
2348 </para></listitem>
2349 <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis>
2350 Supports creation of the SDK given the IPK package manager.
2351 </para></listitem>
2352 </itemizedlist>
2353 </para>
2354
2355 <para>
2356 The <filename>populate_sdk_base</filename> package inherits the
2357 appropriate <filename>populate_sdk_*</filename> (i.e.
2358 <filename>deb</filename>, <filename>rpm</filename>, and
2359 <filename>ipk</filename>) based on
2360 <link linkend='var-IMAGE_PKGTYPE'><filename>IMAGE_PKGTYPE</filename></link>.
2361 </para>
2362
2363 <para>
2364 The base class ensures all source and destination directories are
2365 established and then populates the SDK.
2366 After populating the SDK, the <filename>populate_sdk_base</filename>
2367 class constructs two images:
2368 <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>-nativesdk</filename>,
2369 which contains the cross-compiler and associated tooling, and the
2370 target, which contains a target root filesystem that is configured for
2371 the SDK usage.
2372 These two images reside in
2373 <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>,
2374 which consists of the following:
2375 <literallayout class='monospaced'>
2376 ${SDK_OUTPUT}/&lt;sdk_arch-nativesdk pkgs&gt;
2377 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/&lt;target pkgs&gt;
2378 </literallayout>
2379 </para>
2380
2381 <para>
2382 Finally, the base populate SDK class creates the toolchain
2383 environment setup script, the tarball of the SDK, and the installer.
2384 </para>
2385
2386 <para>
2387 The respective <filename>populate_sdk_deb</filename>,
2388 <filename>populate_sdk_rpm</filename>, and
2389 <filename>populate_sdk_ipk</filename> classes each support the
2390 specific type of SDK.
2391 These classes are inherited by and used with the
2392 <filename>populate_sdk_base</filename> class.
2393 </para>
2394
2395 <para>
2396 For more information on the cross-development toolchain
2397 generation, see the
2398 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
2399 section.
2400 For information on advantages gained when building a
2401 cross-development toolchain using the
2402 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2403 task, see the
2404 "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>"
2405 section in the Yocto Project Application Developer's Guide.
2406 </para>
2407</section>
2408
2409<section id='ref-classes-prexport'>
2410 <title><filename>prexport.bbclass</filename></title>
2411
2412 <para>
2413 The <filename>prexport</filename> class provides functionality for
2414 exporting
2415 <link linkend='var-PR'><filename>PR</filename></link> values.
2416 <note>
2417 This class is not intended to be used directly.
2418 Rather, it is enabled when using
2419 "<filename>bitbake-prserv-tool export</filename>".
2420 </note>
2421 </para>
2422</section>
2423
2424<section id='ref-classes-primport'>
2425 <title><filename>primport.bbclass</filename></title>
2426
2427 <para>
2428 The <filename>primport</filename> class provides functionality for
2429 importing
2430 <link linkend='var-PR'><filename>PR</filename></link> values.
2431 <note>
2432 This class is not intended to be used directly.
2433 Rather, it is enabled when using
2434 "<filename>bitbake-prserv-tool import</filename>".
2435 </note>
2436 </para>
2437</section>
2438
2439<section id='ref-classes-prserv'>
2440 <title><filename>prserv.bbclass</filename></title>
2441
2442 <para>
2443 The <filename>prserv</filename> class provides functionality for
2444 using a
2445 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>
2446 in order to automatically manage the incrementing of the
2447 <link linkend='var-PR'><filename>PR</filename></link> variable for
2448 each recipe.
2449 </para>
2450
2451 <para>
2452 This class is enabled by default because it is inherited by the
2453 <link linkend='ref-classes-package'><filename>package</filename></link>
2454 class.
2455 However, the OpenEmbedded build system will not enable the
2456 functionality of this class unless
2457 <link linkend='var-PRSERV_HOST'><filename>PRSERV_HOST</filename></link>
2458 has been set.
2459 </para>
2460</section>
2461
2462<section id='ref-classes-ptest'>
2463 <title><filename>ptest.bbclass</filename></title>
2464
2465 <para>
2466 The <filename>ptest</filename> class provides functionality for
2467 packaging and installing runtime tests for recipes that build software
2468 that provides these tests.
2469 </para>
2470
2471 <para>
2472 This class is intended to be inherited by individual recipes.
2473 However, the class' functionality is largely disabled unless "ptest"
2474 appears in
2475 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2476 See the
2477 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
2478 section in the Yocto Project Development Manual for more information
2479 on ptest.
2480 </para>
2481</section>
2482
2483<section id='ref-classes-python-dir'>
2484 <title><filename>python-dir.bbclass</filename></title>
2485
2486 <para>
2487 The <filename>python-dir</filename> class provides the base version,
2488 location, and site package location for Python.
2489 </para>
2490</section>
2491
2492<section id='ref-classes-pythonnative'>
2493 <title><filename>pythonnative.bbclass</filename></title>
2494
2495 <para>
2496 When inherited by a recipe, the <filename>pythonnative</filename> class
2497 supports using the native version of Python built by the build system
2498 rather than using the version provided by the build host.
2499 </para>
2500</section>
2501
2502<section id='ref-classes-qemu'>
2503 <title><filename>qemu.bbclass</filename></title>
2504
2505 <para>
2506 The <filename>qemu</filename> class provides functionality for recipes
2507 that either need QEMU or test for the existence of QEMU.
2508 Typically, this class is used to run programs for a target system on
2509 the build host using QEMU's application emulation mode.
2510 </para>
2511</section>
2512
2513<section id='ref-classes-qmake*'>
2514 <title><filename>qmake*.bbclass</filename></title>
2515
2516 <para>
2517 The <filename>qmake*</filename> classes support recipes that
2518 need to build software that uses Qt's <filename>qmake</filename>
2519 build system and are comprised of the following:
2520 <itemizedlist>
2521 <listitem><para><emphasis><filename>qmake_base</filename>:</emphasis>
2522 Provides base functionality for all versions of
2523 <filename>qmake</filename>.</para></listitem>
2524 <listitem><para><emphasis><filename>qmake2</filename>:</emphasis>
2525 Extends base functionality for <filename>qmake</filename> 2.x as
2526 used by Qt 4.x.</para></listitem>
2527 </itemizedlist>
2528 </para>
2529
2530 <para>
2531 If you need to set any configuration variables or pass any options to
2532 <filename>qmake</filename>, you can add these to the
2533 <link linkend='var-EXTRA_QMAKEVARS_PRE'><filename>EXTRA_QMAKEVARS_PRE</filename></link>
2534 or
2535 <link linkend='var-EXTRA_QMAKEVARS_POST'><filename>EXTRA_QMAKEVARS_POST</filename></link>
2536 variables, depending on whether the arguments need to be before or
2537 after the <filename>.pro</filename> file list on the command line,
2538 respectively.
2539 </para>
2540
2541 <para>
2542 By default, all <filename>.pro</filename> files are built.
2543 If you want to specify your own subset of <filename>.pro</filename>
2544 files to be built, specify them in the
2545 <link linkend='var-QMAKE_PROFILES'><filename>QMAKE_PROFILES</filename></link>
2546 variable.
2547 </para>
2548</section>
2549
2550<section id='ref-classes-qt4*'>
2551 <title><filename>qt4*.bbclass</filename></title>
2552
2553 <para>
2554 The <filename>qt4*</filename> classes support recipes that need to
2555 build software that uses the Qt development framework version 4.x
2556 and consist of the following:
2557 <itemizedlist>
2558 <listitem><para><emphasis><filename>qt4e</filename>:</emphasis>
2559 Supports building against Qt/Embedded, which uses the
2560 framebuffer for graphical output.</para></listitem>
2561 <listitem><para><emphasis><filename>qt4x11</filename>:</emphasis>
2562 Supports building against Qt/X11.</para></listitem>
2563 </itemizedlist>
2564 </para>
2565
2566 <para>
2567 The classes inherit the
2568 <link linkend='ref-classes-qmake*'><filename>qmake2</filename></link>
2569 class.
2570 </para>
2571</section>
2572
2573<section id='ref-classes-relocatable'>
2574 <title><filename>relocatable.bbclass</filename></title>
2575
2576 <para>
2577 The <filename>relocatable</filename> class enables relocation of
2578 binaries when they are installed into the sysroot.
2579 </para>
2580
2581 <para>
2582 This class makes use of the
2583 <link linkend='ref-classes-chrpath'><filename>chrpath</filename></link>
2584 class and is used by both the
2585 <link linkend='ref-classes-cross'><filename>cross</filename></link>
2586 and
2587 <link linkend='ref-classes-native'><filename>native</filename></link>
2588 classes.
2589 </para>
2590</section>
2591
2592<section id='ref-classes-report-error'>
2593 <title><filename>report-error.bbclass</filename></title>
2594
2595 <para>
2596 The <filename>report-error</filename> class supports enabling the
2597 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
2598 which allows you to submit build error information to a central
2599 database.
2600 </para>
2601
2602 <para>
2603 The class collects debug information for recipe, recipe version, task,
2604 machine, distro, build system, target system, host distro, branch,
2605 commit, and log.
2606 From the information, report files using a JSON format are created and
2607 stored in
2608 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
2609 </para>
2610</section>
2611
2612<section id='ref-classes-rm-work'>
2613 <title><filename>rm_work.bbclass</filename></title>
2614
2615 <para>
2616 The <filename>rm_work</filename> class supports deletion of temporary
2617 workspace, which can ease your hard drive demands during builds.
2618 </para>
2619
2620 <para>
2621 The OpenEmbedded build system can use a substantial amount of disk
2622 space during the build process.
2623 A portion of this space is the work files under the
2624 <filename>${TMPDIR}/work</filename> directory for each recipe.
2625 Once the build system generates the packages for a recipe, the work
2626 files for that recipe are no longer needed.
2627 However, by default, the build system preserves these files
2628 for inspection and possible debugging purposes.
2629 If you would rather have these files deleted to save disk space
2630 as the build progresses, you can enable <filename>rm_work</filename>
2631 by adding the following to your <filename>local.conf</filename> file,
2632 which is found in the
2633 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
2634 <literallayout class='monospaced'>
2635 INHERIT += "rm_work"
2636 </literallayout>
2637 If you are modifying and building source code out of the work directory
2638 for a recipe, enabling <filename>rm_work</filename> will potentially
2639 result in your changes to the source being lost.
2640 To exclude some recipes from having their work directories deleted by
2641 <filename>rm_work</filename>, you can add the names of the recipe or
2642 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
2643 variable, which can also be set in your <filename>local.conf</filename>
2644 file.
2645 Here is an example:
2646 <literallayout class='monospaced'>
2647 RM_WORK_EXCLUDE += "busybox eglibc"
2648 </literallayout>
2649 </para>
2650</section>
2651
2652<section id='ref-classes-rootfs*'>
2653 <title><filename>rootfs*.bbclass</filename></title>
2654
2655 <para>
2656 The <filename>rootfs*</filename> classes support creating
2657 the root filesystem for an image and consist of the following classes:
2658 <itemizedlist>
2659 <listitem><para>
2660 The <filename>rootfs_deb</filename> class, which supports
2661 creation of root filesystems for images built using
2662 <filename>.deb</filename> packages.</para></listitem>
2663 <listitem><para>
2664 The <filename>rootfs_rpm</filename> class, which supports
2665 creation of root filesystems for images built using
2666 <filename>.rpm</filename> packages.</para></listitem>
2667 <listitem><para>
2668 The <filename>rootfs_ipk</filename> class, which supports
2669 creation of root filesystems for images built using
2670 <filename>.ipk</filename> packages.</para></listitem>
2671 </itemizedlist>
2672 </para>
2673
2674 <para>
2675 The root filesystem is created from packages using one of the
2676 <filename>rootfs*.bbclass</filename> files as determined by the
2677 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2678 variable.
2679 </para>
2680
2681 <para>
2682 For information on how root filesystem images are created, see the
2683 "<link linkend='image-generation-dev-environment'>Image Generation</link>"
2684 section.
2685 </para>
2686</section>
2687
2688<section id='ref-classes-sanity'>
2689 <title><filename>sanity.bbclass</filename></title>
2690
2691 <para>
2692 The <filename>sanity</filename> class checks to see if prerequisite
2693 software is present on the host system so that users can be notified
2694 of potential problems that might affect their build.
2695 The class also performs basic user configuration checks from
2696 the <filename>local.conf</filename> configuration file to
2697 prevent common mistakes that cause build failures.
2698 Distribution policy usually determines whether to include this class.
2699 </para>
2700</section>
2701
2702<section id='ref-classes-scons'>
2703 <title><filename>scons.bbclass</filename></title>
2704
2705 <para>
2706 The <filename>scons</filename> class supports recipes that need to
2707 build software that uses the SCons build system.
2708 You can use the
2709 <link linkend='var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></link>
2710 variable to specify additional configuration options you want to pass
2711 SCons command line.
2712 </para>
2713</section>
2714
2715<section id='ref-classes-sdl'>
2716 <title><filename>sdl.bbclass</filename></title>
2717
2718 <para>
2719 The <filename>sdl</filename> class supports recipes that need to build
2720 software that uses the Simple DirectMedia Layer (SDL) library.
2721 </para>
2722</section>
2723
2724<section id='ref-classes-setuptools'>
2725 <title><filename>setuptools.bbclass</filename></title>
2726
2727 <para>
2728 The <filename>setuptools</filename> class supports Python
2729 version 2.x extensions that use build systems based on
2730 <filename>setuptools</filename>.
2731 If your recipe uses these build systems, the recipe needs to
2732 inherit the <filename>setuptools</filename> class.
2733 </para>
2734</section>
2735
2736<section id='ref-classes-setuptools3'>
2737 <title><filename>setuptools3.bbclass</filename></title>
2738
2739 <para>
2740 The <filename>setuptools3</filename> class supports Python
2741 version 3.x extensions that use build systems based on
2742 <filename>setuptools3</filename>.
2743 If your recipe uses these build systems, the recipe needs to
2744 inherit the <filename>setuptools3</filename> class.
2745 </para>
2746</section>
2747
2748<section id='ref-classes-sip'>
2749 <title><filename>sip.bbclass</filename></title>
2750
2751 <para>
2752 The <filename>sip</filename> class
2753 supports recipes that build or package SIP-based Python bindings.
2754 </para>
2755</section>
2756
2757<section id='ref-classes-siteconfig'>
2758 <title><filename>siteconfig.bbclass</filename></title>
2759
2760 <para>
2761 The <filename>siteconfig</filename> class
2762 provides functionality for handling site configuration.
2763 The class is used by the
2764 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
2765 class to accelerate the
2766 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
2767 task.
2768 </para>
2769</section>
2770
2771<section id='ref-classes-siteinfo'>
2772 <title><filename>siteinfo.bbclass</filename></title>
2773
2774 <para>
2775 The <filename>siteinfo</filename> class provides information about
2776 the targets that might be needed by other classes or recipes.
2777 </para>
2778
2779 <para>
2780 As an example, consider Autotools, which can require tests that must
2781 execute on the target hardware.
2782 Since this is not possible in general when cross compiling, site
2783 information is used to provide cached test results so these tests can
2784 be skipped over but still make the correct values available.
2785 The
2786 <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
2787 contains test results sorted into different categories such as
2788 architecture, endianness, and the <filename>libc</filename> used.
2789 Site information provides a list of files containing data relevant to
2790 the current build in the
2791 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
2792 that Autotools automatically picks up.
2793 </para>
2794
2795 <para>
2796 The class also provides variables like
2797 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
2798 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
2799 that can be used elsewhere in the metadata.
2800 </para>
2801
2802 <para>
2803 Because the
2804 <link linkend='ref-classes-base'><filename>base</filename></link> class
2805 includes the <filename>siteinfo</filename> class, it is always active.
2806 </para>
2807</section>
2808
2809<section id='ref-classes-spdx'>
2810 <title><filename>spdx.bbclass</filename></title>
2811
2812 <para>
2813 The <filename>spdx</filename> class integrates real-time license
2814 scanning, generation of SPDX standard output, and verification
2815 of license information during the build.
2816 <note>
2817 This class is currently at the prototype stage in the 1.6
2818 release.
2819 </note>
2820 </para>
2821</section>
2822
2823<section id='ref-classes-sstate'>
2824 <title><filename>sstate.bbclass</filename></title>
2825
2826 <para>
2827 The <filename>sstate</filename> class provides support for Shared
2828 State (sstate).
2829 By default, the class is enabled through the
2830 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
2831 variable's default value.
2832 </para>
2833
2834 <para>
2835 For more information on sstate, see the
2836 "<link linkend='shared-state-cache'>Shared State Cache</link>"
2837 section.
2838 </para>
2839</section>
2840
2841<section id='ref-classes-staging'>
2842 <title><filename>staging.bbclass</filename></title>
2843
2844 <para>
2845 The <filename>staging</filename> class provides support for staging
2846 files into the sysroot during the
2847 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
2848 task.
2849 The class is enabled by default because it is inherited by the
2850 <link linkend='ref-classes-base'><filename>base</filename></link>
2851 class.
2852 </para>
2853</section>
2854
2855<section id='ref-classes-syslinux'>
2856 <title><filename>syslinux.bbclass</filename></title>
2857
2858 <para>
2859 The <filename>syslinux</filename> class provides syslinux-specific
2860 functions for building bootable images.
2861 </para>
2862
2863 <para>
2864 The class supports the following variables:
2865 <itemizedlist>
2866 <listitem><para><emphasis><link linkend='var-INITRD'><filename>INITRD</filename></link>:</emphasis>
2867 Indicates a filesystem image to use as an initial RAM disk
2868 (initrd).
2869 This variable is optional.</para></listitem>
2870 <listitem><para><emphasis><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:</emphasis>
2871 Indicates a filesystem image to include as the root filesystem.
2872 This variable is optional.</para></listitem>
2873 <listitem><para><emphasis><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>:</emphasis>
2874 Enables creating an automatic menu when set to "1".
2875 </para></listitem>
2876 <listitem><para><emphasis><link linkend='var-LABELS'><filename>LABELS</filename></link>:</emphasis>
2877 Lists targets for automatic configuration.
2878 </para></listitem>
2879 <listitem><para><emphasis><link linkend='var-APPEND'><filename>APPEND</filename></link>:</emphasis>
2880 Lists append string overrides for each label.
2881 </para></listitem>
2882 <listitem><para><emphasis><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>:</emphasis>
2883 Lists additional options to add to the syslinux file.
2884 Semicolon characters separate multiple options.
2885 </para></listitem>
2886 <listitem><para><emphasis><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>:</emphasis>
2887 Lists a background for the VGA boot menu when you are using the
2888 boot menu.</para></listitem>
2889 <listitem><para><emphasis><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>:</emphasis>
2890 Set to "console=ttyX" to change kernel boot default console.
2891 </para></listitem>
2892 <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>:</emphasis>
2893 Sets an alternate serial port.
2894 Or, turns off serial when the variable is set with an
2895 empty string.</para></listitem>
2896 <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>:</emphasis>
2897 Sets an alternate "console=tty..." kernel boot argument.
2898 </para></listitem>
2899 </itemizedlist>
2900 </para>
2901</section>
2902
2903<section id='ref-classes-systemd'>
2904 <title><filename>systemd.bbclass</filename></title>
2905
2906 <para>
2907 The <filename>systemd</filename> class provides support for recipes
2908 that install systemd unit files.
2909 </para>
2910
2911 <para>
2912 The functionality for this class is disabled unless you have "systemd"
2913 in
2914 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2915 </para>
2916
2917 <para>
2918 Under this class, the recipe or Makefile (i.e. whatever the recipe is
2919 calling during the
2920 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2921 task) installs unit files into
2922 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>.
2923 If the unit files being installed go into packages other than the
2924 main package, you need to set
2925 <link linkend='var-SYSTEMD_PACKAGES'><filename>SYSTEMD_PACKAGES</filename></link>
2926 in your recipe to identify the packages in which the files will be
2927 installed.
2928 </para>
2929
2930 <para>
2931 You should set
2932 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
2933 to the name of the service file.
2934 You should also use a package name override to indicate the package
2935 to which the value applies.
2936 If the value applies to the recipe's main package, use
2937 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>.
2938 Here is an example from the connman recipe:
2939 <literallayout class='monospaced'>
2940 SYSTEMD_SERVICE_${PN} = "connman.service"
2941 </literallayout>
2942 Services are set up to start on boot automatically unless
2943 you have set
2944 <link linkend='var-SYSTEMD_AUTO_ENABLE'><filename>SYSTEMD_AUTO_ENABLE</filename></link>
2945 to "disable".
2946 </para>
2947
2948 <para>
2949 For more information on <filename>systemd</filename>, see the
2950 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager'>Selecting an Initialization Manager</ulink>"
2951 section in the Yocto Project Development Manual.
2952 </para>
2953</section>
2954
2955<section id='ref-classes-terminal'>
2956 <title><filename>terminal.bbclass</filename></title>
2957
2958 <para>
2959 The <filename>terminal</filename> class provides support for starting
2960 a terminal session.
2961 The
2962 <link linkend='var-OE_TERMINAL'><filename>OE_TERMINAL</filename></link>
2963 variable controls which terminal emulator is used for the session.
2964 </para>
2965
2966 <para>
2967 Other classes use the <filename>terminal</filename> class anywhere a
2968 separate terminal session needs to be started.
2969 For example, the
2970 <link linkend='ref-classes-patch'><filename>patch</filename></link>
2971 class assuming
2972 <link linkend='var-PATCHRESOLVE'><filename>PATCHRESOLVE</filename></link>
2973 is set to "user", the
2974 <link linkend='ref-classes-cml1'><filename>cml1</filename></link>
2975 class, and the
2976 <link linkend='ref-classes-devshell'><filename>devshell</filename></link>
2977 class all use the <filename>terminal</filename> class.
2978 </para>
2979</section>
2980
2981<section id='ref-classes-testimage'>
2982 <title><filename>testimage.bbclass</filename></title>
2983
2984 <para>
2985 The <filename>testimage</filename> class supports running automated
2986 tests against images using QEMU and on actual hardware.
2987 The class handles loading the tests and starting the image.
2988 </para>
2989
2990 <para>
2991 To use the class, you need to perform steps to set up the
2992 environment.
2993 The tests are commands that run on the target system over
2994 <filename>ssh</filename>.
2995 they are written in Python and make use of the
2996 <filename>unittest</filename> module.
2997 </para>
2998
2999 <para>
3000 For information on how to enable, run, and create new tests, see the
3001 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
3002 section.
3003 </para>
3004</section>
3005
3006<section id='ref-classes-tinderclient'>
3007 <title><filename>tinderclient.bbclass</filename></title>
3008
3009 <para>
3010 The <filename>tinderclient</filename> class submits build results to
3011 an external Tinderbox instance.
3012 <note>
3013 This class is currently unmaintained.
3014 </note>
3015 </para>
3016</section>
3017
3018<section id='ref-classes-toaster'>
3019 <title><filename>toaster.bbclass</filename></title>
3020
3021 <para>
3022 The <filename>toaster</filename> class collects information about
3023 packages and images and sends them as events that the BitBake
3024 user interface can receive.
3025 The class is enabled when the Toaster user interface is running.
3026 </para>
3027
3028 <para>
3029 This class is not intended to be used directly.
3030 </para>
3031</section>
3032
3033<section id='ref-classes-toolchain-scripts'>
3034 <title><filename>toolchain-scripts.bbclass</filename></title>
3035
3036 <para>
3037 The <filename>toolchain-scripts</filename> class provides the scripts
3038 used for setting up the environment for installed SDKs.
3039 </para>
3040</section>
3041
3042<section id='ref-classes-typecheck'>
3043 <title><filename>typecheck.bbclass</filename></title>
3044
3045 <para>
3046 The <filename>typecheck</filename> class provides support for
3047 validating the values of variables set at the configuration level
3048 against their defined types.
3049 The OpenEmbedded build system allows you to define the type of a
3050 variable using the "type" varflag.
3051 Here is an example:
3052 <literallayout class='monospaced'>
3053 IMAGE_FEATURES[type] = "list"
3054 </literallayout>
3055 </para>
3056</section>
3057
3058<section id='ref-classes-uboot-config'>
3059 <title><filename>uboot-config.bbclass</filename></title>
3060
3061 <para>
3062 The <filename>uboot-config</filename> class provides support for
3063 U-Boot configuration for a machine.
3064 Specify the machine in your recipe as follows:
3065 <literallayout class='monospaced'>
3066 UBOOT_CONFIG ??= &lt;default&gt;
3067 UBOOT_CONFIG[foo] = "config,images"
3068 </literallayout>
3069 You can also specify the machine using this method:
3070 <literallayout class='monospaced'>
3071 UBOOT_MACHINE = "config"
3072 </literallayout>
3073 See the
3074 <link linkend='var-UBOOT_CONFIG'><filename>UBOOT_CONFIG</filename></link>
3075 and
3076 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
3077 variables for additional information.
3078 </para>
3079</section>
3080
3081<section id='ref-classes-update-alternatives'>
3082 <title><filename>update-alternatives.bbclass</filename></title>
3083
3084 <para>
3085 The <filename>update-alternatives</filename> class helps the
3086 alternatives system when multiple sources provide the same command.
3087 This situation occurs when several programs that have the same or
3088 similar function are installed with the same name.
3089 For example, the <filename>ar</filename> command is available from the
3090 <filename>busybox</filename>, <filename>binutils</filename> and
3091 <filename>elfutils</filename> packages.
3092 The <filename>update-alternatives</filename> class handles
3093 renaming the binaries so that multiple packages can be installed
3094 without conflicts.
3095 The <filename>ar</filename> command still works regardless of which
3096 packages are installed or subsequently removed.
3097 The class renames the conflicting binary in each package and symlinks
3098 the highest priority binary during installation or removal of packages.
3099 </para>
3100
3101 <para>
3102 To use this class, you need to define a number of variables:
3103 <itemizedlist>
3104 <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
3105 </para></listitem>
3106 <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
3107 </para></listitem>
3108 <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
3109 </para></listitem>
3110 <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
3111 </para></listitem>
3112 </itemizedlist>
3113 These variables list alternative commands needed by a package,
3114 provide pathnames for links, default links for targets, and
3115 so forth.
3116 For details on how to use this class, see the comments in the
3117 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>.
3118 </para>
3119
3120 <note>
3121 You can use the <filename>update-alternatives</filename> command
3122 directly in your recipes.
3123 However, this class simplifies things in most cases.
3124 </note>
3125</section>
3126
3127<section id='ref-classes-update-rc.d'>
3128 <title><filename>update-rc.d.bbclass</filename></title>
3129
3130 <para>
3131 The <filename>update-rc.d</filename> class uses
3132 <filename>update-rc.d</filename> to safely install an
3133 initialization script on behalf of the package.
3134 The OpenEmbedded build system takes care of details such as making
3135 sure the script is stopped before a package is removed and started when
3136 the package is installed.
3137 </para>
3138
3139 <para>
3140 Three variables control this class:
3141 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
3142 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
3143 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
3144 See the variable links for details.
3145 </para>
3146</section>
3147
3148<section id='ref-classes-useradd'>
3149 <title><filename>useradd.bbclass</filename></title>
3150
3151 <para>
3152 The <filename>useradd</filename> class supports the addition of users
3153 or groups for usage by the package on the target.
3154 For example, if you have packages that contain system services that
3155 should be run under their own user or group, you can use this class to
3156 enable creation of the user or group.
3157 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
3158 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3159 provides a simple example that shows how to add three
3160 users and groups to two packages.
3161 See the <filename>useradd-example.bb</filename> recipe for more
3162 information on how to use this class.
3163 </para>
3164
3165 <para>
3166 The <filename>useradd</filename> class supports the
3167 <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>,
3168 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
3169 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
3170 and
3171 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
3172 variables.
3173 </para>
3174</section>
3175
3176<section id='ref-classes-useradd-staticids'>
3177 <title><filename>useradd-staticids.bbclass</filename></title>
3178
3179 <para>
3180 The <filename>useradd-staticids</filename> class supports the addition
3181 of users or groups that have static user identification
3182 (<filename>uid</filename>) and group identification
3183 (<filename>gid</filename>) values.
3184 </para>
3185
3186 <para>
3187 The default behavior of the OpenEmbedded build system for assigning
3188 <filename>uid</filename> and <filename>gid</filename> values when
3189 packages add users and groups during package install time is to
3190 add them dynamically.
3191 This works fine for programs that do not care what the values of the
3192 resulting users and groups become.
3193 In these cases, the order of the installation determines the final
3194 <filename>uid</filename> and <filename>gid</filename> values.
3195 However, if non-deterministic
3196 <filename>uid</filename> and <filename>gid</filename> values are a
3197 problem, you can override the default, dynamic application of these
3198 values by setting static values.
3199 When you set static values, the OpenEmbedded build system looks in
3200 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
3201 <filename>files/passwd</filename> and <filename>files/group</filename>
3202 files for the values.
3203 </para>
3204
3205 <para>
3206 To use static <filename>uid</filename> and <filename>gid</filename>
3207 values, you need to set some variables.
3208 See the
3209 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
3210 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
3211 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
3212 and
3213 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
3214 variables.
3215 You can also see the
3216 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
3217 class for additional information.
3218 </para>
3219
3220 <note><title>Notes</title>
3221 You do not use this class directly.
3222 You either enable or disable the class by setting the
3223 <filename>USERADDEXTENSION</filename> variable.
3224 If you enable or disable the class in a configured system,
3225 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
3226 might contain incorrect <filename>uid</filename> and
3227 <filename>gid</filename> values.
3228 Deleting the <filename>TMPDIR</filename> directory
3229 will correct this condition.
3230 </note>
3231</section>
3232
3233<section id='ref-classes-utility-tasks'>
3234 <title><filename>utility-tasks.bbclass</filename></title>
3235
3236 <para>
3237 The <filename>utility-tasks</filename> class provides support for
3238 various "utility" type tasks that are applicable to all recipes,
3239 such as
3240 <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and
3241 <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>.
3242 </para>
3243
3244 <para>
3245 This class is enabled by default because it is inherited by
3246 the
3247 <link linkend='ref-classes-base'><filename>base</filename></link>
3248 class.
3249 </para>
3250</section>
3251
3252<section id='ref-classes-utils'>
3253 <title><filename>utils.bbclass</filename></title>
3254
3255 <para>
3256 The <filename>utils</filename> class provides some useful Python
3257 functions that are typically used in inline Python expressions
3258 (e.g. <filename>${@...}</filename>).
3259 One example use is for <filename>bb.utils.contains()</filename>.
3260 </para>
3261
3262 <para>
3263 This class is enabled by default because it is inherited by the
3264 <link linkend='ref-classes-base'><filename>base</filename></link>
3265 class.
3266 </para>
3267</section>
3268
3269<section id='ref-classes-vala'>
3270 <title><filename>vala.bbclass</filename></title>
3271
3272 <para>
3273 The <filename>vala</filename> class supports recipes that need to
3274 build software written using the Vala programming language.
3275 </para>
3276</section>
3277
3278<section id='ref-classes-waf'>
3279 <title><filename>waf.bbclass</filename></title>
3280
3281 <para>
3282 The <filename>waf</filename> class supports recipes that need to build
3283 software that uses the Waf build system.
3284 You can use the
3285 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
3286 variable to specify additional configuration options to be passed on
3287 the Waf command line.
3288 </para>
3289</section>
3290
3291<!-- Undocumented classes are:
3292 image-empty.bbclass (possibly being dropped)
3293 migrate_localcount.bbclass (still need a description)
3294-->
3295
3296
3297</chapter>
3298<!--
3299vim: expandtab tw=80 ts=4
3300-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-10-24 04:29:27 +0000