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