blob: ab12373ae0057725e41c84eef7d0242f36dfef12 [file] [log] [blame]
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001<!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; ] >
Andrew Geissler475cb722020-07-10 16:00:51 -05004<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
Patrick Williamsc124f4f2015-09-15 14:41:29 -05005
6<chapter id='ref-classes'>
7<title>Classes</title>
8
9<para>
10 Class files are used to abstract common functionality and share it amongst
11 multiple recipe (<filename>.bb</filename>) files.
12 To use a class file, you simply make sure the recipe inherits the class.
13 In most cases, when a recipe inherits a class it is enough to enable its
14 features.
15 There are cases, however, where in the recipe you might need to set
16 variables or override some default behavior.
17</para>
18
19<para>
Brad Bishopd7bf8c12018-02-25 22:55:05 -050020 Any <link linkend='metadata'>Metadata</link> usually
Patrick Williamsc124f4f2015-09-15 14:41:29 -050021 found in a recipe can also be placed in a class file.
22 Class files are identified by the extension <filename>.bbclass</filename>
23 and are usually placed in a <filename>classes/</filename> directory beneath
24 the <filename>meta*/</filename> directory found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -050025 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050026 Class files can also be pointed to by
27 <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
28 (e.g. <filename>build/</filename>) in the same way as
29 <filename>.conf</filename> files in the <filename>conf</filename> directory.
30 Class files are searched for in
31 <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
32 using the same method by which <filename>.conf</filename> files are
33 searched.
34</para>
35
36<para>
37 This chapter discusses only the most useful and important classes.
38 Other classes do exist within the <filename>meta/classes</filename>
Brad Bishop316dfdd2018-06-25 12:45:53 -040039 directory in the Source Directory.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050040 You can reference the <filename>.bbclass</filename> files directly
41 for more information.
42</para>
43
44<section id='ref-classes-allarch'>
45 <title><filename>allarch.bbclass</filename></title>
46
47 <para>
48 The <filename>allarch</filename> class is inherited
49 by recipes that do not produce architecture-specific output.
50 The class disables functionality that is normally needed for recipes
51 that produce executable binaries (such as building the cross-compiler
52 and a C library as pre-requisites, and splitting out of debug symbols
53 during packaging).
54 <note>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050055 <para>Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes
56 that produce packages that depend on tunings through use of the
Patrick Williamsc124f4f2015-09-15 14:41:29 -050057 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050058 and
Patrick Williamsc124f4f2015-09-15 14:41:29 -050059 <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
Patrick Williamsf1e5d692016-03-30 15:21:19 -050060 variables, should never be configured for all architectures
61 using <filename>allarch</filename>.
62 This is the case even if the recipes do not produce
63 architecture-specific output.</para>
64 <para>Configuring such recipes for all architectures causes the
65 <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
66 tasks to have different signatures for the machines with different
67 tunings.
68 Additionally, unnecessary rebuilds occur every time an
69 image for a different <filename>MACHINE</filename> is built
70 even when the recipe never changes.</para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -050071 </note>
72 </para>
73
74 <para>
75 By default, all recipes inherit the
76 <link linkend='ref-classes-base'><filename>base</filename></link> and
77 <link linkend='ref-classes-package'><filename>package</filename></link>
78 classes, which enable functionality
79 needed for recipes that produce executable output.
80 If your recipe, for example, only produces packages that contain
81 configuration files, media files, or scripts (e.g. Python and Perl),
82 then it should inherit the <filename>allarch</filename> class.
83 </para>
84</section>
85
86<section id='ref-classes-archiver'>
87 <title><filename>archiver.bbclass</filename></title>
88
89 <para>
90 The <filename>archiver</filename> class supports releasing
91 source code and other materials with the binaries.
92 </para>
93
94 <para>
95 For more details on the source archiver, see the
96 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -050097 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -050098 You can also see the
99 <link linkend='var-ARCHIVER_MODE'><filename>ARCHIVER_MODE</filename></link>
100 variable for information about the variable flags (varflags)
101 that help control archive creation.
102 </para>
103</section>
104
105<section id='ref-classes-autotools'>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500106 <title><filename>autotools*.bbclass</filename></title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500107
108 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500109 The <filename>autotools*</filename> classes support Autotooled
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500110 packages.
111 </para>
112
113 <para>
114 The <filename>autoconf</filename>, <filename>automake</filename>,
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500115 and <filename>libtool</filename> packages bring standardization.
116 This class defines a set of tasks (e.g.
117 <filename>configure</filename>, <filename>compile</filename> and
118 so forth) that
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500119 work for all Autotooled packages.
120 It should usually be enough to define a few standard variables
121 and then simply <filename>inherit autotools</filename>.
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500122 These classes can also work with software that emulates Autotools.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500123 For more information, see the
124 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500125 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500126 </para>
127
128 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500129 By default, the <filename>autotools*</filename> classes
130 use out-of-tree builds (i.e.
Brad Bishop316dfdd2018-06-25 12:45:53 -0400131 <filename>autotools.bbclass</filename> building with
132 <filename>B != S</filename>).
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500133 </para>
134
135 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500136 If the software being built by a recipe does not support
137 using out-of-tree builds, you should have the recipe inherit the
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500138 <filename>autotools-brokensep</filename> class.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500139 The <filename>autotools-brokensep</filename> class behaves the same
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500140 as the <filename>autotools</filename> class but builds with
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500141 <link linkend='var-B'><filename>B</filename></link> ==
142 <link linkend='var-S'><filename>S</filename></link>.
143 This method is useful when out-of-tree build support is either not
144 present or is broken.
145 <note>
146 It is recommended that out-of-tree support be fixed and used
147 if at all possible.
148 </note>
149 </para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500150
151 <para>
152 It's useful to have some idea of how the tasks defined by
153 the <filename>autotools*</filename> classes work and what they do
154 behind the scenes.
155 <itemizedlist>
156 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
157 Regenerates the
158 configure script (using <filename>autoreconf</filename>) and
159 then launches it with a standard set of arguments used during
160 cross-compilation.
161 You can pass additional parameters to
162 <filename>configure</filename> through the
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600163 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename>
164 or
165 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
166 variables.
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500167 </para></listitem>
168 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
169 Runs <filename>make</filename> with arguments that specify the
170 compiler and linker.
171 You can pass additional arguments through
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600172 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename>
173 variable.
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500174 </para></listitem>
175 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
176 Runs <filename>make install</filename> and passes in
177 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
178 as <filename>DESTDIR</filename>.
179 </para></listitem>
180 </itemizedlist>
181 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500182</section>
183
184<section id='ref-classes-base'>
185 <title><filename>base.bbclass</filename></title>
186
187 <para>
188 The <filename>base</filename> class is special in that every
189 <filename>.bb</filename> file implicitly inherits the class.
190 This class contains definitions for standard basic
191 tasks such as fetching, unpacking, configuring (empty by default),
192 compiling (runs any <filename>Makefile</filename> present), installing
193 (empty by default) and packaging (empty by default).
194 These classes are often overridden or extended by other classes
195 such as the
196 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
197 class or the
198 <link linkend='ref-classes-package'><filename>package</filename></link>
199 class.
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600200 </para>
201
202 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500203 The class also contains some commonly used functions such as
Patrick Williamsc0f7c042017-02-23 20:41:17 -0600204 <filename>oe_runmake</filename>, which runs
205 <filename>make</filename> with the arguments specified in
206 <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link>
207 variable as well as the arguments passed directly to
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500208 <filename>oe_runmake</filename>.
209 </para>
210</section>
211
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500212<section id='ref-classes-bash-completion'>
213 <title><filename>bash-completion.bbclass</filename></title>
214
215 <para>
216 Sets up packaging and dependencies appropriate for recipes that
217 build software that includes bash-completion data.
218 </para>
219</section>
220
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500221<section id='ref-classes-bin-package'>
222 <title><filename>bin_package.bbclass</filename></title>
223
224 <para>
225 The <filename>bin_package</filename> class is a
226 helper class for recipes that extract the contents of a binary package
227 (e.g. an RPM) and install those contents rather than building the
228 binary from source.
229 The binary package is extracted and new packages in the configured
230 output package format are created.
231 Extraction and installation of proprietary binaries is a good example
232 use for this class.
233 <note>
234 For RPMs and other packages that do not contain a subdirectory,
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500235 you should specify an appropriate fetcher parameter to point to
236 the subdirectory.
237 For example, if BitBake is using the Git fetcher
238 (<filename>git://</filename>), the "subpath" parameter limits
239 the checkout to a specific subpath of the tree.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500240 Here is an example where <filename>${BP}</filename> is used so that
241 the files are extracted into the subdirectory expected by the
242 default value of
243 <link linkend='var-S'><filename>S</filename></link>:
244 <literallayout class='monospaced'>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500245 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500246 </literallayout>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500247 See the
248 "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
249 section in the BitBake User Manual for more information on
250 supported BitBake Fetchers.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500251 </note>
252 </para>
253</section>
254
255<section id='ref-classes-binconfig'>
256 <title><filename>binconfig.bbclass</filename></title>
257
258 <para>
259 The <filename>binconfig</filename> class helps to correct paths in
260 shell scripts.
261 </para>
262
263 <para>
264 Before <filename>pkg-config</filename> had become widespread, libraries
265 shipped shell scripts to give information about the libraries and
266 include paths needed to build software (usually named
267 <filename>LIBNAME-config</filename>).
268 This class assists any recipe using such scripts.
269 </para>
270
271 <para>
272 During staging, the OpenEmbedded build system installs such scripts
273 into the <filename>sysroots/</filename> directory.
274 Inheriting this class results in all paths in these scripts being
275 changed to point into the <filename>sysroots/</filename> directory so
276 that all builds that use the script use the correct directories
277 for the cross compiling layout.
278 See the
279 <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
280 variable for more information.
281 </para>
282</section>
283
284<section id='ref-classes-binconfig-disabled'>
285 <title><filename>binconfig-disabled.bbclass</filename></title>
286
287 <para>
288 An alternative version of the
289 <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
290 class, which disables binary configuration scripts by making them
291 return an error in favor of using <filename>pkg-config</filename>
292 to query the information.
293 The scripts to be disabled should be specified using the
294 <link linkend='var-BINCONFIG'><filename>BINCONFIG</filename></link>
295 variable within the recipe inheriting the class.
296 </para>
297</section>
298
299<section id='ref-classes-blacklist'>
300 <title><filename>blacklist.bbclass</filename></title>
301
302 <para>
303 The <filename>blacklist</filename> class prevents
304 the OpenEmbedded build system from building specific recipes
305 (blacklists them).
306 To use this class, inherit the class globally and set
307 <link linkend='var-PNBLACKLIST'><filename>PNBLACKLIST</filename></link>
308 for each recipe you wish to blacklist.
309 Specify the <link linkend='var-PN'><filename>PN</filename></link>
310 value as a variable flag (varflag) and provide a reason, which is
311 reported, if the package is requested to be built as the value.
312 For example, if you want to blacklist a recipe called "exoticware",
313 you add the following to your <filename>local.conf</filename>
314 or distribution configuration:
315 <literallayout class='monospaced'>
316 INHERIT += "blacklist"
317 PNBLACKLIST[exoticware] = "Not supported by our organization."
318 </literallayout>
319 </para>
320</section>
321
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500322<section id='ref-classes-buildhistory'>
323 <title><filename>buildhistory.bbclass</filename></title>
324
325 <para>
326 The <filename>buildhistory</filename> class records a
327 history of build output metadata, which can be used to detect possible
328 regressions as well as used for analysis of the build output.
329 For more information on using Build History, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400330 "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
331 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500332 </para>
333</section>
334
335<section id='ref-classes-buildstats'>
336 <title><filename>buildstats.bbclass</filename></title>
337
338 <para>
339 The <filename>buildstats</filename> class records
340 performance statistics about each task executed during the build
341 (e.g. elapsed time, CPU usage, and I/O usage).
342 </para>
343
344 <para>
345 When you use this class, the output goes into the
346 <link linkend='var-BUILDSTATS_BASE'><filename>BUILDSTATS_BASE</filename></link>
347 directory, which defaults to <filename>${TMPDIR}/buildstats/</filename>.
348 You can analyze the elapsed time using
349 <filename>scripts/pybootchartgui/pybootchartgui.py</filename>, which
350 produces a cascading chart of the entire build process and can be
351 useful for highlighting bottlenecks.
352 </para>
353
354 <para>
355 Collecting build statistics is enabled by default through the
356 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
357 variable from your <filename>local.conf</filename> file.
358 Consequently, you do not have to do anything to enable the class.
359 However, if you want to disable the class, simply remove "buildstats"
360 from the <filename>USER_CLASSES</filename> list.
361 </para>
362</section>
363
364<section id='ref-classes-buildstats-summary'>
365 <title><filename>buildstats-summary.bbclass</filename></title>
366
367 <para>
368 When inherited globally, prints statistics at the end of the build
369 on sstate re-use.
370 In order to function, this class requires the
371 <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
372 class be enabled.
373 </para>
374</section>
375
376<section id='ref-classes-ccache'>
377 <title><filename>ccache.bbclass</filename></title>
378
379 <para>
Brad Bishop316dfdd2018-06-25 12:45:53 -0400380 The <filename>ccache</filename> class enables the C/C++ Compiler Cache
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500381 for the build.
382 This class is used to give a minor performance boost during the build.
383 However, using the class can lead to unexpected side-effects.
384 Thus, it is recommended that you do not use this class.
385 See <ulink url='http://ccache.samba.org/'></ulink> for information on
386 the C/C++ Compiler Cache.
387 </para>
388</section>
389
390<section id='ref-classes-chrpath'>
391 <title><filename>chrpath.bbclass</filename></title>
392
393 <para>
394 The <filename>chrpath</filename> class
395 is a wrapper around the "chrpath" utility, which is used during the
396 build process for <filename>nativesdk</filename>,
397 <filename>cross</filename>, and
398 <filename>cross-canadian</filename> recipes to change
399 <filename>RPATH</filename> records within binaries in order to make
400 them relocatable.
401 </para>
402</section>
403
404<section id='ref-classes-clutter'>
405 <title><filename>clutter.bbclass</filename></title>
406
407 <para>
408 The <filename>clutter</filename> class consolidates the
409 major and minor version naming and other common items used by Clutter
410 and related recipes.
411 <note>
412 Unlike some other classes related to specific libraries, recipes
413 building other software that uses Clutter do not need to
414 inherit this class unless they use the same recipe versioning
415 scheme that the Clutter and related recipes do.
416 </note>
417 </para>
418</section>
419
420<section id='ref-classes-cmake'>
421 <title><filename>cmake.bbclass</filename></title>
422
423 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800424 The <filename>cmake</filename> class allows for recipes that need to
425 build software using the
426 <ulink url='https://cmake.org/overview/'>CMake</ulink> build system.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500427 You can use the
428 <link linkend='var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></link>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800429 variable to specify additional configuration options to be passed
430 using the <filename>cmake</filename> command line.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500431 </para>
Brad Bishop64c979e2019-11-04 13:55:29 -0500432
433 <para>
434 On the occasion that you would be installing custom CMake toolchain
435 files supplied by the application being built, you should install them
436 to the preferred CMake Module directory:
437 <filename>${D}${datadir}/cmake/</filename> Modules during
438 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>.
439 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500440</section>
441
442<section id='ref-classes-cml1'>
443 <title><filename>cml1.bbclass</filename></title>
444
445 <para>
446 The <filename>cml1</filename> class provides basic support for the
447 Linux kernel style build configuration system.
448 </para>
449</section>
450
451<section id='ref-classes-compress_doc'>
452 <title><filename>compress_doc.bbclass</filename></title>
453
454 <para>
455 Enables compression for man pages and info pages.
456 This class is intended to be inherited globally.
457 The default compression mechanism is gz (gzip) but you can
458 select an alternative mechanism by setting the
459 <link linkend='var-DOC_COMPRESS'><filename>DOC_COMPRESS</filename></link>
460 variable.
461 </para>
462</section>
463
464<section id='ref-classes-copyleft_compliance'>
465 <title><filename>copyleft_compliance.bbclass</filename></title>
466
467 <para>
468 The <filename>copyleft_compliance</filename> class
469 preserves source code for the purposes of license compliance.
470 This class is an alternative to the <filename>archiver</filename>
471 class and is still used by some users even though it has been
472 deprecated in favor of the
473 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
474 class.
475 </para>
476</section>
477
478<section id='ref-classes-copyleft_filter'>
479 <title><filename>copyleft_filter.bbclass</filename></title>
480
481 <para>
482 A class used by the
483 <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
484 and
485 <link linkend='ref-classes-copyleft_compliance'><filename>copyleft_compliance</filename></link>
486 classes for filtering licenses.
487 The <filename>copyleft_filter</filename> class is an internal class
488 and is not intended to be used directly.
489 </para>
490</section>
491
492<section id='ref-classes-core-image'>
493 <title><filename>core-image.bbclass</filename></title>
494
495 <para>
496 The <filename>core-image</filename> class
497 provides common definitions for the
498 <filename>core-image-*</filename> image recipes, such as support for
499 additional
500 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
501 </para>
502</section>
503
504<section id='ref-classes-cpan'>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500505 <title><filename>cpan*.bbclass</filename></title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500506
507 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500508 The <filename>cpan*</filename> classes support Perl modules.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500509 </para>
510
511 <para>
512 Recipes for Perl modules are simple.
513 These recipes usually only need to point to the source's archive and
514 then inherit the proper class file.
515 Building is split into two methods depending on which method the module
516 authors used.
517 <itemizedlist>
518 <listitem><para>Modules that use old
519 <filename>Makefile.PL</filename>-based build system require
520 <filename>cpan.bbclass</filename> in their recipes.
521 </para></listitem>
522 <listitem><para>Modules that use
523 <filename>Build.PL</filename>-based build system require
524 using <filename>cpan_build.bbclass</filename> in their recipes.
525 </para></listitem>
526 </itemizedlist>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500527 Both build methods inherit the <filename>cpan-base</filename> class
528 for basic Perl support.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500529 </para>
530</section>
531
532<section id='ref-classes-cross'>
533 <title><filename>cross.bbclass</filename></title>
534
535 <para>
536 The <filename>cross</filename> class provides support for the recipes
537 that build the cross-compilation tools.
538 </para>
539</section>
540
541<section id='ref-classes-cross-canadian'>
542 <title><filename>cross-canadian.bbclass</filename></title>
543
544 <para>
545 The <filename>cross-canadian</filename> class
546 provides support for the recipes that build the Canadian
547 Cross-compilation tools for SDKs.
548 See the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400549 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
550 section in the Yocto Project Overview and Concepts Manual for more
551 discussion on these cross-compilation tools.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500552 </para>
553</section>
554
555<section id='ref-classes-crosssdk'>
556 <title><filename>crosssdk.bbclass</filename></title>
557
558 <para>
559 The <filename>crosssdk</filename> class
560 provides support for the recipes that build the cross-compilation
561 tools used for building SDKs.
562 See the
Brad Bishop316dfdd2018-06-25 12:45:53 -0400563 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
564 section in the Yocto Project Overview and Concepts Manual for more
565 discussion on these cross-compilation tools.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500566 </para>
567</section>
568
569<section id='ref-classes-debian'>
570 <title><filename>debian.bbclass</filename></title>
571
572 <para>
573 The <filename>debian</filename> class renames output packages so that
574 they follow the Debian naming policy (i.e. <filename>glibc</filename>
575 becomes <filename>libc6</filename> and <filename>glibc-devel</filename>
576 becomes <filename>libc6-dev</filename>.)
577 Renaming includes the library name and version as part of the package
578 name.
579 </para>
580
581 <para>
582 If a recipe creates packages for multiple libraries
583 (shared object files of <filename>.so</filename> type), use the
584 <link linkend='var-LEAD_SONAME'><filename>LEAD_SONAME</filename></link>
585 variable in the recipe to specify the library on which to apply the
586 naming scheme.
587 </para>
588</section>
589
590<section id='ref-classes-deploy'>
591 <title><filename>deploy.bbclass</filename></title>
592
593 <para>
594 The <filename>deploy</filename> class handles deploying files
595 to the
596 <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
597 directory.
598 The main function of this class is to allow the deploy step to be
599 accelerated by shared state.
600 Recipes that inherit this class should define their own
601 <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
602 function to copy the files to be deployed to
603 <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>,
604 and use <filename>addtask</filename> to add the task at the appropriate
605 place, which is usually after
606 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
607 or
608 <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
609 The class then takes care of staging the files from
610 <filename>DEPLOYDIR</filename> to
611 <filename>DEPLOY_DIR_IMAGE</filename>.
612 </para>
613</section>
614
615<section id='ref-classes-devshell'>
616 <title><filename>devshell.bbclass</filename></title>
617
618 <para>
619 The <filename>devshell</filename> class adds the
620 <filename>do_devshell</filename> task.
621 Distribution policy dictates whether to include this class.
622 See the
623 "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500624 in the Yocto Project Development Tasks Manual for more information about
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500625 using <filename>devshell</filename>.
626 </para>
627</section>
628
Brad Bishop1a4b7ee2018-12-16 17:11:34 -0800629<section id='ref-classes-devupstream'>
630 <title><filename>devupstream.bbclass</filename></title>
631
632 <para>
633 The <filename>devupstream</filename> class uses
634 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
635 to add a variant of the recipe that fetches from an alternative URI
636 (e.g. Git) instead of a tarball.
637 Following is an example:
638 <literallayout class='monospaced'>
639 BBCLASSEXTEND = "devupstream:target"
640 SRC_URI_class-devupstream = "git://git.example.com/example"
641 SRCREV_class-devupstream = "abcd1234"
642 </literallayout>
643 Adding the above statements to your recipe creates a variant that has
644 <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
645 set to "-1".
646 Consequently, you need to select the variant of the recipe to use it.
647 Any development-specific adjustments can be done by using the
648 <filename>class-devupstream</filename> override.
649 Here is an example:
650 <literallayout class='monospaced'>
651 DEPENDS_append_class-devupstream = " gperf-native"
652
653 do_configure_prepend_class-devupstream() {
654 touch ${S}/README
655 }
656 </literallayout>
657 The class currently only supports creating a development variant of
658 the target recipe, not <filename>native</filename> or
659 <filename>nativesdk</filename> variants.
660 </para>
661
662 <para>
663 The <filename>BBCLASSEXTEND</filename> syntax
664 (i.e. <filename>devupstream:target</filename>) provides support for
665 <filename>native</filename> and <filename>nativesdk</filename>
666 variants.
667 Consequently, this functionality can be added in a future release.
668 </para>
669
670 <para>
671 Support for other version control systems such as Subversion is
672 limited due to BitBake's automatic fetch dependencies (e.g.
673 <filename>subversion-native</filename>).
674 </para>
675</section>
676
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500677<section id='ref-classes-distro_features_check'>
678 <title><filename>distro_features_check.bbclass</filename></title>
679
680 <para>
681 The <filename>distro_features_check</filename> class
682 allows individual recipes to check for required and conflicting
683 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
684 </para>
685
686 <para>
687 This class provides support for the
688 <link linkend='var-REQUIRED_DISTRO_FEATURES'><filename>REQUIRED_DISTRO_FEATURES</filename></link>
689 and
690 <link linkend='var-CONFLICT_DISTRO_FEATURES'><filename>CONFLICT_DISTRO_FEATURES</filename></link>
691 variables.
692 If any conditions specified in the recipe using the above variables are
693 not met, the recipe will be skipped.
694 </para>
695</section>
696
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500697<section id='ref-classes-distutils'>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500698 <title><filename>distutils*.bbclass</filename></title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500699
700 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500701 The <filename>distutils*</filename> classes support recipes for Python
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500702 version 2.x extensions, which are simple.
703 These recipes usually only need to point to the source's archive and
704 then inherit the proper class.
705 Building is split into two methods depending on which method the
706 module authors used.
707 <itemizedlist>
708 <listitem><para>Extensions that use an Autotools-based build system
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500709 require Autotools and the classes based on
710 <filename>distutils</filename> in their recipes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500711 </para></listitem>
712 <listitem><para>Extensions that use build systems based on
713 <filename>distutils</filename> require
714 the <filename>distutils</filename> class in their recipes.
715 </para></listitem>
716 <listitem><para>Extensions that use build systems based on
717 <filename>setuptools</filename> require the
718 <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
719 class in their recipes.
720 </para></listitem>
721 </itemizedlist>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500722 The <filename>distutils-common-base</filename> class is required by
723 some of the <filename>distutils*</filename> classes to provide common
724 Python2 support.
725 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500726</section>
727
728<section id='ref-classes-distutils3'>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500729 <title><filename>distutils3*.bbclass</filename></title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500730
731 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500732 The <filename>distutils3*</filename> classes support recipes for Python
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500733 version 3.x extensions, which are simple.
734 These recipes usually only need to point to the source's archive and
735 then inherit the proper class.
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500736 Building is split into three methods depending on which method the
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500737 module authors used.
738 <itemizedlist>
739 <listitem><para>Extensions that use an Autotools-based build system
740 require Autotools and
741 <filename>distutils</filename>-based classes in their recipes.
742 </para></listitem>
743 <listitem><para>Extensions that use
744 <filename>distutils</filename>-based build systems require
745 the <filename>distutils</filename> class in their recipes.
746 </para></listitem>
747 <listitem><para>Extensions that use build systems based on
748 <filename>setuptools3</filename> require the
749 <link linkend='ref-classes-setuptools'><filename>setuptools3</filename></link>
750 class in their recipes.
751 </para></listitem>
752 </itemizedlist>
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500753 The <filename>distutils3*</filename> classes either inherit their
754 corresponding <filename>distutils*</filename> class or replicate them
755 using a Python3 version instead (e.g.
756 <filename>distutils3-base</filename> inherits
757 <filename>distutils-common-base</filename>, which is the same as
758 <filename>distutils-base</filename> but inherits
759 <filename>python3native</filename> instead of
760 <filename>pythonnative</filename>).
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500761 </para>
762</section>
763
764<section id='ref-classes-externalsrc'>
765 <title><filename>externalsrc.bbclass</filename></title>
766
767 <para>
768 The <filename>externalsrc</filename> class supports building software
769 from source code that is external to the OpenEmbedded build system.
770 Building software from an external source tree means that the build
771 system's normal fetch, unpack, and patch process is not used.
772 </para>
773
774 <para>
775 By default, the OpenEmbedded build system uses the
776 <link linkend='var-S'><filename>S</filename></link> and
777 <link linkend='var-B'><filename>B</filename></link> variables to
778 locate unpacked recipe source code and to build it, respectively.
779 When your recipe inherits the <filename>externalsrc</filename> class,
780 you use the
781 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
782 and
783 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
784 variables to ultimately define <filename>S</filename> and
785 <filename>B</filename>.
786 </para>
787
788 <para>
789 By default, this class expects the source code to support recipe builds
790 that use the <link linkend='var-B'><filename>B</filename></link>
791 variable to point to the directory in which the OpenEmbedded build
792 system places the generated objects built from the recipes.
793 By default, the <filename>B</filename> directory is set to the
794 following, which is separate from the source directory
795 (<filename>S</filename>):
796 <literallayout class='monospaced'>
797 ${WORKDIR}/${BPN}/{PV}/
798 </literallayout>
799 See these variables for more information:
800 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
801 <link linkend='var-BPN'><filename>BPN</filename></link>, and
802 <link linkend='var-PV'><filename>PV</filename></link>,
803 </para>
804
805 <para>
806 For more information on the
807 <filename>externalsrc</filename> class, see the comments in
808 <filename>meta/classes/externalsrc.bbclass</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500809 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500810 For information on how to use the <filename>externalsrc</filename>
811 class, see the
812 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -0500813 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500814 </para>
815</section>
816
817<section id='ref-classes-extrausers'>
818 <title><filename>extrausers.bbclass</filename></title>
819
820 <para>
821 The <filename>extrausers</filename> class allows
822 additional user and group configuration to be applied at the image
823 level.
824 Inheriting this class either globally or from an image recipe allows
825 additional user and group operations to be performed using the
826 <link linkend='var-EXTRA_USERS_PARAMS'><filename>EXTRA_USERS_PARAMS</filename></link>
827 variable.
828 <note>
829 The user and group operations added using the
830 <filename>extrausers</filename> class are not tied to a specific
831 recipe outside of the recipe for the image.
832 Thus, the operations can be performed across the image as a whole.
833 Use the
834 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
835 class to add user and group configuration to a specific recipe.
836 </note>
837 Here is an example that uses this class in an image recipe:
838 <literallayout class='monospaced'>
839 inherit extrausers
840 EXTRA_USERS_PARAMS = "\
841 useradd -p '' tester; \
842 groupadd developers; \
843 userdel nobody; \
844 groupdel -g video; \
845 groupmod -g 1020 developers; \
846 usermod -s /bin/sh tester; \
847 "
848 </literallayout>
849 Here is an example that adds two users named "tester-jim" and
850 "tester-sue" and assigns passwords:
851 <literallayout class='monospaced'>
852 inherit extrausers
853 EXTRA_USERS_PARAMS = "\
854 useradd -P tester01 tester-jim; \
855 useradd -P tester01 tester-sue; \
856 "
857 </literallayout>
858 Finally, here is an example that sets the root password to
859 "1876*18":
860 <literallayout class='monospaced'>
861 inherit extrausers
862 EXTRA_USERS_PARAMS = "\
863 usermod -P 1876*18 root; \
864 "
865 </literallayout>
866 </para>
867</section>
868
869<section id='ref-classes-fontcache'>
870 <title><filename>fontcache.bbclass</filename></title>
871
872 <para>
873 The <filename>fontcache</filename> class generates the
874 proper post-install and post-remove (postinst and postrm)
875 scriptlets for font packages.
876 These scriptlets call <filename>fc-cache</filename> (part of
877 <filename>Fontconfig</filename>) to add the fonts to the font
878 information cache.
879 Since the cache files are architecture-specific,
880 <filename>fc-cache</filename> runs using QEMU if the postinst
881 scriptlets need to be run on the build host during image creation.
882 </para>
883
884 <para>
885 If the fonts being installed are in packages other than the main
886 package, set
887 <link linkend='var-FONT_PACKAGES'><filename>FONT_PACKAGES</filename></link>
888 to specify the packages containing the fonts.
889 </para>
890</section>
891
Patrick Williamsf1e5d692016-03-30 15:21:19 -0500892<section id='ref-classes-fs-uuid'>
893 <title><filename>fs-uuid.bbclass</filename></title>
894
895 <para>
896 The <filename>fs-uuid</filename> class extracts UUID from
897 <filename>${</filename><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link><filename>}</filename>,
898 which must have been built by the time that this function gets called.
899 The <filename>fs-uuid</filename> class only works on
900 <filename>ext</filename> file systems and depends on
901 <filename>tune2fs</filename>.
902 </para>
903</section>
904
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500905<section id='ref-classes-gconf'>
906 <title><filename>gconf.bbclass</filename></title>
907
908 <para>
909 The <filename>gconf</filename> class provides common
910 functionality for recipes that need to install GConf schemas.
911 The schemas will be put into a separate package
912 (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-gconf</filename>)
913 that is created automatically when this class is inherited.
914 This package uses the appropriate post-install and post-remove
915 (postinst/postrm) scriptlets to register and unregister the schemas
916 in the target image.
917 </para>
918</section>
919
920<section id='ref-classes-gettext'>
921 <title><filename>gettext.bbclass</filename></title>
922
923 <para>
924 The <filename>gettext</filename> class provides support for
925 building software that uses the GNU <filename>gettext</filename>
926 internationalization and localization system.
927 All recipes building software that use
928 <filename>gettext</filename> should inherit this class.
929 </para>
930</section>
931
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500932<section id='ref-classes-gnomebase'>
933 <title><filename>gnomebase.bbclass</filename></title>
934
935 <para>
936 The <filename>gnomebase</filename> class is the base
937 class for recipes that build software from the GNOME stack.
938 This class sets
939 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> to
940 download the source from the GNOME mirrors as well as extending
941 <link linkend='var-FILES'><filename>FILES</filename></link>
942 with the typical GNOME installation paths.
943 </para>
944</section>
945
Patrick Williamsd8c66bc2016-06-20 12:57:21 -0500946<section id='ref-classes-gobject-introspection'>
947 <title><filename>gobject-introspection.bbclass</filename></title>
948
949 <para>
950 Provides support for recipes building software that
951 supports GObject introspection.
952 This functionality is only enabled if the
953 "gobject-introspection-data" feature is in
954 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
955 as well as "qemu-usermode" being in
956 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
957 <note>
958 This functionality is backfilled by default and,
959 if not applicable, should be disabled through
960 <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
961 or
962 <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>,
963 respectively.
964 </note>
965 </para>
966</section>
967
Patrick Williamsc124f4f2015-09-15 14:41:29 -0500968<section id='ref-classes-grub-efi'>
969 <title><filename>grub-efi.bbclass</filename></title>
970
971 <para>
972 The <filename>grub-efi</filename>
973 class provides <filename>grub-efi</filename>-specific functions for
974 building bootable images.
975 </para>
976
977 <para>
978 This class supports several variables:
979 <itemizedlist>
980 <listitem><para>
981 <link linkend='var-INITRD'><filename>INITRD</filename></link>:
982 Indicates list of filesystem images to concatenate and use
983 as an initial RAM disk (initrd) (optional).
984 </para></listitem>
985 <listitem><para>
986 <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
987 Indicates a filesystem image to include as the root filesystem
988 (optional).</para></listitem>
989 <listitem><para>
990 <link linkend='var-GRUB_GFXSERIAL'><filename>GRUB_GFXSERIAL</filename></link>:
991 Set this to "1" to have graphics and serial in the boot menu.
992 </para></listitem>
993 <listitem><para>
994 <link linkend='var-LABELS'><filename>LABELS</filename></link>:
995 A list of targets for the automatic configuration.
996 </para></listitem>
997 <listitem><para>
998 <link linkend='var-APPEND'><filename>APPEND</filename></link>:
999 An override list of append strings for each
1000 <filename>LABEL</filename>.
1001 </para></listitem>
1002 <listitem><para>
1003 <link linkend='var-GRUB_OPTS'><filename>GRUB_OPTS</filename></link>:
1004 Additional options to add to the configuration (optional).
1005 Options are delimited using semi-colon characters
1006 (<filename>;</filename>).</para></listitem>
1007 <listitem><para>
1008 <link linkend='var-GRUB_TIMEOUT'><filename>GRUB_TIMEOUT</filename></link>:
1009 Timeout before executing the default <filename>LABEL</filename>
1010 (optional).
1011 </para></listitem>
1012 </itemizedlist>
1013 </para>
1014</section>
1015
1016<section id='ref-classes-gsettings'>
1017 <title><filename>gsettings.bbclass</filename></title>
1018
1019 <para>
1020 The <filename>gsettings</filename> class
1021 provides common functionality for recipes that need to install
1022 GSettings (glib) schemas.
1023 The schemas are assumed to be part of the main package.
1024 Appropriate post-install and post-remove (postinst/postrm)
1025 scriptlets are added to register and unregister the schemas in the
1026 target image.
1027 </para>
1028</section>
1029
1030<section id='ref-classes-gtk-doc'>
1031 <title><filename>gtk-doc.bbclass</filename></title>
1032
1033 <para>
1034 The <filename>gtk-doc</filename> class
1035 is a helper class to pull in the appropriate
1036 <filename>gtk-doc</filename> dependencies and disable
1037 <filename>gtk-doc</filename>.
1038 </para>
1039</section>
1040
1041<section id='ref-classes-gtk-icon-cache'>
1042 <title><filename>gtk-icon-cache.bbclass</filename></title>
1043
1044 <para>
1045 The <filename>gtk-icon-cache</filename> class
1046 generates the proper post-install and post-remove (postinst/postrm)
1047 scriptlets for packages that use GTK+ and install icons.
1048 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
1049 the fonts to GTK+'s icon cache.
1050 Since the cache files are architecture-specific,
1051 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
1052 postinst scriptlets need to be run on the build host during image
1053 creation.
1054 </para>
1055</section>
1056
1057<section id='ref-classes-gtk-immodules-cache'>
1058 <title><filename>gtk-immodules-cache.bbclass</filename></title>
1059
1060 <para>
1061 The <filename>gtk-immodules-cache</filename> class
1062 generates the proper post-install and post-remove (postinst/postrm)
1063 scriptlets for packages that install GTK+ input method modules for
1064 virtual keyboards.
1065 These scriptlets call <filename>gtk-update-icon-cache</filename> to add
1066 the input method modules to the cache.
1067 Since the cache files are architecture-specific,
1068 <filename>gtk-update-icon-cache</filename> is run using QEMU if the
1069 postinst scriptlets need to be run on the build host during image
1070 creation.
1071 </para>
1072
1073 <para>
1074 If the input method modules being installed are in packages other than
1075 the main package, set
1076 <link linkend='var-GTKIMMODULES_PACKAGES'><filename>GTKIMMODULES_PACKAGES</filename></link>
1077 to specify the packages containing the modules.
1078 </para>
1079</section>
1080
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001081<section id='ref-classes-gzipnative'>
1082 <title><filename>gzipnative.bbclass</filename></title>
1083
1084 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05001085 The <filename>gzipnative</filename> class enables the use of
1086 different native versions of <filename>gzip</filename>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001087 and <filename>pigz</filename> rather than the versions of these tools
1088 from the build host.
1089 </para>
1090</section>
1091
1092<section id='ref-classes-icecc'>
1093 <title><filename>icecc.bbclass</filename></title>
1094
1095 <para>
1096 The <filename>icecc</filename> class supports
1097 <ulink url='https://github.com/icecc/icecream'>Icecream</ulink>, which
1098 facilitates taking compile jobs and distributing them among remote
1099 machines.
1100 </para>
1101
1102 <para>
1103 The class stages directories with symlinks from <filename>gcc</filename>
1104 and <filename>g++</filename> to <filename>icecc</filename>, for both
1105 native and cross compilers.
1106 Depending on each configure or compile, the OpenEmbedded build system
1107 adds the directories at the head of the <filename>PATH</filename> list
1108 and then sets the <filename>ICECC_CXX</filename> and
1109 <filename>ICEC_CC</filename> variables, which are the paths to the
1110 <filename>g++</filename> and <filename>gcc</filename> compilers,
1111 respectively.
1112 </para>
1113
1114 <para>
1115 For the cross compiler, the class creates a <filename>tar.gz</filename>
1116 file that contains the Yocto Project toolchain and sets
1117 <filename>ICECC_VERSION</filename>, which is the version of the
1118 cross-compiler used in the cross-development toolchain, accordingly.
1119 </para>
1120
1121 <para>
1122 The class handles all three different compile stages
1123 (i.e native ,cross-kernel and target) and creates the necessary
1124 environment <filename>tar.gz</filename> file to be used by the remote
1125 machines.
1126 The class also supports SDK generation.
1127 </para>
1128
1129 <para>
1130 If <link linkend='var-ICECC_PATH'><filename>ICECC_PATH</filename></link>
1131 is not set in your <filename>local.conf</filename> file, then the
1132 class tries to locate the <filename>icecc</filename> binary
1133 using <filename>which</filename>.
1134
1135 If
1136 <link linkend='var-ICECC_ENV_EXEC'><filename>ICECC_ENV_EXEC</filename></link>
1137 is set in your <filename>local.conf</filename> file, the variable should
1138 point to the <filename>icecc-create-env</filename> script
1139 provided by the user.
1140 If you do not point to a user-provided script, the build system
1141 uses the default script provided by the recipe
1142 <filename>icecc-create-env-native.bb</filename>.
1143 <note>
1144 This script is a modified version and not the one that comes with
1145 <filename>icecc</filename>.
1146 </note>
1147 </para>
1148
1149 <para>
1150 If you do not want the Icecream distributed compile support to apply
1151 to specific recipes or classes, you can effectively "blacklist" them
1152 by listing the recipes and classes using the
1153 <link linkend='var-ICECC_USER_PACKAGE_BL'><filename>ICECC_USER_PACKAGE_BL</filename></link>
1154 and
1155 <link linkend='var-ICECC_USER_CLASS_BL'><filename>ICECC_USER_CLASS_BL</filename></link>,
1156 variables, respectively, in your <filename>local.conf</filename> file.
1157 Doing so causes the OpenEmbedded build system to handle these
1158 compilations locally.
1159 </para>
1160
1161 <para>
1162 Additionally, you can list recipes using the
1163 <link linkend='var-ICECC_USER_PACKAGE_WL'><filename>ICECC_USER_PACKAGE_WL</filename></link>
1164 variable in your <filename>local.conf</filename> file to force
1165 <filename>icecc</filename> to be enabled for recipes using an empty
1166 <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
1167 variable.
1168 </para>
1169
1170 <para>
1171 Inheriting the <filename>icecc</filename> class changes all sstate
1172 signatures.
1173 Consequently, if a development team has a dedicated build system
1174 that populates
1175 <link linkend='var-SSTATE_MIRRORS'><filename>STATE_MIRRORS</filename></link>
1176 and they want to reuse sstate from
1177 <filename>STATE_MIRRORS</filename>, then all developers and the
1178 build system need to either inherit the <filename>icecc</filename>
1179 class or nobody should.
1180 </para>
1181
1182 <para>
1183 At the distribution level, you can inherit the
1184 <filename>icecc</filename> class to be sure that all builders start
1185 with the same sstate signatures.
1186 After inheriting the class, you can then disable the feature by setting
1187 the
1188 <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link>
1189 variable to "1" as follows:
1190 <literallayout class='monospaced'>
1191 INHERIT_DISTRO_append = " icecc"
1192 ICECC_DISABLED ??= "1"
1193 </literallayout>
1194 This practice makes sure everyone is using the same signatures but also
1195 requires individuals that do want to use Icecream to enable the feature
1196 individually as follows in your <filename>local.conf</filename> file:
1197 <literallayout class='monospaced'>
1198 ICECC_DISABLED = ""
1199 </literallayout>
1200 </para>
1201</section>
1202
1203<section id='ref-classes-image'>
1204 <title><filename>image.bbclass</filename></title>
1205
1206 <para>
1207 The <filename>image</filename> class helps support creating images
1208 in different formats.
1209 First, the root filesystem is created from packages using
1210 one of the <filename>rootfs*.bbclass</filename>
1211 files (depending on the package format used) and then one or more image
1212 files are created.
1213 <itemizedlist>
1214 <listitem><para>The
1215 <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
1216 variable controls the types of images to generate.
1217 </para></listitem>
1218 <listitem><para>The
1219 <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
1220 variable controls the list of packages to install into the
1221 image.</para></listitem>
1222 </itemizedlist>
1223 For information on customizing images, see the
1224 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001225 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001226 For information on how images are created, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04001227 "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
1228 section in the Yocto Project Overview and Concpets Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001229 </para>
1230</section>
1231
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001232<section id='ref-classes-image-buildinfo'>
1233 <title><filename>image-buildinfo.bbclass</filename></title>
1234
1235 <para>
1236 The <filename>image-buildinfo</filename> class writes information
1237 to the target filesystem on <filename>/etc/build</filename>.
1238 </para>
1239</section>
1240
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001241<section id='ref-classes-image_types'>
1242 <title><filename>image_types.bbclass</filename></title>
1243
1244 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001245 The <filename>image_types</filename> class defines all of the
1246 standard image output types that you can enable through the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001247 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1248 variable.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001249 You can use this class as a reference on how to add support for
1250 custom image output types.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001251 </para>
1252
1253 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001254 By default, the
1255 <link linkend='ref-classes-image'><filename>image</filename></link>
1256 class automatically enables the <filename>image_types</filename> class.
1257 The <filename>image</filename> class uses the
1258 <filename>IMGCLASSES</filename> variable as follows:
1259 <literallayout class='monospaced'>
1260 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
1261 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
1262 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
1263 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
1264 IMGCLASSES += "image_types_wic"
1265 IMGCLASSES += "rootfs-postcommands"
1266 IMGCLASSES += "image-postinst-intercepts"
1267 inherit ${IMGCLASSES}
1268 </literallayout>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001269 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001270
1271 <para>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08001272 The <filename>image_types</filename> class also handles conversion and
1273 compression of images.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001274 <note>
1275 To build a VMware VMDK image, you need to add "wic.vmdk" to
Brad Bishop316dfdd2018-06-25 12:45:53 -04001276 <filename>IMAGE_FSTYPES</filename>.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001277 This would also be similar for Virtual Box Virtual Disk Image
1278 ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
1279 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001280 </para>
1281</section>
1282
1283<section id='ref-classes-image-live'>
1284 <title><filename>image-live.bbclass</filename></title>
1285
1286 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001287 This class controls building "live" (i.e. HDDIMG and ISO) images.
1288 Live images contain syslinux for legacy booting, as well as the
1289 bootloader specified by
1290 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
1291 if
1292 <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
1293 contains "efi".
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001294 </para>
1295
1296 <para>
1297 Normally, you do not use this class directly.
1298 Instead, you add "live" to
1299 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001300 </para>
1301</section>
1302
1303<section id='ref-classes-image-mklibs'>
1304 <title><filename>image-mklibs.bbclass</filename></title>
1305
1306 <para>
1307 The <filename>image-mklibs</filename> class
1308 enables the use of the <filename>mklibs</filename> utility during the
1309 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1310 task, which optimizes the size of
1311 libraries contained in the image.
1312 </para>
1313
1314 <para>
1315 By default, the class is enabled in the
1316 <filename>local.conf.template</filename> using the
1317 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1318 variable as follows:
1319 <literallayout class='monospaced'>
1320 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1321 </literallayout>
1322 </para>
1323</section>
1324
1325<section id='ref-classes-image-prelink'>
1326 <title><filename>image-prelink.bbclass</filename></title>
1327
1328 <para>
1329 The <filename>image-prelink</filename> class
1330 enables the use of the <filename>prelink</filename> utility during
1331 the
1332 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1333 task, which optimizes the dynamic
1334 linking of shared libraries to reduce executable startup time.
1335 </para>
1336
1337 <para>
1338 By default, the class is enabled in the
1339 <filename>local.conf.template</filename> using the
1340 <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
1341 variable as follows:
1342 <literallayout class='monospaced'>
1343 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
1344 </literallayout>
1345 </para>
1346</section>
1347
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001348<section id='ref-classes-insane'>
1349 <title><filename>insane.bbclass</filename></title>
1350
1351 <para>
1352 The <filename>insane</filename> class adds a step to the package
1353 generation process so that output quality assurance checks are
1354 generated by the OpenEmbedded build system.
1355 A range of checks are performed that check the build's output
1356 for common problems that show up during runtime.
1357 Distribution policy usually dictates whether to include this class.
1358 </para>
1359
1360 <para>
1361 You can configure the sanity checks so that specific test failures
1362 either raise a warning or an error message.
1363 Typically, failures for new tests generate a warning.
1364 Subsequent failures for the same test would then generate an error
1365 message once the metadata is in a known and good condition.
1366 See the
1367 "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
1368 Chapter for a list of all the warning and error messages
1369 you might encounter using a default configuration.
1370 </para>
1371
1372 <para>
1373 Use the
1374 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1375 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1376 variables to control the behavior of
1377 these checks at the global level (i.e. in your custom distro
1378 configuration).
1379 However, to skip one or more checks in recipes, you should use
1380 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1381 For example, to skip the check for symbolic link
1382 <filename>.so</filename> files in the main package of a recipe,
1383 add the following to the recipe.
1384 You need to realize that the package name override, in this example
1385 <filename>${PN}</filename>, must be used:
1386 <literallayout class='monospaced'>
1387 INSANE_SKIP_${PN} += "dev-so"
1388 </literallayout>
1389 Please keep in mind that the QA checks exist in order to detect real
1390 or potential problems in the packaged output.
1391 So exercise caution when disabling these checks.
1392 </para>
1393
1394 <para>
1395 The following list shows the tests you can list with the
1396 <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
1397 variables:
1398 <itemizedlist>
1399 <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
1400 Checks that produced binaries have not already been
1401 stripped prior to the build system extracting debug symbols.
1402 It is common for upstream software projects to default to
1403 stripping debug symbols for output binaries.
1404 In order for debugging to work on the target using
1405 <filename>-dbg</filename> packages, this stripping must be
1406 disabled.
1407 </para></listitem>
1408 <listitem><para><emphasis><filename>arch:</filename></emphasis>
1409 Checks the Executable and Linkable Format (ELF) type, bit size,
1410 and endianness of any binaries to ensure they match the target
1411 architecture.
1412 This test fails if any binaries do not match the type since
1413 there would be an incompatibility.
1414 The test could indicate that the
1415 wrong compiler or compiler options have been used.
1416 Sometimes software, like bootloaders, might need to bypass
1417 this check.
1418 </para></listitem>
1419 <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
1420 Checks for paths to locations on the build host inside the
1421 output files.
1422 Currently, this test triggers too many false positives and
1423 thus is not normally enabled.
1424 </para></listitem>
1425 <listitem><para><emphasis><filename>build-deps:</filename></emphasis>
1426 Determines if a build-time dependency that is specified through
1427 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
1428 explicit
1429 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1430 or task-level dependencies exists to match any runtime
1431 dependency.
1432 This determination is particularly useful to discover where
1433 runtime dependencies are detected and added during packaging.
1434 If no explicit dependency has been specified within the
1435 metadata, at the packaging stage it is too late to ensure that
1436 the dependency is built, and thus you can end up with an
1437 error when the package is installed into the image during the
1438 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
1439 task because the auto-detected dependency was not satisfied.
1440 An example of this would be where the
1441 <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
1442 class automatically adds a dependency on the
1443 <filename>initscripts-functions</filename> package to packages
1444 that install an initscript that refers to
1445 <filename>/etc/init.d/functions</filename>.
1446 The recipe should really have an explicit
1447 <filename>RDEPENDS</filename> for the package in question on
1448 <filename>initscripts-functions</filename> so that the
1449 OpenEmbedded build system is able to ensure that the
1450 <filename>initscripts</filename> recipe is actually built and
1451 thus the <filename>initscripts-functions</filename> package is
1452 made available.
1453 </para></listitem>
1454 <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
1455 Checks the
1456 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
1457 log for indications
1458 that paths to locations on the build host were used.
1459 Using such paths might result in host contamination of the
1460 build output.
1461 </para></listitem>
1462 <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
1463 Checks that all packages except <filename>-dbg</filename>
1464 packages do not depend on <filename>-dbg</filename>
1465 packages, which would cause a packaging bug.
1466 </para></listitem>
1467 <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
1468 Checks for <filename>.debug</filename> directories in anything but the
1469 <filename>-dbg</filename> package.
1470 The debug files should all be in the <filename>-dbg</filename> package.
1471 Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
1472 <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
1473 Checks for invalid version comparison statements in runtime
1474 dependency relationships between packages (i.e. in
1475 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1476 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1477 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1478 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1479 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1480 and
1481 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
1482 variable values).
1483 Any invalid comparisons might trigger failures or undesirable
1484 behavior when passed to the package manager.
1485 </para></listitem>
1486 <listitem><para><emphasis><filename>desktop:</filename></emphasis>
1487 Runs the <filename>desktop-file-validate</filename> program
1488 against any <filename>.desktop</filename> files to validate
1489 their contents against the specification for
1490 <filename>.desktop</filename> files.</para></listitem>
1491 <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
1492 Checks that all packages except <filename>-dev</filename>
1493 or <filename>-staticdev</filename> packages do not depend on
1494 <filename>-dev</filename> packages, which would be a
1495 packaging bug.</para></listitem>
1496 <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
1497 Checks that the <filename>.so</filename> symbolic links are in the
1498 <filename>-dev</filename> package and not in any of the other packages.
1499 In general, these symlinks are only useful for development purposes.
1500 Thus, the <filename>-dev</filename> package is the correct location for
1501 them.
1502 Some very rare cases do exist for dynamically loaded modules where
1503 these symlinks are needed instead in the main package.
1504 </para></listitem>
1505 <listitem><para><emphasis><filename>file-rdeps:</filename></emphasis>
1506 Checks that file-level dependencies identified by the
1507 OpenEmbedded build system at packaging time are satisfied.
1508 For example, a shell script might start with the line
1509 <filename>#!/bin/bash</filename>.
1510 This line would translate to a file dependency on
1511 <filename>/bin/bash</filename>.
1512 Of the three package managers that the OpenEmbedded build
1513 system supports, only RPM directly handles file-level
1514 dependencies, resolving them automatically to packages
1515 providing the files.
1516 However, the lack of that functionality in the other two
1517 package managers does not mean the dependencies do not still
1518 need resolving.
1519 This QA check attempts to ensure that explicitly declared
1520 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
1521 exist to handle any file-level dependency detected in
1522 packaged files.
1523 </para></listitem>
1524 <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
1525 Checks for
1526 <link linkend='var-FILES'><filename>FILES</filename></link>
1527 variable values that contain "//", which is invalid.
1528 </para></listitem>
Brad Bishop316dfdd2018-06-25 12:45:53 -04001529 <listitem><para id='insane-host-user-contaminated'>
1530 <emphasis><filename>host-user-contaminated:</filename></emphasis>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001531 Checks that no package produced by the recipe contains any
1532 files outside of <filename>/home</filename> with a user or
1533 group ID that matches the user running BitBake.
1534 A match usually indicates that the files are being installed
1535 with an incorrect UID/GID, since target IDs are independent
1536 from host IDs.
1537 For additional information, see the section describing the
1538 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1539 task.
1540 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001541 <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
1542 Report when packages are excluded from being created due to
1543 being marked with a license that is in
1544 <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
1545 </para></listitem>
1546 <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
1547 Checks the
1548 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1549 log for indications
1550 that paths to locations on the build host were used.
1551 Using such paths might result in host contamination of the
1552 build output.
1553 </para></listitem>
1554 <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
1555 Reports when files have been installed within
1556 <filename>do_install</filename> but have not been included in
1557 any package by way of the
1558 <link linkend='var-FILES'><filename>FILES</filename></link>
1559 variable.
1560 Files that do not appear in any package cannot be present in
1561 an image later on in the build process.
1562 Ideally, all installed files should be packaged or not
1563 installed at all.
1564 These files can be deleted at the end of
1565 <filename>do_install</filename> if the files are not
1566 needed in any package.
1567 </para></listitem>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06001568 <listitem><para><emphasis><filename>invalid-chars:</filename></emphasis>
1569 Checks that the recipe metadata variables
1570 <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>,
1571 <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>,
1572 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>,
1573 and
1574 <link linkend='var-SECTION'><filename>SECTION</filename></link>
1575 do not contain non-UTF-8 characters.
1576 Some package managers do not support such characters.
1577 </para></listitem>
1578 <listitem><para><emphasis><filename>invalid-packageconfig:</filename></emphasis>
1579 Checks that no undefined features are being added to
1580 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>.
1581 For example, any name "foo" for which the following form
1582 does not exist:
1583 <literallayout class='monospaced'>
1584 PACKAGECONFIG[foo] = "..."
1585 </literallayout>
1586 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001587 <listitem><para><emphasis><filename>la:</filename></emphasis>
1588 Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
1589 paths.
1590 Any <filename>.la</filename> file containing these paths is incorrect since
1591 <filename>libtool</filename> adds the correct sysroot prefix when using the
1592 files automatically itself.</para></listitem>
1593 <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
1594 Ensures that the binaries were linked with the
1595 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
1596 options provided by the build system.
1597 If this test fails, check that the <filename>LDFLAGS</filename> variable
1598 is being passed to the linker command.</para></listitem>
1599 <listitem><para><emphasis><filename>libdir:</filename></emphasis>
1600 Checks for libraries being installed into incorrect
1601 (possibly hardcoded) installation paths.
1602 For example, this test will catch recipes that install
1603 <filename>/lib/bar.so</filename> when
1604 <filename>${base_libdir}</filename> is "lib32".
1605 Another example is when recipes install
1606 <filename>/usr/lib64/foo.so</filename> when
1607 <filename>${libdir}</filename> is "/usr/lib".
1608 </para></listitem>
1609 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
1610 Checks if a package contains files in
1611 <filename>/usr/libexec</filename>.
1612 This check is not performed if the
1613 <filename>libexecdir</filename> variable has been set
1614 explicitly to <filename>/usr/libexec</filename>.
1615 </para></listitem>
1616 <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
1617 Checks for the same package being listed multiple times through
1618 the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1619 variable value.
1620 Installing the package in this manner can cause errors during
1621 packaging.
1622 </para></listitem>
1623 <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
1624 Reports lines in <filename>fs-perms.txt</filename> that have
1625 an invalid format.
1626 </para></listitem>
1627 <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
1628 Reports lines in <filename>fs-perms.txt</filename> that have
1629 an invalid format.
1630 </para></listitem>
1631 <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
1632 Reports lines in <filename>fs-perms.txt</filename> that
1633 specify 'link' where the specified target already exists.
1634 </para></listitem>
1635 <listitem><para><emphasis><filename>perms:</filename></emphasis>
1636 Currently, this check is unused but reserved.
1637 </para></listitem>
1638 <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
1639 Checks <filename>.pc</filename> files for any
1640 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
1641 paths.
1642 Any <filename>.pc</filename> file containing these paths is incorrect
1643 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
1644 when the files are accessed.</para></listitem>
1645 <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
1646 Checks that all packages in
1647 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1648 have names that do not contain invalid characters (i.e.
1649 characters other than 0-9, a-z, ., +, and -).
1650 </para></listitem>
1651 <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
1652 Checks to see if the <filename>PKGV</filename> variable
1653 is undefined during
1654 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1655 </para></listitem>
1656 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
1657 Checks through the variables
1658 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
1659 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
1660 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
1661 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
1662 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
1663 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
1664 <link linkend='var-FILES'><filename>FILES</filename></link>,
1665 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
1666 <filename>pkg_preinst</filename>,
1667 <filename>pkg_postinst</filename>,
1668 <filename>pkg_prerm</filename>
1669 and <filename>pkg_postrm</filename>, and reports if there are
1670 variable sets that are not package-specific.
1671 Using these variables without a package suffix is bad practice,
1672 and might unnecessarily complicate dependencies of other packages
1673 within the same recipe or have other unintended consequences.
1674 </para></listitem>
1675 <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
1676 Checks that a recipe does not have a name
1677 (<link linkend='var-PN'><filename>PN</filename></link>) value
1678 that appears in
1679 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
1680 If a recipe is named such that its <filename>PN</filename>
1681 value matches something already in
1682 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
1683 happens to be the same as
1684 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
1685 or
1686 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
1687 it can have unexpected consequences.
1688 For example, assignments such as
1689 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
1690 <filename>FILES = "xyz"</filename>.
1691 </para></listitem>
1692 <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
1693 Checks for rpaths in the binaries that contain build system paths such
1694 as <filename>TMPDIR</filename>.
1695 If this test fails, bad <filename>-rpath</filename> options are being
1696 passed to the linker commands and your binaries have potential security
1697 issues.</para></listitem>
1698 <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
1699 Reports that splitting or stripping debug symbols from binaries
1700 has failed.
1701 </para></listitem>
1702 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
1703 Checks for static library files (<filename>*.a</filename>) in
1704 non-<filename>staticdev</filename> packages.
1705 </para></listitem>
1706 <listitem><para><emphasis><filename>symlink-to-sysroot:</filename></emphasis>
1707 Checks for symlinks in packages that point into
1708 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
1709 on the host.
1710 Such symlinks will work on the host, but are clearly invalid
1711 when running on the target.
1712 </para></listitem>
1713 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
1714 Checks for ELF binaries that contain relocations in their
1715 <filename>.text</filename> sections, which can result in a
1716 performance impact at runtime.
1717 See the explanation for the
1718 <link linkend='qa-issue-textrel'><filename>ELF binary</filename></link>
1719 message for more information regarding runtime performance issues.
1720 </para></listitem>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001721<!--
1722This check was removed for YP 2.3 release
1723
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001724 <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
1725 Reports when a binary installed in
1726 <filename>${base_libdir}</filename>,
1727 <filename>${base_bindir}</filename>, or
1728 <filename>${base_sbindir}</filename>, depends on another
1729 binary installed under <filename>${exec_prefix}</filename>.
1730 This dependency is a concern if you want the system to remain
1731 basically operable if <filename>/usr</filename> is mounted
1732 separately and is not mounted.
1733 <note>
1734 Defaults for binaries installed in
1735 <filename>${base_libdir}</filename>,
1736 <filename>${base_bindir}</filename>, and
1737 <filename>${base_sbindir}</filename> are
1738 <filename>/lib</filename>, <filename>/bin</filename>, and
1739 <filename>/sbin</filename>, respectively.
1740 The default for a binary installed
1741 under <filename>${exec_prefix}</filename> is
1742 <filename>/usr</filename>.
1743 </note>
1744 </para></listitem>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05001745-->
Andrew Geissler1e34c2d2020-05-29 16:02:59 -05001746 <listitem><para><emphasis><filename>unlisted-pkg-lics:</filename></emphasis>
1747 Checks that all declared licenses applying for a package are also
1748 declared on the recipe level (i.e. any license in
1749 <filename>LICENSE_*</filename> should appear in
1750 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>).
1751 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001752 <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
1753 Checks for dynamic library load paths (rpaths) in the binaries that
1754 by default on a standard system are searched by the linker (e.g.
1755 <filename>/lib</filename> and <filename>/usr/lib</filename>).
1756 While these paths will not cause any breakage, they do waste space and
1757 are unnecessary.</para></listitem>
1758 <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
1759 Reports when variables fundamental to packaging (i.e.
1760 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
1761 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
1762 <link linkend='var-D'><filename>D</filename></link>,
1763 <link linkend='var-PN'><filename>PN</filename></link>, and
1764 <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
1765 undefined during
1766 <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
1767 </para></listitem>
1768 <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
1769 If Build History is enabled, reports when a package
1770 being written out has a lower version than the previously
1771 written package under the same name.
1772 If you are placing output packages into a feed and
1773 upgrading packages on a target system using that feed, the
1774 version of a package going backwards can result in the target
1775 system not correctly upgrading to the "new" version of the
1776 package.
1777 <note>
1778 If you are not using runtime package management on your
1779 target system, then you do not need to worry about
1780 this situation.
1781 </note>
1782 </para></listitem>
1783 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
1784 Checks that all packages containing Xorg drivers have ABI
1785 dependencies.
1786 The <filename>xserver-xorg</filename> recipe provides driver
1787 ABI names.
1788 All drivers should depend on the ABI versions that they have
1789 been built against.
1790 Driver recipes that include
1791 <filename>xorg-driver-input.inc</filename>
1792 or <filename>xorg-driver-video.inc</filename> will
1793 automatically get these versions.
1794 Consequently, you should only need to explicitly add
1795 dependencies to binary driver recipes.
1796 </para></listitem>
1797 </itemizedlist>
1798 </para>
1799</section>
1800
1801<section id='ref-classes-insserv'>
1802 <title><filename>insserv.bbclass</filename></title>
1803
1804 <para>
1805 The <filename>insserv</filename> class
1806 uses the <filename>insserv</filename> utility to update the order of
1807 symbolic links in <filename>/etc/rc?.d/</filename> within an image
1808 based on dependencies specified by LSB headers in the
1809 <filename>init.d</filename> scripts themselves.
1810 </para>
1811</section>
1812
1813<section id='ref-classes-kernel'>
1814 <title><filename>kernel.bbclass</filename></title>
1815
1816 <para>
1817 The <filename>kernel</filename> class handles building Linux kernels.
1818 The class contains code to build all kernel trees.
1819 All needed headers are staged into the
1820 <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
1821 directory to allow out-of-tree module builds using
1822 the
1823 <link linkend='ref-classes-module'><filename>module</filename></link>
1824 class.
1825 </para>
1826
1827 <para>
Brad Bishop37a0e4d2017-12-04 01:01:44 -05001828 This means that each built kernel module is packaged separately and
1829 inter-module dependencies are created by parsing the
1830 <filename>modinfo</filename> output.
1831 If all modules are required, then installing the
1832 <filename>kernel-modules</filename> package installs all packages with
1833 modules and various other kernel packages such as
1834 <filename>kernel-vmlinux</filename>.
1835 </para>
1836
1837 <para>
1838 The <filename>kernel</filename> class contains logic that allows
1839 you to embed an initial RAM filesystem (initramfs) image when
1840 you build the kernel image.
1841 For information on how to build an initramfs, see the
1842 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05001843 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001844 </para>
1845
1846 <para>
1847 Various other classes are used by the <filename>kernel</filename>
1848 and <filename>module</filename> classes internally including the
1849 <link linkend='ref-classes-kernel-arch'><filename>kernel-arch</filename></link>,
1850 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>,
1851 and
1852 <link linkend='ref-classes-linux-kernel-base'><filename>linux-kernel-base</filename></link>
1853 classes.
1854 </para>
1855</section>
1856
1857<section id='ref-classes-kernel-arch'>
1858 <title><filename>kernel-arch.bbclass</filename></title>
1859
1860 <para>
1861 The <filename>kernel-arch</filename> class
1862 sets the <filename>ARCH</filename> environment variable for Linux
1863 kernel compilation (including modules).
1864 </para>
1865</section>
1866
Brad Bishop316dfdd2018-06-25 12:45:53 -04001867<section id='ref-classes-kernel-devicetree'>
1868 <title><filename>kernel-devicetree.bbclass</filename></title>
1869
1870 <para>
1871 The <filename>kernel-devicetree</filename> class, which is inherited by
1872 the
1873 <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
1874 class, supports device tree generation.
1875 </para>
1876</section>
1877
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001878<section id='ref-classes-kernel-fitimage'>
1879 <title><filename>kernel-fitimage.bbclass</filename></title>
1880
1881 <para>
1882 The <filename>kernel-fitimage</filename> class provides support to
1883 pack zImages.
1884 </para>
1885</section>
1886
1887<section id='ref-classes-kernel-grub'>
1888 <title><filename>kernel-grub.bbclass</filename></title>
1889
1890 <para>
1891 The <filename>kernel-grub</filename> class updates the boot area and
1892 the boot menu with the kernel as the priority boot mechanism while
1893 installing a RPM to update the kernel on a deployed target.
1894 </para>
1895</section>
1896
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001897<section id='ref-classes-kernel-module-split'>
1898 <title><filename>kernel-module-split.bbclass</filename></title>
1899
1900 <para>
1901 The <filename>kernel-module-split</filename> class
1902 provides common functionality for splitting Linux kernel modules into
1903 separate packages.
1904 </para>
1905</section>
1906
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001907<section id='ref-classes-kernel-uboot'>
1908 <title><filename>kernel-uboot.bbclass</filename></title>
1909
1910 <para>
1911 The <filename>kernel-uboot</filename> class provides support for
1912 building from vmlinux-style kernel sources.
1913 </para>
1914</section>
1915
1916<section id='ref-classes-kernel-uimage'>
1917 <title><filename>kernel-uimage.bbclass</filename></title>
1918
1919 <para>
1920 The <filename>kernel-uimage</filename> class provides support to
1921 pack uImage.
1922 </para>
1923</section>
1924
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001925<section id='ref-classes-kernel-yocto'>
1926 <title><filename>kernel-yocto.bbclass</filename></title>
1927
1928 <para>
1929 The <filename>kernel-yocto</filename> class
1930 provides common functionality for building from linux-yocto style
1931 kernel source repositories.
1932 </para>
1933</section>
1934
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001935<section id='ref-classes-kernelsrc'>
1936 <title><filename>kernelsrc.bbclass</filename></title>
1937
1938 <para>
1939 The <filename>kernelsrc</filename> class sets the Linux kernel
1940 source and version.
1941 </para>
1942</section>
1943
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001944<section id='ref-classes-lib_package'>
1945 <title><filename>lib_package.bbclass</filename></title>
1946
1947 <para>
1948 The <filename>lib_package</filename> class
1949 supports recipes that build libraries and produce executable
1950 binaries, where those binaries should not be installed by default
1951 along with the library.
1952 Instead, the binaries are added to a separate
1953 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-bin</filename>
1954 package to make their installation optional.
1955 </para>
1956</section>
1957
Patrick Williamsf1e5d692016-03-30 15:21:19 -05001958<section id='ref-classes-libc*'>
1959 <title><filename>libc*.bbclass</filename></title>
1960
1961 <para>
1962 The <filename>libc*</filename> classes support recipes that build
1963 packages with <filename>libc</filename>:
1964 <itemizedlist>
1965 <listitem><para>The <filename>libc-common</filename> class
1966 provides common support for building with
1967 <filename>libc</filename>.
1968 </para></listitem>
1969 <listitem><para>The <filename>libc-package</filename> class
1970 supports packaging up <filename>glibc</filename> and
1971 <filename>eglibc</filename>.
1972 </para></listitem>
1973 </itemizedlist>
1974 </para>
1975</section>
1976
Patrick Williamsc124f4f2015-09-15 14:41:29 -05001977<section id='ref-classes-license'>
1978 <title><filename>license.bbclass</filename></title>
1979
1980 <para>
1981 The <filename>license</filename> class provides license
1982 manifest creation and license exclusion.
1983 This class is enabled by default using the default value for the
1984 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
1985 variable.
1986 </para>
1987</section>
1988
1989<section id='ref-classes-linux-kernel-base'>
1990 <title><filename>linux-kernel-base.bbclass</filename></title>
1991
1992 <para>
1993 The <filename>linux-kernel-base</filename> class
1994 provides common functionality for recipes that build out of the Linux
1995 kernel source tree.
1996 These builds goes beyond the kernel itself.
1997 For example, the Perf recipe also inherits this class.
1998 </para>
1999</section>
2000
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002001<section id='ref-classes-linuxloader'>
2002 <title><filename>linuxloader.bbclass</filename></title>
2003
2004 <para>
2005 Provides the function <filename>linuxloader()</filename>, which gives
2006 the value of the dynamic loader/linker provided on the platform.
2007 This value is used by a number of other classes.
2008 </para>
2009</section>
2010
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002011<section id='ref-classes-logging'>
2012 <title><filename>logging.bbclass</filename></title>
2013
2014 <para>
2015 The <filename>logging</filename> class provides the standard
2016 shell functions used to log messages for various BitBake severity levels
2017 (i.e. <filename>bbplain</filename>, <filename>bbnote</filename>,
2018 <filename>bbwarn</filename>, <filename>bberror</filename>,
2019 <filename>bbfatal</filename>, and <filename>bbdebug</filename>).
2020 </para>
2021
2022 <para>
2023 This class is enabled by default since it is inherited by
2024 the <filename>base</filename> class.
2025 </para>
2026</section>
2027
2028<section id='ref-classes-meta'>
2029 <title><filename>meta.bbclass</filename></title>
2030
2031 <para>
2032 The <filename>meta</filename> class is inherited by recipes
2033 that do not build any output packages themselves, but act as a "meta"
2034 target for building other recipes.
2035 </para>
2036</section>
2037
2038<section id='ref-classes-metadata_scm'>
2039 <title><filename>metadata_scm.bbclass</filename></title>
2040
2041 <para>
2042 The <filename>metadata_scm</filename> class provides functionality for
2043 querying the branch and revision of a Source Code Manager (SCM)
2044 repository.
2045 </para>
2046
2047 <para>
2048 The <link linkend='ref-classes-base'><filename>base</filename></link>
2049 class uses this class to print the revisions of each layer before
2050 starting every build.
2051 The <filename>metadata_scm</filename> class is enabled by default
2052 because it is inherited by the <filename>base</filename> class.
2053 </para>
2054</section>
2055
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002056<section id='ref-classes-migrate_localcount'>
2057 <title><filename>migrate_localcount.bbclass</filename></title>
2058
2059 <para>
2060 The <filename>migrate_localcount</filename> class verifies a recipe's
2061 localcount data and increments it appropriately.
2062 </para>
2063</section>
2064
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002065<section id='ref-classes-mime'>
2066 <title><filename>mime.bbclass</filename></title>
2067
2068 <para>
2069 The <filename>mime</filename> class generates the proper
2070 post-install and post-remove (postinst/postrm) scriptlets for packages
2071 that install MIME type files.
2072 These scriptlets call <filename>update-mime-database</filename> to add
2073 the MIME types to the shared database.
2074 </para>
2075</section>
2076
2077<section id='ref-classes-mirrors'>
2078 <title><filename>mirrors.bbclass</filename></title>
2079
2080 <para>
2081 The <filename>mirrors</filename> class sets up some standard
2082 <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> entries
2083 for source code mirrors.
2084 These mirrors provide a fall-back path in case the upstream source
2085 specified in
2086 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
2087 within recipes is unavailable.
2088 </para>
2089
2090 <para>
2091 This class is enabled by default since it is inherited by the
2092 <link linkend='ref-classes-base'><filename>base</filename></link> class.
2093 </para>
2094</section>
2095
2096<section id='ref-classes-module'>
2097 <title><filename>module.bbclass</filename></title>
2098
2099 <para>
2100 The <filename>module</filename> class provides support for building
2101 out-of-tree Linux kernel modules.
2102 The class inherits the
2103 <link linkend='ref-classes-module-base'><filename>module-base</filename></link>
2104 and
2105 <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link>
2106 classes, and implements the
2107 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
2108 and
2109 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2110 tasks.
2111 The class provides everything needed to build and package a kernel
2112 module.
2113 </para>
2114
2115 <para>
2116 For general information on out-of-tree Linux kernel modules, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04002117 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002118 section in the Yocto Project Linux Kernel Development Manual.
2119 </para>
2120</section>
2121
2122<section id='ref-classes-module-base'>
2123 <title><filename>module-base.bbclass</filename></title>
2124
2125 <para>
2126 The <filename>module-base</filename> class provides the base
2127 functionality for building Linux kernel modules.
2128 Typically, a recipe that builds software that includes one or
2129 more kernel modules and has its own means of building
2130 the module inherits this class as opposed to inheriting the
2131 <link linkend='ref-classes-module'><filename>module</filename></link>
2132 class.
2133 </para>
2134</section>
2135
2136<section id='ref-classes-multilib*'>
2137 <title><filename>multilib*.bbclass</filename></title>
2138
2139 <para>
2140 The <filename>multilib*</filename> classes provide support
2141 for building libraries with different target optimizations or target
2142 architectures and installing them side-by-side in the same image.
2143 </para>
2144
2145 <para>
2146 For more information on using the Multilib feature, see the
2147 "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002148 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002149 </para>
2150</section>
2151
2152<section id='ref-classes-native'>
2153 <title><filename>native.bbclass</filename></title>
2154
2155 <para>
2156 The <filename>native</filename> class provides common
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002157 functionality for recipes that build tools to run on the
2158 <link linkend='hardware-build-system-term'>build host</link>
2159 (i.e. tools that use the compiler or other tools from the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002160 build host).
2161 </para>
2162
2163 <para>
2164 You can create a recipe that builds tools that run natively on the
2165 host a couple different ways:
2166 <itemizedlist>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002167 <listitem><para>
2168 Create a
2169 <replaceable>myrecipe</replaceable><filename>-native.bb</filename>
2170 recipe that inherits the <filename>native</filename> class.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002171 If you use this method, you must order the inherit statement
2172 in the recipe after all other inherit statements so that the
2173 <filename>native</filename> class is inherited last.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002174 <note><title>Warning</title>
2175 When creating a recipe this way, the recipe name must
2176 follow this naming convention:
2177 <literallayout class='monospaced'>
2178 <replaceable>myrecipe</replaceable>-native.bb
2179 </literallayout>
2180 Not using this naming convention can lead to subtle
2181 problems caused by existing code that depends on that
2182 naming convention.
2183 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002184 </para></listitem>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002185 <listitem><para>
2186 Create or modify a target recipe that contains the following:
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002187 <literallayout class='monospaced'>
2188 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native"
2189 </literallayout>
2190 Inside the recipe, use <filename>_class-native</filename> and
2191 <filename>_class-target</filename> overrides to specify any
2192 functionality specific to the respective native or target
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08002193 case.
2194 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002195 </itemizedlist>
2196 </para>
2197
2198 <para>
2199 Although applied differently, the <filename>native</filename> class is
2200 used with both methods.
2201 The advantage of the second method is that you do not need to have two
2202 separate recipes (assuming you need both) for native and target.
2203 All common parts of the recipe are automatically shared.
2204 </para>
2205</section>
2206
2207<section id='ref-classes-nativesdk'>
2208 <title><filename>nativesdk.bbclass</filename></title>
2209
2210 <para>
2211 The <filename>nativesdk</filename> class provides common
2212 functionality for recipes that wish to build tools to run as part of
2213 an SDK (i.e. tools that run on
2214 <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
2215 </para>
2216
2217 <para>
2218 You can create a recipe that builds tools that run on the SDK machine
2219 a couple different ways:
2220 <itemizedlist>
2221 <listitem><para>Create a
2222 <filename>nativesdk-</filename><replaceable>myrecipe</replaceable><filename>.bb</filename>
2223 recipe that inherits the <filename>nativesdk</filename> class.
2224 If you use this method, you must order the inherit statement
2225 in the recipe after all other inherit statements so that the
2226 <filename>nativesdk</filename> class is inherited last.
2227 </para></listitem>
2228 <listitem><para>Create a <filename>nativesdk</filename> variant
2229 of any recipe by adding the following:
2230 <literallayout class='monospaced'>
2231 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "nativesdk"
2232 </literallayout>
2233 Inside the recipe, use <filename>_class-nativesdk</filename> and
2234 <filename>_class-target</filename> overrides to specify any
2235 functionality specific to the respective SDK machine or target
2236 case.</para></listitem>
2237 </itemizedlist>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002238 <note><title>Warning</title>
2239 When creating a recipe, you must follow this naming convention:
2240 <literallayout class='monospaced'>
2241 nativesdk-<replaceable>myrecipe</replaceable>.bb
2242 </literallayout>
2243 Not doing so can lead to subtle problems because code exists
2244 that depends on the naming convention.
2245 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002246 </para>
2247
2248 <para>
2249 Although applied differently, the <filename>nativesdk</filename> class
2250 is used with both methods.
2251 The advantage of the second method is that you do not need to have two
2252 separate recipes (assuming you need both) for the SDK machine and the
2253 target.
2254 All common parts of the recipe are automatically shared.
2255 </para>
2256</section>
2257
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002258<section id='ref-classes-nopackages'>
2259 <title><filename>nopackages.bbclass</filename></title>
2260
2261 <para>
2262 Disables packaging tasks for those recipes and classes where
2263 packaging is not needed.
2264 </para>
2265</section>
2266
2267<section id='ref-classes-npm'>
2268 <title><filename>npm.bbclass</filename></title>
2269
2270 <para>
Brad Bishop15ae2502019-06-18 21:44:24 -04002271 Provides support for building Node.js software fetched using the
2272 <ulink url='https://en.wikipedia.org/wiki/Npm_(software)'>node package manager (NPM)</ulink>.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002273 <note>
2274 Currently, recipes inheriting this class must use the
2275 <filename>npm://</filename> fetcher to have dependencies fetched
2276 and packaged automatically.
2277 </note>
Brad Bishop15ae2502019-06-18 21:44:24 -04002278 For information on how to create NPM packages, see the
2279 "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-node-package-manager-npm-packages'>Creating Node Package Manager (NPM) Packages</ulink>"
2280 section in the Yocto Project Development Tasks Manual.
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002281 </para>
2282</section>
2283
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002284<section id='ref-classes-oelint'>
2285 <title><filename>oelint.bbclass</filename></title>
2286
2287 <para>
2288 The <filename>oelint</filename> class is an
2289 obsolete lint checking tool that exists in
2290 <filename>meta/classes</filename> in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002291 <link linkend='source-directory'>Source Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002292 </para>
2293
2294 <para>
2295 A number of classes exist that could be generally useful in
2296 OE-Core but are never actually used within OE-Core itself.
2297 The <filename>oelint</filename> class is one such example.
2298 However, being aware of this class can reduce the proliferation of
2299 different versions of similar classes across multiple layers.
2300 </para>
2301</section>
2302
2303<section id='ref-classes-own-mirrors'>
2304 <title><filename>own-mirrors.bbclass</filename></title>
2305
2306 <para>
2307 The <filename>own-mirrors</filename> class makes it
2308 easier to set up your own
2309 <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
2310 from which to first fetch source before attempting to fetch it from the
2311 upstream specified in
2312 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
2313 within each recipe.
2314 </para>
2315
2316 <para>
2317 To use this class, inherit it globally and specify
2318 <link linkend='var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></link>.
2319 Here is an example:
2320 <literallayout class='monospaced'>
2321 INHERIT += "own-mirrors"
2322 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
2323 </literallayout>
2324 You can specify only a single URL in
2325 <filename>SOURCE_MIRROR_URL</filename>.
2326 </para>
2327</section>
2328
2329<section id='ref-classes-package'>
2330 <title><filename>package.bbclass</filename></title>
2331
2332 <para>
2333 The <filename>package</filename> class supports generating
2334 packages from a build's output.
2335 The core generic functionality is in
2336 <filename>package.bbclass</filename>.
2337 The code specific to particular package types resides in these
2338 package-specific classes:
2339 <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
2340 <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
2341 <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
2342 and
2343 <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
2344 <note><title>Warning</title>
2345 The <filename>package_tar</filename> class is broken and not
2346 supported.
2347 It is recommended that you do not use this class.
2348 </note>
2349 </para>
2350
2351 <para>
2352 You can control the list of resulting package formats by using the
2353 <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
2354 variable defined in your <filename>conf/local.conf</filename>
2355 configuration file, which is located in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002356 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002357 When defining the variable, you can specify one or more package types.
2358 Since images are generated from packages, a packaging class is
2359 needed to enable image generation.
2360 The first class listed in this variable is used for image generation.
2361 </para>
2362
2363 <para>
2364 If you take the optional step to set up a repository (package feed)
Brad Bishop6e60e8b2018-02-01 10:27:11 -05002365 on the development host that can be used by DNF, you can
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002366 install packages from the feed while you are running the image
2367 on the target (i.e. runtime installation of packages).
2368 For more information, see the
2369 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002370 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002371 </para>
2372
2373 <para>
2374 The package-specific class you choose can affect build-time performance
2375 and has space ramifications.
2376 In general, building a package with IPK takes about thirty percent less
2377 time as compared to using RPM to build the same or similar package.
2378 This comparison takes into account a complete build of the package with
2379 all dependencies previously built.
2380 The reason for this discrepancy is because the RPM package manager
2381 creates and processes more
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002382 <link linkend='metadata'>Metadata</link> than the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002383 IPK package manager.
2384 Consequently, you might consider setting
2385 <filename>PACKAGE_CLASSES</filename> to "package_ipk" if you are
2386 building smaller systems.
2387 </para>
2388
2389 <para>
2390 Before making your package manager decision, however, you should
2391 consider some further things about using RPM:
2392 <itemizedlist>
2393 <listitem><para>
2394 RPM starts to provide more abilities than IPK due to
2395 the fact that it processes more Metadata.
2396 For example, this information includes individual file types,
2397 file checksum generation and evaluation on install, sparse file
2398 support, conflict detection and resolution for Multilib systems,
2399 ACID style upgrade, and repackaging abilities for rollbacks.
2400 </para></listitem>
2401 <listitem><para>
2402 For smaller systems, the extra space used for the Berkeley
2403 Database and the amount of metadata when using RPM can affect
2404 your ability to perform on-device upgrades.
2405 </para></listitem>
2406 </itemizedlist>
2407 </para>
2408
2409 <para>
2410 You can find additional information on the effects of the package
2411 class at these two Yocto Project mailing list links:
2412 <itemizedlist>
2413 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
2414 https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
2415 <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
2416 https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
2417 </itemizedlist>
2418 </para>
2419</section>
2420
2421<section id='ref-classes-package_deb'>
2422 <title><filename>package_deb.bbclass</filename></title>
2423
2424 <para>
2425 The <filename>package_deb</filename> class
2426 provides support for creating packages that use the Debian
2427 (i.e. <filename>.deb</filename>) file format.
2428 The class ensures the packages are written out in a
2429 <filename>.deb</filename> file format to the
2430 <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
2431 directory.
2432 </para>
2433
2434 <para>
2435 This class inherits the
2436 <link linkend='ref-classes-package'><filename>package</filename></link>
2437 class and is enabled through the
2438 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2439 variable in the <filename>local.conf</filename> file.
2440 </para>
2441</section>
2442
2443<section id='ref-classes-package_ipk'>
2444 <title><filename>package_ipk.bbclass</filename></title>
2445
2446 <para>
2447 The <filename>package_ipk</filename> class
2448 provides support for creating packages that use the IPK
2449 (i.e. <filename>.ipk</filename>) file format.
2450 The class ensures the packages are written out in a
2451 <filename>.ipk</filename> file format to the
2452 <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
2453 directory.
2454 </para>
2455
2456 <para>
2457 This class inherits the
2458 <link linkend='ref-classes-package'><filename>package</filename></link>
2459 class and is enabled through the
2460 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2461 variable in the <filename>local.conf</filename> file.
2462 </para>
2463</section>
2464
2465<section id='ref-classes-package_rpm'>
2466 <title><filename>package_rpm.bbclass</filename></title>
2467
2468 <para>
2469 The <filename>package_rpm</filename> class
2470 provides support for creating packages that use the RPM
2471 (i.e. <filename>.rpm</filename>) file format.
2472 The class ensures the packages are written out in a
2473 <filename>.rpm</filename> file format to the
2474 <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
2475 directory.
2476 </para>
2477
2478 <para>
2479 This class inherits the
2480 <link linkend='ref-classes-package'><filename>package</filename></link>
2481 class and is enabled through the
2482 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2483 variable in the <filename>local.conf</filename> file.
2484 </para>
2485</section>
2486
2487<section id='ref-classes-package_tar'>
2488 <title><filename>package_tar.bbclass</filename></title>
2489
2490 <para>
2491 The <filename>package_tar</filename> class
2492 provides support for creating tarballs.
2493 The class ensures the packages are written out in a
2494 tarball format to the
2495 <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
2496 directory.
2497 </para>
2498
2499 <para>
2500 This class inherits the
2501 <link linkend='ref-classes-package'><filename>package</filename></link>
2502 class and is enabled through the
2503 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
2504 variable in the <filename>local.conf</filename> file.
2505 <note>
2506 You cannot specify the <filename>package_tar</filename> class
2507 first using the <filename>PACKAGE_CLASSES</filename> variable.
2508 You must use <filename>.deb</filename>,
2509 <filename>.ipk</filename>, or <filename>.rpm</filename> file
2510 formats for your image or SDK.
2511 </note>
2512 </para>
2513</section>
2514
2515<section id='ref-classes-packagedata'>
2516 <title><filename>packagedata.bbclass</filename></title>
2517
2518 <para>
2519 The <filename>packagedata</filename> class provides
2520 common functionality for reading <filename>pkgdata</filename> files
2521 found in
2522 <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
2523 These files contain information about each output package produced by
2524 the OpenEmbedded build system.
2525 </para>
2526
2527 <para>
2528 This class is enabled by default because it is inherited by the
2529 <link linkend='ref-classes-package'><filename>package</filename></link>
2530 class.
2531 </para>
2532</section>
2533
2534<section id='ref-classes-packagegroup'>
2535 <title><filename>packagegroup.bbclass</filename></title>
2536
2537 <para>
2538 The <filename>packagegroup</filename> class sets default values
2539 appropriate for package group recipes (e.g.
2540 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
2541 <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
2542 <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
2543 and so forth).
2544 It is highly recommended that all package group recipes inherit this class.
2545 </para>
2546
2547 <para>
2548 For information on how to use this class, see the
2549 "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002550 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002551 </para>
2552
2553 <para>
2554 Previously, this class was called the <filename>task</filename> class.
2555 </para>
2556</section>
2557
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002558<section id='ref-classes-patch'>
2559 <title><filename>patch.bbclass</filename></title>
2560
2561 <para>
2562 The <filename>patch</filename> class provides all functionality for
2563 applying patches during the
2564 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
2565 task.
2566 </para>
2567
2568 <para>
2569 This class is enabled by default because it is inherited by the
2570 <link linkend='ref-classes-base'><filename>base</filename></link>
2571 class.
2572 </para>
2573</section>
2574
2575<section id='ref-classes-perlnative'>
2576 <title><filename>perlnative.bbclass</filename></title>
2577
2578 <para>
2579 When inherited by a recipe, the <filename>perlnative</filename> class
2580 supports using the native version of Perl built by the build system
2581 rather than using the version provided by the build host.
2582 </para>
2583</section>
2584
2585<section id='ref-classes-pixbufcache'>
2586 <title><filename>pixbufcache.bbclass</filename></title>
2587
2588 <para>
2589 The <filename>pixbufcache</filename> class generates the proper
2590 post-install and post-remove (postinst/postrm) scriptlets for packages
2591 that install pixbuf loaders, which are used with
2592 <filename>gdk-pixbuf</filename>.
2593 These scriptlets call <filename>update_pixbuf_cache</filename>
2594 to add the pixbuf loaders to the cache.
2595 Since the cache files are architecture-specific,
2596 <filename>update_pixbuf_cache</filename> is run using QEMU if the
2597 postinst scriptlets need to be run on the build host during image
2598 creation.
2599 </para>
2600
2601 <para>
2602 If the pixbuf loaders being installed are in packages other
2603 than the recipe's main package, set
2604 <link linkend='var-PIXBUF_PACKAGES'><filename>PIXBUF_PACKAGES</filename></link>
2605 to specify the packages containing the loaders.
2606 </para>
2607</section>
2608
2609<section id='ref-classes-pkgconfig'>
2610 <title><filename>pkgconfig.bbclass</filename></title>
2611
2612 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002613 The <filename>pkgconfig</filename> class provides a standard way to get
2614 header and library information by using <filename>pkg-config</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002615 This class aims to smooth integration of
2616 <filename>pkg-config</filename> into libraries that use it.
2617 </para>
2618
2619 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002620 During staging, BitBake installs <filename>pkg-config</filename>
2621 data into the <filename>sysroots/</filename> directory.
2622 By making use of sysroot functionality within
2623 <filename>pkg-config</filename>, the <filename>pkgconfig</filename>
2624 class no longer has to manipulate the files.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002625 </para>
2626</section>
2627
2628<section id='ref-classes-populate-sdk'>
2629 <title><filename>populate_sdk.bbclass</filename></title>
2630
2631 <para>
2632 The <filename>populate_sdk</filename> class provides support for
2633 SDK-only recipes.
2634 For information on advantages gained when building a cross-development
2635 toolchain using the
2636 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2637 task, see the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002638 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002639 section in the Yocto Project Application Development and the
2640 Extensible Software Development Kit (eSDK) manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002641 </para>
2642</section>
2643
2644<section id='ref-classes-populate-sdk-*'>
2645 <title><filename>populate_sdk_*.bbclass</filename></title>
2646
2647 <para>
2648 The <filename>populate_sdk_*</filename> classes support SDK creation
2649 and consist of the following classes:
2650 <itemizedlist>
2651 <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis>
2652 The base class supporting SDK creation under all package
2653 managers (i.e. DEB, RPM, and opkg).</para></listitem>
2654 <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis>
2655 Supports creation of the SDK given the Debian package manager.
2656 </para></listitem>
2657 <listitem><para><emphasis><filename>populate_sdk_rpm</filename>:</emphasis>
2658 Supports creation of the SDK given the RPM package manager.
2659 </para></listitem>
2660 <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis>
2661 Supports creation of the SDK given the opkg (IPK format)
2662 package manager.
2663 </para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002664 <listitem><para><emphasis><filename>populate_sdk_ext</filename>:</emphasis>
2665 Supports extensible SDK creation under all package managers.
2666 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002667 </itemizedlist>
2668 </para>
2669
2670 <para>
2671 The <filename>populate_sdk_base</filename> class inherits the
2672 appropriate <filename>populate_sdk_*</filename> (i.e.
2673 <filename>deb</filename>, <filename>rpm</filename>, and
2674 <filename>ipk</filename>) based on
2675 <link linkend='var-IMAGE_PKGTYPE'><filename>IMAGE_PKGTYPE</filename></link>.
2676 </para>
2677
2678 <para>
2679 The base class ensures all source and destination directories are
2680 established and then populates the SDK.
2681 After populating the SDK, the <filename>populate_sdk_base</filename>
2682 class constructs two sysroots:
2683 <filename>${</filename><link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>}-nativesdk</filename>,
2684 which contains the cross-compiler and associated tooling, and the
2685 target, which contains a target root filesystem that is configured for
2686 the SDK usage.
2687 These two images reside in
2688 <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>,
2689 which consists of the following:
2690 <literallayout class='monospaced'>
2691 ${SDK_OUTPUT}/${SDK_ARCH}<replaceable>-nativesdk-pkgs</replaceable>
2692 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/<replaceable>target-pkgs</replaceable>
2693 </literallayout>
2694 </para>
2695
2696 <para>
2697 Finally, the base populate SDK class creates the toolchain
2698 environment setup script, the tarball of the SDK, and the installer.
2699 </para>
2700
2701 <para>
2702 The respective <filename>populate_sdk_deb</filename>,
2703 <filename>populate_sdk_rpm</filename>, and
2704 <filename>populate_sdk_ipk</filename> classes each support the
2705 specific type of SDK.
2706 These classes are inherited by and used with the
2707 <filename>populate_sdk_base</filename> class.
2708 </para>
2709
2710 <para>
2711 For more information on the cross-development toolchain
2712 generation, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04002713 "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
2714 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002715 For information on advantages gained when building a
2716 cross-development toolchain using the
2717 <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
2718 task, see the
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002719 "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002720 section in the Yocto Project Application Development and the
2721 Extensible Software Development Kit (eSDK) manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002722 </para>
2723</section>
2724
2725<section id='ref-classes-prexport'>
2726 <title><filename>prexport.bbclass</filename></title>
2727
2728 <para>
2729 The <filename>prexport</filename> class provides functionality for
2730 exporting
2731 <link linkend='var-PR'><filename>PR</filename></link> values.
2732 <note>
2733 This class is not intended to be used directly.
2734 Rather, it is enabled when using
2735 "<filename>bitbake-prserv-tool export</filename>".
2736 </note>
2737 </para>
2738</section>
2739
2740<section id='ref-classes-primport'>
2741 <title><filename>primport.bbclass</filename></title>
2742
2743 <para>
2744 The <filename>primport</filename> class provides functionality for
2745 importing
2746 <link linkend='var-PR'><filename>PR</filename></link> values.
2747 <note>
2748 This class is not intended to be used directly.
2749 Rather, it is enabled when using
2750 "<filename>bitbake-prserv-tool import</filename>".
2751 </note>
2752 </para>
2753</section>
2754
2755<section id='ref-classes-prserv'>
2756 <title><filename>prserv.bbclass</filename></title>
2757
2758 <para>
2759 The <filename>prserv</filename> class provides functionality for
2760 using a
2761 <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>
2762 in order to automatically manage the incrementing of the
2763 <link linkend='var-PR'><filename>PR</filename></link> variable for
2764 each recipe.
2765 </para>
2766
2767 <para>
2768 This class is enabled by default because it is inherited by the
2769 <link linkend='ref-classes-package'><filename>package</filename></link>
2770 class.
2771 However, the OpenEmbedded build system will not enable the
2772 functionality of this class unless
2773 <link linkend='var-PRSERV_HOST'><filename>PRSERV_HOST</filename></link>
2774 has been set.
2775 </para>
2776</section>
2777
2778<section id='ref-classes-ptest'>
2779 <title><filename>ptest.bbclass</filename></title>
2780
2781 <para>
2782 The <filename>ptest</filename> class provides functionality for
2783 packaging and installing runtime tests for recipes that build software
2784 that provides these tests.
2785 </para>
2786
2787 <para>
2788 This class is intended to be inherited by individual recipes.
2789 However, the class' functionality is largely disabled unless "ptest"
2790 appears in
2791 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
2792 See the
2793 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002794 section in the Yocto Project Development Tasks Manual for more
2795 information on ptest.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002796 </para>
2797</section>
2798
2799<section id='ref-classes-ptest-gnome'>
2800 <title><filename>ptest-gnome.bbclass</filename></title>
2801
2802 <para>
2803 Enables package tests (ptests) specifically for GNOME packages,
2804 which have tests intended to be executed with
2805 <filename>gnome-desktop-testing</filename>.
2806 </para>
2807
2808 <para>
2809 For information on setting up and running ptests, see the
2810 "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002811 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002812 </para>
2813</section>
2814
2815<section id='ref-classes-python-dir'>
2816 <title><filename>python-dir.bbclass</filename></title>
2817
2818 <para>
2819 The <filename>python-dir</filename> class provides the base version,
2820 location, and site package location for Python.
2821 </para>
2822</section>
2823
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002824<section id='ref-classes-python3native'>
2825 <title><filename>python3native.bbclass</filename></title>
2826
2827 <para>
2828 The <filename>python3native</filename> class supports using the
2829 native version of Python 3 built by the build system rather than
2830 support of the version provided by the build host.
2831 </para>
2832</section>
2833
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002834<section id='ref-classes-pythonnative'>
2835 <title><filename>pythonnative.bbclass</filename></title>
2836
2837 <para>
2838 When inherited by a recipe, the <filename>pythonnative</filename> class
2839 supports using the native version of Python built by the build system
2840 rather than using the version provided by the build host.
2841 </para>
2842</section>
2843
2844<section id='ref-classes-qemu'>
2845 <title><filename>qemu.bbclass</filename></title>
2846
2847 <para>
2848 The <filename>qemu</filename> class provides functionality for recipes
2849 that either need QEMU or test for the existence of QEMU.
2850 Typically, this class is used to run programs for a target system on
2851 the build host using QEMU's application emulation mode.
2852 </para>
2853</section>
2854
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002855<section id='ref-classes-recipe_sanity'>
2856 <title><filename>recipe_sanity.bbclass</filename></title>
2857
2858 <para>
2859 The <filename>recipe_sanity</filename> class checks for the presence
2860 of any host system recipe prerequisites that might affect the
2861 build (e.g. variables that are set or software that is present).
2862 </para>
2863</section>
2864
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002865<section id='ref-classes-relocatable'>
2866 <title><filename>relocatable.bbclass</filename></title>
2867
2868 <para>
2869 The <filename>relocatable</filename> class enables relocation of
2870 binaries when they are installed into the sysroot.
2871 </para>
2872
2873 <para>
2874 This class makes use of the
2875 <link linkend='ref-classes-chrpath'><filename>chrpath</filename></link>
2876 class and is used by both the
2877 <link linkend='ref-classes-cross'><filename>cross</filename></link>
2878 and
2879 <link linkend='ref-classes-native'><filename>native</filename></link>
2880 classes.
2881 </para>
2882</section>
2883
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002884<section id='ref-classes-remove-libtool'>
2885 <title><filename>remove-libtool.bbclass</filename></title>
2886
2887 <para>
2888 The <filename>remove-libtool</filename> class adds a post function
2889 to the
2890 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
2891 task to remove all <filename>.la</filename> files installed by
2892 <filename>libtool</filename>.
2893 Removing these files results in them being absent from both the
2894 sysroot and target packages.
2895 </para>
2896
2897 <para>
2898 If a recipe needs the <filename>.la</filename> files to be installed,
2899 then the recipe can override the removal by setting
2900 <filename>REMOVE_LIBTOOL_LA</filename> to "0" as follows:
2901 <literallayout class='monospaced'>
2902 REMOVE_LIBTOOL_LA = "0"
2903 </literallayout>
2904 <note>
2905 The <filename>remove-libtool</filename> class is not enabled by
2906 default.
2907 </note>
2908 </para>
2909</section>
2910
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002911<section id='ref-classes-report-error'>
2912 <title><filename>report-error.bbclass</filename></title>
2913
2914 <para>
2915 The <filename>report-error</filename> class supports enabling the
2916 <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
2917 which allows you to submit build error information to a central
2918 database.
2919 </para>
2920
2921 <para>
2922 The class collects debug information for recipe, recipe version, task,
2923 machine, distro, build system, target system, host distro, branch,
2924 commit, and log.
2925 From the information, report files using a JSON format are created and
2926 stored in
2927 <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
2928 </para>
2929</section>
2930
2931<section id='ref-classes-rm-work'>
2932 <title><filename>rm_work.bbclass</filename></title>
2933
2934 <para>
2935 The <filename>rm_work</filename> class supports deletion of temporary
2936 workspace, which can ease your hard drive demands during builds.
2937 </para>
2938
2939 <para>
2940 The OpenEmbedded build system can use a substantial amount of disk
2941 space during the build process.
2942 A portion of this space is the work files under the
2943 <filename>${TMPDIR}/work</filename> directory for each recipe.
2944 Once the build system generates the packages for a recipe, the work
2945 files for that recipe are no longer needed.
2946 However, by default, the build system preserves these files
2947 for inspection and possible debugging purposes.
2948 If you would rather have these files deleted to save disk space
2949 as the build progresses, you can enable <filename>rm_work</filename>
2950 by adding the following to your <filename>local.conf</filename> file,
2951 which is found in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05002952 <link linkend='build-directory'>Build Directory</link>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002953 <literallayout class='monospaced'>
2954 INHERIT += "rm_work"
2955 </literallayout>
2956 If you are modifying and building source code out of the work directory
2957 for a recipe, enabling <filename>rm_work</filename> will potentially
2958 result in your changes to the source being lost.
2959 To exclude some recipes from having their work directories deleted by
2960 <filename>rm_work</filename>, you can add the names of the recipe or
2961 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
2962 variable, which can also be set in your <filename>local.conf</filename>
2963 file.
2964 Here is an example:
2965 <literallayout class='monospaced'>
2966 RM_WORK_EXCLUDE += "busybox glibc"
2967 </literallayout>
2968 </para>
2969</section>
2970
2971<section id='ref-classes-rootfs*'>
2972 <title><filename>rootfs*.bbclass</filename></title>
2973
2974 <para>
2975 The <filename>rootfs*</filename> classes support creating
2976 the root filesystem for an image and consist of the following classes:
2977 <itemizedlist>
2978 <listitem><para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05002979 The <filename>rootfs-postcommands</filename> class, which
2980 defines filesystem post-processing functions for image recipes.
2981 </para></listitem>
2982 <listitem><para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002983 The <filename>rootfs_deb</filename> class, which supports
2984 creation of root filesystems for images built using
2985 <filename>.deb</filename> packages.</para></listitem>
2986 <listitem><para>
2987 The <filename>rootfs_rpm</filename> class, which supports
2988 creation of root filesystems for images built using
2989 <filename>.rpm</filename> packages.</para></listitem>
2990 <listitem><para>
2991 The <filename>rootfs_ipk</filename> class, which supports
2992 creation of root filesystems for images built using
2993 <filename>.ipk</filename> packages.</para></listitem>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05002994 <listitem><para>
2995 The <filename>rootfsdebugfiles</filename> class, which installs
2996 additional files found on the build host directly into the
2997 root filesystem.
2998 </para></listitem>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05002999 </itemizedlist>
3000 </para>
3001
3002 <para>
3003 The root filesystem is created from packages using one of the
3004 <filename>rootfs*.bbclass</filename> files as determined by the
3005 <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
3006 variable.
3007 </para>
3008
3009 <para>
3010 For information on how root filesystem images are created, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003011 "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
3012 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003013 </para>
3014</section>
3015
3016<section id='ref-classes-sanity'>
3017 <title><filename>sanity.bbclass</filename></title>
3018
3019 <para>
3020 The <filename>sanity</filename> class checks to see if prerequisite
3021 software is present on the host system so that users can be notified
3022 of potential problems that might affect their build.
3023 The class also performs basic user configuration checks from
3024 the <filename>local.conf</filename> configuration file to
3025 prevent common mistakes that cause build failures.
3026 Distribution policy usually determines whether to include this class.
3027 </para>
3028</section>
3029
3030<section id='ref-classes-scons'>
3031 <title><filename>scons.bbclass</filename></title>
3032
3033 <para>
3034 The <filename>scons</filename> class supports recipes that need to
3035 build software that uses the SCons build system.
3036 You can use the
3037 <link linkend='var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></link>
3038 variable to specify additional configuration options you want to pass
3039 SCons command line.
3040 </para>
3041</section>
3042
3043<section id='ref-classes-sdl'>
3044 <title><filename>sdl.bbclass</filename></title>
3045
3046 <para>
3047 The <filename>sdl</filename> class supports recipes that need to build
3048 software that uses the Simple DirectMedia Layer (SDL) library.
3049 </para>
3050</section>
3051
3052<section id='ref-classes-setuptools'>
3053 <title><filename>setuptools.bbclass</filename></title>
3054
3055 <para>
3056 The <filename>setuptools</filename> class supports Python
3057 version 2.x extensions that use build systems based on
3058 <filename>setuptools</filename>.
3059 If your recipe uses these build systems, the recipe needs to
3060 inherit the <filename>setuptools</filename> class.
3061 </para>
3062</section>
3063
3064<section id='ref-classes-setuptools3'>
3065 <title><filename>setuptools3.bbclass</filename></title>
3066
3067 <para>
3068 The <filename>setuptools3</filename> class supports Python
3069 version 3.x extensions that use build systems based on
3070 <filename>setuptools3</filename>.
3071 If your recipe uses these build systems, the recipe needs to
3072 inherit the <filename>setuptools3</filename> class.
3073 </para>
3074</section>
3075
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003076<section id='ref-classes-sign_rpm'>
3077 <title><filename>sign_rpm.bbclass</filename></title>
3078
3079 <para>
3080 The <filename>sign_rpm</filename> class supports generating signed
3081 RPM packages.
3082 </para>
3083</section>
3084
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003085<section id='ref-classes-sip'>
3086 <title><filename>sip.bbclass</filename></title>
3087
3088 <para>
3089 The <filename>sip</filename> class
3090 supports recipes that build or package SIP-based Python bindings.
3091 </para>
3092</section>
3093
3094<section id='ref-classes-siteconfig'>
3095 <title><filename>siteconfig.bbclass</filename></title>
3096
3097 <para>
3098 The <filename>siteconfig</filename> class
3099 provides functionality for handling site configuration.
3100 The class is used by the
3101 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
3102 class to accelerate the
3103 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
3104 task.
3105 </para>
3106</section>
3107
3108<section id='ref-classes-siteinfo'>
3109 <title><filename>siteinfo.bbclass</filename></title>
3110
3111 <para>
3112 The <filename>siteinfo</filename> class provides information about
3113 the targets that might be needed by other classes or recipes.
3114 </para>
3115
3116 <para>
3117 As an example, consider Autotools, which can require tests that must
3118 execute on the target hardware.
3119 Since this is not possible in general when cross compiling, site
3120 information is used to provide cached test results so these tests can
3121 be skipped over but still make the correct values available.
3122 The
3123 <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
3124 contains test results sorted into different categories such as
3125 architecture, endianness, and the <filename>libc</filename> used.
3126 Site information provides a list of files containing data relevant to
3127 the current build in the
3128 <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
3129 that Autotools automatically picks up.
3130 </para>
3131
3132 <para>
3133 The class also provides variables like
3134 <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
3135 and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
3136 that can be used elsewhere in the metadata.
3137 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003138</section>
3139
3140<section id='ref-classes-spdx'>
3141 <title><filename>spdx.bbclass</filename></title>
3142
3143 <para>
3144 The <filename>spdx</filename> class integrates real-time license
3145 scanning, generation of SPDX standard output, and verification
3146 of license information during the build.
3147 <note>
3148 This class is currently at the prototype stage in the 1.6
3149 release.
3150 </note>
3151 </para>
3152</section>
3153
3154<section id='ref-classes-sstate'>
3155 <title><filename>sstate.bbclass</filename></title>
3156
3157 <para>
3158 The <filename>sstate</filename> class provides support for Shared
3159 State (sstate).
3160 By default, the class is enabled through the
3161 <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
3162 variable's default value.
3163 </para>
3164
3165 <para>
3166 For more information on sstate, see the
Brad Bishop316dfdd2018-06-25 12:45:53 -04003167 "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>"
3168 section in the Yocto Project Overview and Concepts Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003169 </para>
3170</section>
3171
3172<section id='ref-classes-staging'>
3173 <title><filename>staging.bbclass</filename></title>
3174
3175 <para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003176 The <filename>staging</filename> class installs files into individual
3177 recipe work directories for sysroots.
3178 The class contains the following key tasks:
3179 <itemizedlist>
3180 <listitem><para>
3181 The
3182 <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
3183 task, which is responsible for handing the files that end up
3184 in the recipe sysroots.
3185 </para></listitem>
3186 <listitem><para>
3187 The
3188 <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
3189 task (a "partner" task to the
3190 <filename>populate_sysroot</filename> task), which installs
3191 the files into the individual recipe work directories (i.e.
3192 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
3193 </para></listitem>
3194 </itemizedlist>
3195 </para>
3196
3197 <para>
3198 The code in the <filename>staging</filename> class is complex and
3199 basically works in two stages:
3200 <itemizedlist>
3201 <listitem><para>
3202 <emphasis>Stage One:</emphasis>
3203 The first stage addresses recipes that have files they want
3204 to share with other recipes that have dependencies on the
3205 originating recipe.
3206 Normally these dependencies are installed through the
3207 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
3208 task into
3209 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
3210 The <filename>do_populate_sysroot</filename> task copies
3211 a subset of these files into
3212 <filename>${SYSROOT_DESTDIR}</filename>.
3213 This subset of files is controlled by the
3214 <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
3215 <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
3216 and
3217 <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>
3218 variables.
3219 <note>
3220 Additionally, a recipe can customize the files further by
3221 declaring a processing function in the
3222 <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>
3223 variable.
3224 </note>
3225 </para>
3226
3227 <para>
3228 A shared state (sstate) object is built from these files
3229 and the files are placed into a subdirectory of
3230 <link linkend='structure-build-tmp-sysroots-components'><filename>tmp/sysroots-components/</filename></link>.
3231 The files are scanned for hardcoded paths to the original
3232 installation location.
3233 If the location is found in text files, the hardcoded
3234 locations are replaced by tokens and a list of the files
3235 needing such replacements is created.
3236 These adjustments are referred to as "FIXMEs".
3237 The list of files that are scanned for paths is controlled by
3238 the
3239 <link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link>
3240 variable.
3241 </para></listitem>
3242 <listitem><para>
3243 <emphasis>Stage Two:</emphasis>
3244 The second stage addresses recipes that want to use something
3245 from another recipe and declare a dependency on that recipe
3246 through the
3247 <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
3248 variable.
3249 The recipe will have a
3250 <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
3251 task and when
3252 this task executes, it creates the
3253 <filename>recipe-sysroot</filename> and
3254 <filename>recipe-sysroot-native</filename> in the recipe
3255 work directory (i.e.
3256 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
3257 The OpenEmbedded build system creates hard links to copies of the
3258 relevant files from <filename>sysroots-components</filename>
3259 into the recipe work directory.
3260 <note>
3261 If hard links are not possible, the build system uses
3262 actual copies.
3263 </note>
3264 The build system then addresses any "FIXMEs" to paths as
3265 defined from the list created in the first stage.
3266 </para>
3267
3268 <para>
3269 Finally, any files in <filename>${bindir}</filename>
3270 within the sysroot that have the prefix
3271 "<filename>postinst-</filename>" are executed.
3272 <note>
3273 Although such sysroot post installation scripts are not
3274 recommended for general use, the files do allow some issues
3275 such as user creation and module indexes to be addressed.
3276 </note>
3277 </para>
3278
3279 <para>
3280 Because recipes can have other dependencies outside of
3281 <filename>DEPENDS</filename> (e.g.
3282 <filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>),
3283 the sysroot creation function
3284 <filename>extend_recipe_sysroot</filename> is also added as
3285 a pre-function for those tasks whose dependencies are not
3286 through <filename>DEPENDS</filename> but operate similarly.
3287 </para>
3288
3289 <para>
3290 When installing dependencies into the sysroot, the code
3291 traverses the dependency graph and processes dependencies
3292 in exactly the same way as the dependencies would or would not
3293 be when installed from sstate.
3294 This processing means, for example, a native tool would have
3295 its native dependencies added but a target library would not
3296 have its dependencies traversed or installed.
3297 The same sstate dependency code is used so that
3298 builds should be identical regardless of whether sstate
3299 was used or not.
3300 For a closer look, see the
3301 <filename>setscene_depvalid()</filename> function in the
3302 <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
3303 class.
3304 </para>
3305
3306 <para>
3307 The build system is careful to maintain manifests of the files
3308 it installs so that any given dependency can be installed as
3309 needed.
3310 The sstate hash of the installed item is also stored so that
3311 if it changes, the build system can reinstall it.
3312 </para></listitem>
3313 </itemizedlist>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003314 </para>
3315</section>
3316
3317<section id='ref-classes-syslinux'>
3318 <title><filename>syslinux.bbclass</filename></title>
3319
3320 <para>
3321 The <filename>syslinux</filename> class provides syslinux-specific
3322 functions for building bootable images.
3323 </para>
3324
3325 <para>
3326 The class supports the following variables:
3327 <itemizedlist>
3328 <listitem><para><link linkend='var-INITRD'><filename>INITRD</filename></link>:
3329 Indicates list of filesystem images to concatenate and use as
3330 an initial RAM disk (initrd).
3331 This variable is optional.</para></listitem>
3332 <listitem><para><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
3333 Indicates a filesystem image to include as the root filesystem.
3334 This variable is optional.</para></listitem>
3335 <listitem><para><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>:
3336 Enables creating an automatic menu when set to "1".
3337 </para></listitem>
3338 <listitem><para><link linkend='var-LABELS'><filename>LABELS</filename></link>:
3339 Lists targets for automatic configuration.
3340 </para></listitem>
3341 <listitem><para><link linkend='var-APPEND'><filename>APPEND</filename></link>:
3342 Lists append string overrides for each label.
3343 </para></listitem>
3344 <listitem><para><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>:
3345 Lists additional options to add to the syslinux file.
3346 Semicolon characters separate multiple options.
3347 </para></listitem>
3348 <listitem><para><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>:
3349 Lists a background for the VGA boot menu when you are using the
3350 boot menu.</para></listitem>
3351 <listitem><para><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>:
3352 Set to "console=ttyX" to change kernel boot default console.
3353 </para></listitem>
3354 <listitem><para><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>:
3355 Sets an alternate serial port.
3356 Or, turns off serial when the variable is set with an
3357 empty string.</para></listitem>
3358 <listitem><para><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>:
3359 Sets an alternate "console=tty..." kernel boot argument.
3360 </para></listitem>
3361 </itemizedlist>
3362 </para>
3363</section>
3364
3365<section id='ref-classes-systemd'>
3366 <title><filename>systemd.bbclass</filename></title>
3367
3368 <para>
3369 The <filename>systemd</filename> class provides support for recipes
3370 that install systemd unit files.
3371 </para>
3372
3373 <para>
3374 The functionality for this class is disabled unless you have "systemd"
3375 in
3376 <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
3377 </para>
3378
3379 <para>
3380 Under this class, the recipe or Makefile (i.e. whatever the recipe is
3381 calling during the
3382 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
3383 task) installs unit files into
3384 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>.
3385 If the unit files being installed go into packages other than the
3386 main package, you need to set
3387 <link linkend='var-SYSTEMD_PACKAGES'><filename>SYSTEMD_PACKAGES</filename></link>
3388 in your recipe to identify the packages in which the files will be
3389 installed.
3390 </para>
3391
3392 <para>
3393 You should set
3394 <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
3395 to the name of the service file.
3396 You should also use a package name override to indicate the package
3397 to which the value applies.
3398 If the value applies to the recipe's main package, use
3399 <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>.
3400 Here is an example from the connman recipe:
3401 <literallayout class='monospaced'>
3402 SYSTEMD_SERVICE_${PN} = "connman.service"
3403 </literallayout>
3404 Services are set up to start on boot automatically unless
3405 you have set
3406 <link linkend='var-SYSTEMD_AUTO_ENABLE'><filename>SYSTEMD_AUTO_ENABLE</filename></link>
3407 to "disable".
3408 </para>
3409
3410 <para>
3411 For more information on <filename>systemd</filename>, see the
3412 "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager'>Selecting an Initialization Manager</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003413 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003414 </para>
3415</section>
3416
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003417<section id='ref-classes-systemd-boot'>
3418 <title><filename>systemd-boot.bbclass</filename></title>
3419
3420 <para>
3421 The <filename>systemd-boot</filename> class provides functions specific
3422 to the systemd-boot bootloader for building bootable images.
3423 This is an internal class and is not intended to be used directly.
3424 <note>
3425 The <filename>systemd-boot</filename> class is a result from
3426 merging the <filename>gummiboot</filename> class used in previous
3427 Yocto Project releases with the <filename>systemd</filename>
3428 project.
3429 </note>
3430 Set the
3431 <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
3432 variable to "systemd-boot" to use this class.
3433 Doing so creates a standalone EFI bootloader that is not dependent
3434 on systemd.
3435 </para>
3436
3437 <para>
3438 For information on more variables used and supported in this class,
3439 see the
3440 <link linkend='var-SYSTEMD_BOOT_CFG'><filename>SYSTEMD_BOOT_CFG</filename></link>,
3441 <link linkend='var-SYSTEMD_BOOT_ENTRIES'><filename>SYSTEMD_BOOT_ENTRIES</filename></link>,
3442 and
3443 <link linkend='var-SYSTEMD_BOOT_TIMEOUT'><filename>SYSTEMD_BOOT_TIMEOUT</filename></link>
3444 variables.
3445 </para>
3446
3447 <para>
3448 You can also see the
3449 <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>
3450 for more information.
3451 </para>
3452</section>
3453
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003454<section id='ref-classes-terminal'>
3455 <title><filename>terminal.bbclass</filename></title>
3456
3457 <para>
3458 The <filename>terminal</filename> class provides support for starting
3459 a terminal session.
3460 The
3461 <link linkend='var-OE_TERMINAL'><filename>OE_TERMINAL</filename></link>
3462 variable controls which terminal emulator is used for the session.
3463 </para>
3464
3465 <para>
3466 Other classes use the <filename>terminal</filename> class anywhere a
3467 separate terminal session needs to be started.
3468 For example, the
3469 <link linkend='ref-classes-patch'><filename>patch</filename></link>
3470 class assuming
3471 <link linkend='var-PATCHRESOLVE'><filename>PATCHRESOLVE</filename></link>
3472 is set to "user", the
3473 <link linkend='ref-classes-cml1'><filename>cml1</filename></link>
3474 class, and the
3475 <link linkend='ref-classes-devshell'><filename>devshell</filename></link>
3476 class all use the <filename>terminal</filename> class.
3477 </para>
3478</section>
3479
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003480<section id='ref-classes-testimage*'>
3481 <title><filename>testimage*.bbclass</filename></title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003482
3483 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003484 The <filename>testimage*</filename> classes support running
3485 automated tests against images using QEMU and on actual hardware.
3486 The classes handle loading the tests and starting the image.
3487 To use the classes, you need to perform steps to set up the
3488 environment.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08003489 <note><title>Tip</title>
3490 Best practices include using
3491 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3492 rather than
3493 <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to
3494 inherit the <filename>testimage</filename> class for automated
3495 image testing.
3496 </note>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003497 </para>
3498
3499 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003500 The tests are commands that run on the target system over
3501 <filename>ssh</filename>.
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003502 Each test is written in Python and makes use of the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003503 <filename>unittest</filename> module.
3504 </para>
3505
3506 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003507 The <filename>testimage.bbclass</filename> runs tests on an image
3508 when called using the following:
3509 <literallayout class='monospaced'>
3510 $ bitbake -c testimage <replaceable>image</replaceable>
3511 </literallayout>
3512 The <filename>testimage-auto</filename> class runs tests on an image
3513 after the image is constructed (i.e.
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08003514 <link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003515 must be set to "1").
3516 </para>
3517
3518 <para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003519 For information on how to enable, run, and create new tests, see the
3520 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003521 section in the Yocto Project Development Tasks Manual.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003522 </para>
3523</section>
3524
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003525<section id='ref-classes-testsdk'>
3526 <title><filename>testsdk.bbclass</filename></title>
3527
3528 <para>
3529 This class supports running automated tests against
3530 software development kits (SDKs).
3531 The <filename>testsdk</filename> class runs tests on an SDK when
3532 called using the following:
3533 <literallayout class='monospaced'>
3534 $ bitbake -c testsdk image
3535 </literallayout>
Brad Bishop1a4b7ee2018-12-16 17:11:34 -08003536 <note><title>Tip</title>
3537 Best practices include using
3538 <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
3539 rather than
3540 <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to
3541 inherit the <filename>testsdk</filename> class for automated
3542 SDK testing.
3543 </note>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003544 </para>
3545</section>
3546
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003547<section id='ref-classes-texinfo'>
3548 <title><filename>texinfo.bbclass</filename></title>
3549
3550 <para>
3551 This class should be inherited by recipes whose upstream packages
3552 invoke the <filename>texinfo</filename> utilities at build-time.
3553 Native and cross recipes are made to use the dummy scripts provided
3554 by <filename>texinfo-dummy-native</filename>, for improved performance.
3555 Target architecture recipes use the genuine
3556 Texinfo utilities.
3557 By default, they use the Texinfo utilities on the host system.
3558 <note>
3559 If you want to use the Texinfo recipe shipped with the build
3560 system, you can remove "texinfo-native" from
3561 <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
3562 and makeinfo from
3563 <link linkend='var-SANITY_REQUIRED_UTILITIES'><filename>SANITY_REQUIRED_UTILITIES</filename></link>.
3564 </note>
3565 </para>
3566</section>
3567
3568<section id='ref-classes-tinderclient'>
3569 <title><filename>tinderclient.bbclass</filename></title>
3570
3571 <para>
3572 The <filename>tinderclient</filename> class submits build results to
3573 an external Tinderbox instance.
3574 <note>
3575 This class is currently unmaintained.
3576 </note>
3577 </para>
3578</section>
3579
3580<section id='ref-classes-toaster'>
3581 <title><filename>toaster.bbclass</filename></title>
3582
3583 <para>
3584 The <filename>toaster</filename> class collects information about
3585 packages and images and sends them as events that the BitBake
3586 user interface can receive.
3587 The class is enabled when the Toaster user interface is running.
3588 </para>
3589
3590 <para>
3591 This class is not intended to be used directly.
3592 </para>
3593</section>
3594
3595<section id='ref-classes-toolchain-scripts'>
3596 <title><filename>toolchain-scripts.bbclass</filename></title>
3597
3598 <para>
3599 The <filename>toolchain-scripts</filename> class provides the scripts
3600 used for setting up the environment for installed SDKs.
3601 </para>
3602</section>
3603
3604<section id='ref-classes-typecheck'>
3605 <title><filename>typecheck.bbclass</filename></title>
3606
3607 <para>
3608 The <filename>typecheck</filename> class provides support for
3609 validating the values of variables set at the configuration level
3610 against their defined types.
3611 The OpenEmbedded build system allows you to define the type of a
3612 variable using the "type" varflag.
3613 Here is an example:
3614 <literallayout class='monospaced'>
3615 IMAGE_FEATURES[type] = "list"
3616 </literallayout>
3617 </para>
3618</section>
3619
3620<section id='ref-classes-uboot-config'>
3621 <title><filename>uboot-config.bbclass</filename></title>
3622
3623 <para>
3624 The <filename>uboot-config</filename> class provides support for
3625 U-Boot configuration for a machine.
3626 Specify the machine in your recipe as follows:
3627 <literallayout class='monospaced'>
3628 UBOOT_CONFIG ??= &lt;default&gt;
3629 UBOOT_CONFIG[foo] = "config,images"
3630 </literallayout>
3631 You can also specify the machine using this method:
3632 <literallayout class='monospaced'>
3633 UBOOT_MACHINE = "config"
3634 </literallayout>
3635 See the
3636 <link linkend='var-UBOOT_CONFIG'><filename>UBOOT_CONFIG</filename></link>
3637 and
3638 <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
3639 variables for additional information.
3640 </para>
3641</section>
3642
3643<section id='ref-classes-uninative'>
3644 <title><filename>uninative.bbclass</filename></title>
3645
3646 <para>
Patrick Williamsd8c66bc2016-06-20 12:57:21 -05003647 Attempts to isolate the build system from the host
3648 distribution's C library in order to make re-use of native shared state
3649 artifacts across different host distributions practical.
3650 With this class enabled, a tarball containing a pre-built C library
3651 is downloaded at the start of the build.
3652 In the Poky reference distribution this is enabled by default
3653 through
3654 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>.
3655 Other distributions that do not derive from poky can also
3656 "<filename>require conf/distro/include/yocto-uninative.inc</filename>"
3657 to use this.
3658 Alternatively if you prefer, you can build the uninative-tarball recipe
3659 yourself, publish the resulting tarball (e.g. via HTTP) and set
3660 <filename>UNINATIVE_URL</filename> and
3661 <filename>UNINATIVE_CHECKSUM</filename> appropriately.
3662 For an example, see the
3663 <filename>meta/conf/distro/include/yocto-uninative.inc</filename>.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003664 </para>
Brad Bishop6e60e8b2018-02-01 10:27:11 -05003665
3666 <para>
3667 The <filename>uninative</filename> class is also used unconditionally
3668 by the extensible SDK.
3669 When building the extensible SDK,
3670 <filename>uninative-tarball</filename> is built and the resulting
3671 tarball is included within the SDK.
3672 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003673</section>
3674
3675<section id='ref-classes-update-alternatives'>
3676 <title><filename>update-alternatives.bbclass</filename></title>
3677
3678 <para>
3679 The <filename>update-alternatives</filename> class helps the
3680 alternatives system when multiple sources provide the same command.
3681 This situation occurs when several programs that have the same or
3682 similar function are installed with the same name.
3683 For example, the <filename>ar</filename> command is available from the
3684 <filename>busybox</filename>, <filename>binutils</filename> and
3685 <filename>elfutils</filename> packages.
3686 The <filename>update-alternatives</filename> class handles
3687 renaming the binaries so that multiple packages can be installed
3688 without conflicts.
3689 The <filename>ar</filename> command still works regardless of which
3690 packages are installed or subsequently removed.
3691 The class renames the conflicting binary in each package and symlinks
3692 the highest priority binary during installation or removal of packages.
3693 </para>
3694
3695 <para>
3696 To use this class, you need to define a number of variables:
3697 <itemizedlist>
3698 <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
3699 </para></listitem>
3700 <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
3701 </para></listitem>
3702 <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
3703 </para></listitem>
3704 <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
3705 </para></listitem>
3706 </itemizedlist>
3707 These variables list alternative commands needed by a package,
3708 provide pathnames for links, default links for targets, and
3709 so forth.
3710 For details on how to use this class, see the comments in the
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003711 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>
3712 file.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003713 </para>
3714
3715 <note>
3716 You can use the <filename>update-alternatives</filename> command
3717 directly in your recipes.
3718 However, this class simplifies things in most cases.
3719 </note>
3720</section>
3721
3722<section id='ref-classes-update-rc.d'>
3723 <title><filename>update-rc.d.bbclass</filename></title>
3724
3725 <para>
3726 The <filename>update-rc.d</filename> class uses
3727 <filename>update-rc.d</filename> to safely install an
3728 initialization script on behalf of the package.
3729 The OpenEmbedded build system takes care of details such as making
3730 sure the script is stopped before a package is removed and started when
3731 the package is installed.
3732 </para>
3733
3734 <para>
3735 Three variables control this class:
3736 <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
3737 <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
3738 <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
3739 See the variable links for details.
3740 </para>
3741</section>
3742
3743<section id='ref-classes-useradd'>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003744 <title><filename>useradd*.bbclass</filename></title>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003745
3746 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003747 The <filename>useradd*</filename> classes support the addition of users
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003748 or groups for usage by the package on the target.
3749 For example, if you have packages that contain system services that
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003750 should be run under their own user or group, you can use these classes
3751 to enable creation of the user or group.
Brad Bishopd7bf8c12018-02-25 22:55:05 -05003752 The
3753 <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
3754 recipe in the <link linkend='source-directory'>Source Directory</link>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003755 provides a simple example that shows how to add three
3756 users and groups to two packages.
3757 See the <filename>useradd-example.bb</filename> recipe for more
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003758 information on how to use these classes.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003759 </para>
3760
3761 <para>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003762 The <filename>useradd_base</filename> class provides basic
3763 functionality for user or groups settings.
3764 </para>
3765
3766 <para>
3767 The <filename>useradd*</filename> classes support the
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003768 <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>,
3769 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
3770 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
3771 and
3772 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
3773 variables.
3774 </para>
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003775
3776 <para>
3777 The <filename>useradd-staticids</filename> class supports the addition
3778 of users or groups that have static user identification
3779 (<filename>uid</filename>) and group identification
3780 (<filename>gid</filename>) values.
3781 </para>
3782
3783 <para>
3784 The default behavior of the OpenEmbedded build system for assigning
3785 <filename>uid</filename> and <filename>gid</filename> values when
3786 packages add users and groups during package install time is to
3787 add them dynamically.
3788 This works fine for programs that do not care what the values of the
3789 resulting users and groups become.
3790 In these cases, the order of the installation determines the final
3791 <filename>uid</filename> and <filename>gid</filename> values.
3792 However, if non-deterministic
3793 <filename>uid</filename> and <filename>gid</filename> values are a
3794 problem, you can override the default, dynamic application of these
3795 values by setting static values.
3796 When you set static values, the OpenEmbedded build system looks in
3797 <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
3798 <filename>files/passwd</filename> and <filename>files/group</filename>
3799 files for the values.
3800 </para>
3801
3802 <para>
3803 To use static <filename>uid</filename> and <filename>gid</filename>
3804 values, you need to set some variables.
3805 See the
3806 <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
3807 <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
3808 <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
3809 and
3810 <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
3811 variables.
3812 You can also see the
3813 <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
3814 class for additional information.
3815 </para>
3816
3817 <note><title>Notes</title>
Patrick Williamsf1e5d692016-03-30 15:21:19 -05003818 You do not use the <filename>useradd-staticids</filename>
3819 class directly.
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003820 You either enable or disable the class by setting the
3821 <filename>USERADDEXTENSION</filename> variable.
3822 If you enable or disable the class in a configured system,
3823 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
3824 might contain incorrect <filename>uid</filename> and
3825 <filename>gid</filename> values.
3826 Deleting the <filename>TMPDIR</filename> directory
3827 will correct this condition.
3828 </note>
3829</section>
3830
3831<section id='ref-classes-utility-tasks'>
3832 <title><filename>utility-tasks.bbclass</filename></title>
3833
3834 <para>
3835 The <filename>utility-tasks</filename> class provides support for
3836 various "utility" type tasks that are applicable to all recipes,
3837 such as
3838 <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and
3839 <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>.
3840 </para>
3841
3842 <para>
3843 This class is enabled by default because it is inherited by
3844 the
3845 <link linkend='ref-classes-base'><filename>base</filename></link>
3846 class.
3847 </para>
3848</section>
3849
3850<section id='ref-classes-utils'>
3851 <title><filename>utils.bbclass</filename></title>
3852
3853 <para>
3854 The <filename>utils</filename> class provides some useful Python
3855 functions that are typically used in inline Python expressions
3856 (e.g. <filename>${@...}</filename>).
3857 One example use is for <filename>bb.utils.contains()</filename>.
3858 </para>
3859
3860 <para>
3861 This class is enabled by default because it is inherited by the
3862 <link linkend='ref-classes-base'><filename>base</filename></link>
3863 class.
3864 </para>
3865</section>
3866
3867<section id='ref-classes-vala'>
3868 <title><filename>vala.bbclass</filename></title>
3869
3870 <para>
3871 The <filename>vala</filename> class supports recipes that need to
3872 build software written using the Vala programming language.
3873 </para>
3874</section>
3875
3876<section id='ref-classes-waf'>
3877 <title><filename>waf.bbclass</filename></title>
3878
3879 <para>
3880 The <filename>waf</filename> class supports recipes that need to build
3881 software that uses the Waf build system.
3882 You can use the
3883 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
Patrick Williamsc0f7c042017-02-23 20:41:17 -06003884 or
3885 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
3886 variables to specify additional configuration options to be passed on
Patrick Williamsc124f4f2015-09-15 14:41:29 -05003887 the Waf command line.
3888 </para>
3889</section>
3890
3891<!-- Undocumented classes are:
3892 image-empty.bbclass (possibly being dropped)
3893 migrate_localcount.bbclass (still need a description)
3894-->
3895
3896
3897</chapter>
3898<!--
3899vim: expandtab tw=80 ts=4
3900-->