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