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