blob: 6dd0cbbd41dba900c55843ce8c58003c339ff019 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3*******
4Classes
5*******
6
7Class files are used to abstract common functionality and share it
8amongst multiple recipe (``.bb``) files. To use a class file, you simply
9make sure the recipe inherits the class. In most cases, when a recipe
10inherits a class it is enough to enable its features. There are cases,
11however, where in the recipe you might need to set variables or override
12some default behavior.
13
14Any :term:`Metadata` usually found in a recipe can also be
15placed in a class file. Class files are identified by the extension
16``.bbclass`` and are usually placed in a ``classes/`` directory beneath
17the ``meta*/`` directory found in the :term:`Source Directory`.
18Class files can also be pointed to by
19:term:`BUILDDIR` (e.g. ``build/``) in the same way as
20``.conf`` files in the ``conf`` directory. Class files are searched for
21in :term:`BBPATH` using the same method by which ``.conf``
22files are searched.
23
24This chapter discusses only the most useful and important classes. Other
25classes do exist within the ``meta/classes`` directory in the Source
26Directory. You can reference the ``.bbclass`` files directly for more
27information.
28
29.. _ref-classes-allarch:
30
31``allarch.bbclass``
32===================
33
34The ``allarch`` class is inherited by recipes that do not produce
35architecture-specific output. The class disables functionality that is
36normally needed for recipes that produce executable binaries (such as
37building the cross-compiler and a C library as pre-requisites, and
38splitting out of debug symbols during packaging).
39
40.. note::
41
42 Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes that
43 produce packages that depend on tunings through use of the
44 :term:`RDEPENDS` and
45 :term:`TUNE_PKGARCH` variables, should never be
46 configured for all architectures using ``allarch``. This is the case
47 even if the recipes do not produce architecture-specific output.
48
49 Configuring such recipes for all architectures causes the
Andrew Geissler4c19ea12020-10-27 13:52:24 -050050 ``do_package_write_*`` tasks to
Andrew Geisslerc9f78652020-09-18 14:11:35 -050051 have different signatures for the machines with different tunings.
52 Additionally, unnecessary rebuilds occur every time an image for a
53 different ``MACHINE`` is built even when the recipe never changes.
54
55By default, all recipes inherit the :ref:`base <ref-classes-base>` and
56:ref:`package <ref-classes-package>` classes, which enable
57functionality needed for recipes that produce executable output. If your
58recipe, for example, only produces packages that contain configuration
59files, media files, or scripts (e.g. Python and Perl), then it should
60inherit the ``allarch`` class.
61
62.. _ref-classes-archiver:
63
64``archiver.bbclass``
65====================
66
67The ``archiver`` class supports releasing source code and other
68materials with the binaries.
69
70For more details on the source archiver, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060071":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072section in the Yocto Project Development Tasks Manual. You can also see
73the :term:`ARCHIVER_MODE` variable for information
74about the variable flags (varflags) that help control archive creation.
75
76.. _ref-classes-autotools:
77
78``autotools*.bbclass``
79======================
80
81The ``autotools*`` classes support Autotooled packages.
82
83The ``autoconf``, ``automake``, and ``libtool`` packages bring
84standardization. This class defines a set of tasks (e.g. ``configure``,
85``compile`` and so forth) that work for all Autotooled packages. It
86should usually be enough to define a few standard variables and then
87simply ``inherit autotools``. These classes can also work with software
88that emulates Autotools. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060089":ref:`dev-manual/common-tasks:autotooled package`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090in the Yocto Project Development Tasks Manual.
91
92By default, the ``autotools*`` classes use out-of-tree builds (i.e.
93``autotools.bbclass`` building with ``B != S``).
94
95If the software being built by a recipe does not support using
96out-of-tree builds, you should have the recipe inherit the
97``autotools-brokensep`` class. The ``autotools-brokensep`` class behaves
98the same as the ``autotools`` class but builds with :term:`B`
99== :term:`S`. This method is useful when out-of-tree build
100support is either not present or is broken.
101
102.. note::
103
104 It is recommended that out-of-tree support be fixed and used if at
105 all possible.
106
107It's useful to have some idea of how the tasks defined by the
108``autotools*`` classes work and what they do behind the scenes.
109
110- :ref:`ref-tasks-configure` - Regenerates the
111 configure script (using ``autoreconf``) and then launches it with a
112 standard set of arguments used during cross-compilation. You can pass
113 additional parameters to ``configure`` through the ``EXTRA_OECONF``
114 or :term:`PACKAGECONFIG_CONFARGS`
115 variables.
116
117- :ref:`ref-tasks-compile` - Runs ``make`` with
118 arguments that specify the compiler and linker. You can pass
119 additional arguments through the ``EXTRA_OEMAKE`` variable.
120
121- :ref:`ref-tasks-install` - Runs ``make install`` and
122 passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``.
123
124.. _ref-classes-base:
125
126``base.bbclass``
127================
128
129The ``base`` class is special in that every ``.bb`` file implicitly
130inherits the class. This class contains definitions for standard basic
131tasks such as fetching, unpacking, configuring (empty by default),
132compiling (runs any ``Makefile`` present), installing (empty by default)
133and packaging (empty by default). These classes are often overridden or
134extended by other classes such as the
135:ref:`autotools <ref-classes-autotools>` class or the
136:ref:`package <ref-classes-package>` class.
137
138The class also contains some commonly used functions such as
139``oe_runmake``, which runs ``make`` with the arguments specified in
140:term:`EXTRA_OEMAKE` variable as well as the
141arguments passed directly to ``oe_runmake``.
142
143.. _ref-classes-bash-completion:
144
145``bash-completion.bbclass``
146===========================
147
148Sets up packaging and dependencies appropriate for recipes that build
149software that includes bash-completion data.
150
151.. _ref-classes-bin-package:
152
153``bin_package.bbclass``
154=======================
155
156The ``bin_package`` class is a helper class for recipes that extract the
157contents of a binary package (e.g. an RPM) and install those contents
158rather than building the binary from source. The binary package is
159extracted and new packages in the configured output package format are
160created. Extraction and installation of proprietary binaries is a good
161example use for this class.
162
163.. note::
164
165 For RPMs and other packages that do not contain a subdirectory, you
166 should specify an appropriate fetcher parameter to point to the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500167 subdirectory. For example, if BitBake is using the Git fetcher (``git://``),
168 the "subpath" parameter limits the checkout to a specific subpath
169 of the tree. Here is an example where ``${BP}`` is used so that the files
170 are extracted into the subdirectory expected by the default value of
Andrew Geisslerc926e172021-05-07 16:11:35 -0500171 ``S``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500172
173 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
174
175
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500176 See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for
177 more information on supported BitBake Fetchers.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500178
179.. _ref-classes-binconfig:
180
181``binconfig.bbclass``
182=====================
183
184The ``binconfig`` class helps to correct paths in shell scripts.
185
186Before ``pkg-config`` had become widespread, libraries shipped shell
187scripts to give information about the libraries and include paths needed
188to build software (usually named ``LIBNAME-config``). This class assists
189any recipe using such scripts.
190
191During staging, the OpenEmbedded build system installs such scripts into
192the ``sysroots/`` directory. Inheriting this class results in all paths
193in these scripts being changed to point into the ``sysroots/`` directory
194so that all builds that use the script use the correct directories for
195the cross compiling layout. See the
196:term:`BINCONFIG_GLOB` variable for more
197information.
198
199.. _ref-classes-binconfig-disabled:
200
201``binconfig-disabled.bbclass``
202==============================
203
204An alternative version of the :ref:`binconfig <ref-classes-binconfig>`
205class, which disables binary configuration scripts by making them return
206an error in favor of using ``pkg-config`` to query the information. The
207scripts to be disabled should be specified using the
208:term:`BINCONFIG` variable within the recipe inheriting
209the class.
210
211.. _ref-classes-blacklist:
212
213``blacklist.bbclass``
214=====================
215
216The ``blacklist`` class prevents the OpenEmbedded build system from
217building specific recipes (blacklists them). To use this class, inherit
218the class globally and set :term:`PNBLACKLIST` for
219each recipe you wish to blacklist. Specify the :term:`PN`
220value as a variable flag (varflag) and provide a reason, which is
221reported, if the package is requested to be built as the value. For
222example, if you want to blacklist a recipe called "exoticware", you add
Andrew Geisslerc926e172021-05-07 16:11:35 -0500223the following to your ``local.conf`` or distribution configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500224
225 INHERIT += "blacklist"
226 PNBLACKLIST[exoticware] = "Not supported by our organization."
227
228.. _ref-classes-buildhistory:
229
230``buildhistory.bbclass``
231========================
232
233The ``buildhistory`` class records a history of build output metadata,
234which can be used to detect possible regressions as well as used for
235analysis of the build output. For more information on using Build
236History, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600237":ref:`dev-manual/common-tasks:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500238section in the Yocto Project Development Tasks Manual.
239
240.. _ref-classes-buildstats:
241
242``buildstats.bbclass``
243======================
244
245The ``buildstats`` class records performance statistics about each task
246executed during the build (e.g. elapsed time, CPU usage, and I/O usage).
247
248When you use this class, the output goes into the
249:term:`BUILDSTATS_BASE` directory, which defaults
250to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using
251``scripts/pybootchartgui/pybootchartgui.py``, which produces a cascading
252chart of the entire build process and can be useful for highlighting
253bottlenecks.
254
255Collecting build statistics is enabled by default through the
256:term:`USER_CLASSES` variable from your
257``local.conf`` file. Consequently, you do not have to do anything to
258enable the class. However, if you want to disable the class, simply
259remove "buildstats" from the ``USER_CLASSES`` list.
260
261.. _ref-classes-buildstats-summary:
262
263``buildstats-summary.bbclass``
264==============================
265
266When inherited globally, prints statistics at the end of the build on
267sstate re-use. In order to function, this class requires the
268:ref:`buildstats <ref-classes-buildstats>` class be enabled.
269
270.. _ref-classes-ccache:
271
272``ccache.bbclass``
273==================
274
275The ``ccache`` class enables the C/C++ Compiler Cache for the build.
276This class is used to give a minor performance boost during the build.
277However, using the class can lead to unexpected side-effects. Thus, it
278is recommended that you do not use this class. See
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600279https://ccache.samba.org/ for information on the C/C++ Compiler
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280Cache.
281
282.. _ref-classes-chrpath:
283
284``chrpath.bbclass``
285===================
286
287The ``chrpath`` class is a wrapper around the "chrpath" utility, which
288is used during the build process for ``nativesdk``, ``cross``, and
289``cross-canadian`` recipes to change ``RPATH`` records within binaries
290in order to make them relocatable.
291
292.. _ref-classes-clutter:
293
294``clutter.bbclass``
295===================
296
297The ``clutter`` class consolidates the major and minor version naming
298and other common items used by Clutter and related recipes.
299
300.. note::
301
302 Unlike some other classes related to specific libraries, recipes
303 building other software that uses Clutter do not need to inherit this
304 class unless they use the same recipe versioning scheme that the
305 Clutter and related recipes do.
306
307.. _ref-classes-cmake:
308
309``cmake.bbclass``
310=================
311
312The ``cmake`` class allows for recipes that need to build software using
313the `CMake <https://cmake.org/overview/>`__ build system. You can use
314the :term:`EXTRA_OECMAKE` variable to specify
315additional configuration options to be passed using the ``cmake``
316command line.
317
318On the occasion that you would be installing custom CMake toolchain
319files supplied by the application being built, you should install them
320to the preferred CMake Module directory: ``${D}${datadir}/cmake/``
321Modules during
322:ref:`ref-tasks-install`.
323
324.. _ref-classes-cml1:
325
326``cml1.bbclass``
327================
328
329The ``cml1`` class provides basic support for the Linux kernel style
330build configuration system.
331
332.. _ref-classes-compress_doc:
333
334``compress_doc.bbclass``
335========================
336
337Enables compression for man pages and info pages. This class is intended
338to be inherited globally. The default compression mechanism is gz (gzip)
339but you can select an alternative mechanism by setting the
340:term:`DOC_COMPRESS` variable.
341
342.. _ref-classes-copyleft_compliance:
343
344``copyleft_compliance.bbclass``
345===============================
346
347The ``copyleft_compliance`` class preserves source code for the purposes
348of license compliance. This class is an alternative to the ``archiver``
349class and is still used by some users even though it has been deprecated
350in favor of the :ref:`archiver <ref-classes-archiver>` class.
351
352.. _ref-classes-copyleft_filter:
353
354``copyleft_filter.bbclass``
355===========================
356
357A class used by the :ref:`archiver <ref-classes-archiver>` and
358:ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes
359for filtering licenses. The ``copyleft_filter`` class is an internal
360class and is not intended to be used directly.
361
362.. _ref-classes-core-image:
363
364``core-image.bbclass``
365======================
366
367The ``core-image`` class provides common definitions for the
368``core-image-*`` image recipes, such as support for additional
369:term:`IMAGE_FEATURES`.
370
371.. _ref-classes-cpan:
372
373``cpan*.bbclass``
374=================
375
376The ``cpan*`` classes support Perl modules.
377
378Recipes for Perl modules are simple. These recipes usually only need to
379point to the source's archive and then inherit the proper class file.
380Building is split into two methods depending on which method the module
381authors used.
382
383- Modules that use old ``Makefile.PL``-based build system require
384 ``cpan.bbclass`` in their recipes.
385
386- Modules that use ``Build.PL``-based build system require using
387 ``cpan_build.bbclass`` in their recipes.
388
389Both build methods inherit the ``cpan-base`` class for basic Perl
390support.
391
392.. _ref-classes-cross:
393
394``cross.bbclass``
395=================
396
397The ``cross`` class provides support for the recipes that build the
398cross-compilation tools.
399
400.. _ref-classes-cross-canadian:
401
402``cross-canadian.bbclass``
403==========================
404
405The ``cross-canadian`` class provides support for the recipes that build
406the Canadian Cross-compilation tools for SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600407":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500408section in the Yocto Project Overview and Concepts Manual for more
409discussion on these cross-compilation tools.
410
411.. _ref-classes-crosssdk:
412
413``crosssdk.bbclass``
414====================
415
416The ``crosssdk`` class provides support for the recipes that build the
417cross-compilation tools used for building SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600418":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500419section in the Yocto Project Overview and Concepts Manual for more
420discussion on these cross-compilation tools.
421
422.. _ref-classes-debian:
423
424``debian.bbclass``
425==================
426
427The ``debian`` class renames output packages so that they follow the
428Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and
429``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library
430name and version as part of the package name.
431
432If a recipe creates packages for multiple libraries (shared object files
433of ``.so`` type), use the :term:`LEAD_SONAME`
434variable in the recipe to specify the library on which to apply the
435naming scheme.
436
437.. _ref-classes-deploy:
438
439``deploy.bbclass``
440==================
441
442The ``deploy`` class handles deploying files to the
443:term:`DEPLOY_DIR_IMAGE` directory. The main
444function of this class is to allow the deploy step to be accelerated by
445shared state. Recipes that inherit this class should define their own
446:ref:`ref-tasks-deploy` function to copy the files to be
447deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
448add the task at the appropriate place, which is usually after
449:ref:`ref-tasks-compile` or
450:ref:`ref-tasks-install`. The class then takes care of
451staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``.
452
453.. _ref-classes-devshell:
454
455``devshell.bbclass``
456====================
457
458The ``devshell`` class adds the ``do_devshell`` task. Distribution
Andrew Geissler09209ee2020-12-13 08:44:15 -0600459policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500460section in the Yocto Project Development Tasks Manual for more
461information about using ``devshell``.
462
463.. _ref-classes-devupstream:
464
465``devupstream.bbclass``
466=======================
467
468The ``devupstream`` class uses
469:term:`BBCLASSEXTEND` to add a variant of the
470recipe that fetches from an alternative URI (e.g. Git) instead of a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500471tarball. Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500472
473 BBCLASSEXTEND = "devupstream:target"
474 SRC_URI_class-devupstream = "git://git.example.com/example"
475 SRCREV_class-devupstream = "abcd1234"
476
477Adding the above statements to your recipe creates a variant that has
478:term:`DEFAULT_PREFERENCE` set to "-1".
479Consequently, you need to select the variant of the recipe to use it.
480Any development-specific adjustments can be done by using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500481``class-devupstream`` override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500482
483 DEPENDS_append_class-devupstream = " gperf-native"
484 do_configure_prepend_class-devupstream() {
485 touch ${S}/README
486 }
487
488The class
489currently only supports creating a development variant of the target
490recipe, not ``native`` or ``nativesdk`` variants.
491
492The ``BBCLASSEXTEND`` syntax (i.e. ``devupstream:target``) provides
493support for ``native`` and ``nativesdk`` variants. Consequently, this
494functionality can be added in a future release.
495
496Support for other version control systems such as Subversion is limited
497due to BitBake's automatic fetch dependencies (e.g.
498``subversion-native``).
499
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500500.. _ref-classes-distutils3:
501
502``distutils3*.bbclass``
503=======================
504
505The ``distutils3*`` classes support recipes for Python version 3.x
506extensions, which are simple. These recipes usually only need to point
507to the source's archive and then inherit the proper class. Building is
508split into three methods depending on which method the module authors
509used.
510
511- Extensions that use an Autotools-based build system require Autotools
512 and ``distutils``-based classes in their recipes.
513
514- Extensions that use ``distutils``-based build systems require the
515 ``distutils`` class in their recipes.
516
517- Extensions that use build systems based on ``setuptools3`` require
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500518 the :ref:`setuptools3 <ref-classes-setuptools3>` class in their
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500519 recipes.
520
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500521.. _ref-classes-externalsrc:
522
523``externalsrc.bbclass``
524=======================
525
526The ``externalsrc`` class supports building software from source code
527that is external to the OpenEmbedded build system. Building software
528from an external source tree means that the build system's normal fetch,
529unpack, and patch process is not used.
530
531By default, the OpenEmbedded build system uses the :term:`S`
532and :term:`B` variables to locate unpacked recipe source code
533and to build it, respectively. When your recipe inherits the
534``externalsrc`` class, you use the
535:term:`EXTERNALSRC` and
536:term:`EXTERNALSRC_BUILD` variables to
537ultimately define ``S`` and ``B``.
538
539By default, this class expects the source code to support recipe builds
540that use the :term:`B` variable to point to the directory in
541which the OpenEmbedded build system places the generated objects built
542from the recipes. By default, the ``B`` directory is set to the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500543following, which is separate from the source directory (``S``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500544
545 ${WORKDIR}/${BPN}/{PV}/
546
547See these variables for more information:
548:term:`WORKDIR`, :term:`BPN`, and
549:term:`PV`,
550
551For more information on the ``externalsrc`` class, see the comments in
552``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
553For information on how to use the
554``externalsrc`` class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600555":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500556section in the Yocto Project Development Tasks Manual.
557
558.. _ref-classes-extrausers:
559
560``extrausers.bbclass``
561======================
562
563The ``extrausers`` class allows additional user and group configuration
564to be applied at the image level. Inheriting this class either globally
565or from an image recipe allows additional user and group operations to
566be performed using the
567:term:`EXTRA_USERS_PARAMS` variable.
568
569.. note::
570
571 The user and group operations added using the
572 extrausers
573 class are not tied to a specific recipe outside of the recipe for the
574 image. Thus, the operations can be performed across the image as a
575 whole. Use the
576 useradd
577 class to add user and group configuration to a specific recipe.
578
Andrew Geisslerc926e172021-05-07 16:11:35 -0500579Here is an example that uses this class in an image recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500580
581 inherit extrausers
582 EXTRA_USERS_PARAMS = "\
583 useradd -p '' tester; \
584 groupadd developers; \
585 userdel nobody; \
586 groupdel -g video; \
587 groupmod -g 1020 developers; \
588 usermod -s /bin/sh tester; \
589 "
590
591Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
Andrew Geisslerc926e172021-05-07 16:11:35 -0500592passwords::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500593
594 inherit extrausers
595 EXTRA_USERS_PARAMS = "\
596 useradd -P tester01 tester-jim; \
597 useradd -P tester01 tester-sue; \
598 "
599
Andrew Geisslerc926e172021-05-07 16:11:35 -0500600Finally, here is an example that sets the root password to "1876*18"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500601
602 inherit extrausers
603 EXTRA_USERS_PARAMS = "\
604 usermod -P 1876*18 root; \
605 "
606
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600607.. _ref-classes-features_check:
608
609``features_check.bbclass``
610=================================
611
612The ``features_check`` class allows individual recipes to check
613for required and conflicting
614:term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`.
615
616This class provides support for the following variables:
617
618- :term:`REQUIRED_DISTRO_FEATURES`
619- :term:`CONFLICT_DISTRO_FEATURES`
620- :term:`ANY_OF_DISTRO_FEATURES`
621- ``REQUIRED_MACHINE_FEATURES``
622- ``CONFLICT_MACHINE_FEATURES``
623- ``ANY_OF_MACHINE_FEATURES``
624- ``REQUIRED_COMBINED_FEATURES``
625- ``CONFLICT_COMBINED_FEATURES``
626- ``ANY_OF_COMBINED_FEATURES``
627
628If any conditions specified in the recipe using the above
629variables are not met, the recipe will be skipped, and if the
630build system attempts to build the recipe then an error will be
631triggered.
632
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500633.. _ref-classes-fontcache:
634
635``fontcache.bbclass``
636=====================
637
638The ``fontcache`` class generates the proper post-install and
639post-remove (postinst and postrm) scriptlets for font packages. These
640scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts
641to the font information cache. Since the cache files are
642architecture-specific, ``fc-cache`` runs using QEMU if the postinst
643scriptlets need to be run on the build host during image creation.
644
645If the fonts being installed are in packages other than the main
646package, set :term:`FONT_PACKAGES` to specify the
647packages containing the fonts.
648
649.. _ref-classes-fs-uuid:
650
651``fs-uuid.bbclass``
652===================
653
654The ``fs-uuid`` class extracts UUID from
655``${``\ :term:`ROOTFS`\ ``}``, which must have been built
656by the time that this function gets called. The ``fs-uuid`` class only
657works on ``ext`` file systems and depends on ``tune2fs``.
658
659.. _ref-classes-gconf:
660
661``gconf.bbclass``
662=================
663
664The ``gconf`` class provides common functionality for recipes that need
665to install GConf schemas. The schemas will be put into a separate
666package (``${``\ :term:`PN`\ ``}-gconf``) that is created
667automatically when this class is inherited. This package uses the
668appropriate post-install and post-remove (postinst/postrm) scriptlets to
669register and unregister the schemas in the target image.
670
671.. _ref-classes-gettext:
672
673``gettext.bbclass``
674===================
675
676The ``gettext`` class provides support for building software that uses
677the GNU ``gettext`` internationalization and localization system. All
678recipes building software that use ``gettext`` should inherit this
679class.
680
681.. _ref-classes-gnomebase:
682
683``gnomebase.bbclass``
684=====================
685
686The ``gnomebase`` class is the base class for recipes that build
687software from the GNOME stack. This class sets
688:term:`SRC_URI` to download the source from the GNOME
689mirrors as well as extending :term:`FILES` with the typical
690GNOME installation paths.
691
692.. _ref-classes-gobject-introspection:
693
694``gobject-introspection.bbclass``
695=================================
696
697Provides support for recipes building software that supports GObject
698introspection. This functionality is only enabled if the
699"gobject-introspection-data" feature is in
700:term:`DISTRO_FEATURES` as well as
701"qemu-usermode" being in
702:term:`MACHINE_FEATURES`.
703
704.. note::
705
706 This functionality is backfilled by default and, if not applicable,
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500707 should be disabled through ``DISTRO_FEATURES_BACKFILL_CONSIDERED`` or
708 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``, respectively.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500709
710.. _ref-classes-grub-efi:
711
712``grub-efi.bbclass``
713====================
714
715The ``grub-efi`` class provides ``grub-efi``-specific functions for
716building bootable images.
717
718This class supports several variables:
719
720- :term:`INITRD`: Indicates list of filesystem images to
721 concatenate and use as an initial RAM disk (initrd) (optional).
722
723- :term:`ROOTFS`: Indicates a filesystem image to include
724 as the root filesystem (optional).
725
726- :term:`GRUB_GFXSERIAL`: Set this to "1" to have
727 graphics and serial in the boot menu.
728
729- :term:`LABELS`: A list of targets for the automatic
730 configuration.
731
732- :term:`APPEND`: An override list of append strings for
733 each ``LABEL``.
734
735- :term:`GRUB_OPTS`: Additional options to add to the
736 configuration (optional). Options are delimited using semi-colon
737 characters (``;``).
738
739- :term:`GRUB_TIMEOUT`: Timeout before executing
740 the default ``LABEL`` (optional).
741
742.. _ref-classes-gsettings:
743
744``gsettings.bbclass``
745=====================
746
747The ``gsettings`` class provides common functionality for recipes that
748need to install GSettings (glib) schemas. The schemas are assumed to be
749part of the main package. Appropriate post-install and post-remove
750(postinst/postrm) scriptlets are added to register and unregister the
751schemas in the target image.
752
753.. _ref-classes-gtk-doc:
754
755``gtk-doc.bbclass``
756===================
757
758The ``gtk-doc`` class is a helper class to pull in the appropriate
759``gtk-doc`` dependencies and disable ``gtk-doc``.
760
761.. _ref-classes-gtk-icon-cache:
762
763``gtk-icon-cache.bbclass``
764==========================
765
766The ``gtk-icon-cache`` class generates the proper post-install and
767post-remove (postinst/postrm) scriptlets for packages that use GTK+ and
768install icons. These scriptlets call ``gtk-update-icon-cache`` to add
769the fonts to GTK+'s icon cache. Since the cache files are
770architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if
771the postinst scriptlets need to be run on the build host during image
772creation.
773
774.. _ref-classes-gtk-immodules-cache:
775
776``gtk-immodules-cache.bbclass``
777===============================
778
779The ``gtk-immodules-cache`` class generates the proper post-install and
780post-remove (postinst/postrm) scriptlets for packages that install GTK+
781input method modules for virtual keyboards. These scriptlets call
782``gtk-update-icon-cache`` to add the input method modules to the cache.
783Since the cache files are architecture-specific,
784``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets
785need to be run on the build host during image creation.
786
787If the input method modules being installed are in packages other than
788the main package, set
789:term:`GTKIMMODULES_PACKAGES` to specify
790the packages containing the modules.
791
792.. _ref-classes-gzipnative:
793
794``gzipnative.bbclass``
795======================
796
797The ``gzipnative`` class enables the use of different native versions of
798``gzip`` and ``pigz`` rather than the versions of these tools from the
799build host.
800
801.. _ref-classes-icecc:
802
803``icecc.bbclass``
804=================
805
806The ``icecc`` class supports
807`Icecream <https://github.com/icecc/icecream>`__, which facilitates
808taking compile jobs and distributing them among remote machines.
809
810The class stages directories with symlinks from ``gcc`` and ``g++`` to
811``icecc``, for both native and cross compilers. Depending on each
812configure or compile, the OpenEmbedded build system adds the directories
813at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and
814``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc``
815compilers, respectively.
816
817For the cross compiler, the class creates a ``tar.gz`` file that
818contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which
819is the version of the cross-compiler used in the cross-development
820toolchain, accordingly.
821
822The class handles all three different compile stages (i.e native
823,cross-kernel and target) and creates the necessary environment
824``tar.gz`` file to be used by the remote machines. The class also
825supports SDK generation.
826
827If :term:`ICECC_PATH` is not set in your
828``local.conf`` file, then the class tries to locate the ``icecc`` binary
829using ``which``. If :term:`ICECC_ENV_EXEC` is set
830in your ``local.conf`` file, the variable should point to the
831``icecc-create-env`` script provided by the user. If you do not point to
832a user-provided script, the build system uses the default script
833provided by the recipe ``icecc-create-env-native.bb``.
834
835.. note::
836
837 This script is a modified version and not the one that comes with
838 icecc.
839
840If you do not want the Icecream distributed compile support to apply to
841specific recipes or classes, you can effectively "blacklist" them by
842listing the recipes and classes using the
843:term:`ICECC_USER_PACKAGE_BL` and
844:term:`ICECC_USER_CLASS_BL`, variables,
845respectively, in your ``local.conf`` file. Doing so causes the
846OpenEmbedded build system to handle these compilations locally.
847
848Additionally, you can list recipes using the
849:term:`ICECC_USER_PACKAGE_WL` variable in
850your ``local.conf`` file to force ``icecc`` to be enabled for recipes
851using an empty :term:`PARALLEL_MAKE` variable.
852
853Inheriting the ``icecc`` class changes all sstate signatures.
854Consequently, if a development team has a dedicated build system that
855populates :term:`SSTATE_MIRRORS` and they want to
856reuse sstate from ``SSTATE_MIRRORS``, then all developers and the build
857system need to either inherit the ``icecc`` class or nobody should.
858
859At the distribution level, you can inherit the ``icecc`` class to be
860sure that all builders start with the same sstate signatures. After
861inheriting the class, you can then disable the feature by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500862:term:`ICECC_DISABLED` variable to "1" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500863
864 INHERIT_DISTRO_append = " icecc"
865 ICECC_DISABLED ??= "1"
866
867This practice
868makes sure everyone is using the same signatures but also requires
869individuals that do want to use Icecream to enable the feature
Andrew Geisslerc926e172021-05-07 16:11:35 -0500870individually as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500871
872 ICECC_DISABLED = ""
873
874.. _ref-classes-image:
875
876``image.bbclass``
877=================
878
879The ``image`` class helps support creating images in different formats.
880First, the root filesystem is created from packages using one of the
881``rootfs*.bbclass`` files (depending on the package format used) and
882then one or more image files are created.
883
884- The ``IMAGE_FSTYPES`` variable controls the types of images to
885 generate.
886
887- The ``IMAGE_INSTALL`` variable controls the list of packages to
888 install into the image.
889
890For information on customizing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600891":ref:`dev-manual/common-tasks:customizing images`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500892in the Yocto Project Development Tasks Manual. For information on how
893images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600894":ref:`overview-manual/concepts:images`" section in the
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600895Yocto Project Overview and Concepts Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500896
897.. _ref-classes-image-buildinfo:
898
899``image-buildinfo.bbclass``
900===========================
901
902The ``image-buildinfo`` class writes information to the target
903filesystem on ``/etc/build``.
904
905.. _ref-classes-image_types:
906
907``image_types.bbclass``
908=======================
909
910The ``image_types`` class defines all of the standard image output types
911that you can enable through the
912:term:`IMAGE_FSTYPES` variable. You can use this
913class as a reference on how to add support for custom image output
914types.
915
916By default, the :ref:`image <ref-classes-image>` class automatically
917enables the ``image_types`` class. The ``image`` class uses the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500918``IMGCLASSES`` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500919
920 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
921 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
922 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
923 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
924 IMGCLASSES += "image_types_wic"
925 IMGCLASSES += "rootfs-postcommands"
926 IMGCLASSES += "image-postinst-intercepts"
927 inherit ${IMGCLASSES}
928
929The ``image_types`` class also handles conversion and compression of images.
930
931.. note::
932
933 To build a VMware VMDK image, you need to add "wic.vmdk" to
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500934 ``IMAGE_FSTYPES``. This would also be similar for Virtual Box Virtual Disk
935 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500936
937.. _ref-classes-image-live:
938
939``image-live.bbclass``
940======================
941
942This class controls building "live" (i.e. HDDIMG and ISO) images. Live
943images contain syslinux for legacy booting, as well as the bootloader
944specified by :term:`EFI_PROVIDER` if
945:term:`MACHINE_FEATURES` contains "efi".
946
947Normally, you do not use this class directly. Instead, you add "live" to
948:term:`IMAGE_FSTYPES`.
949
950.. _ref-classes-image-mklibs:
951
952``image-mklibs.bbclass``
953========================
954
955The ``image-mklibs`` class enables the use of the ``mklibs`` utility
956during the :ref:`ref-tasks-rootfs` task, which optimizes
957the size of libraries contained in the image.
958
959By default, the class is enabled in the ``local.conf.template`` using
Andrew Geisslerc926e172021-05-07 16:11:35 -0500960the :term:`USER_CLASSES` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500961
962 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
963
964.. _ref-classes-image-prelink:
965
966``image-prelink.bbclass``
967=========================
968
969The ``image-prelink`` class enables the use of the ``prelink`` utility
970during the :ref:`ref-tasks-rootfs` task, which optimizes
971the dynamic linking of shared libraries to reduce executable startup
972time.
973
974By default, the class is enabled in the ``local.conf.template`` using
Andrew Geisslerc926e172021-05-07 16:11:35 -0500975the :term:`USER_CLASSES` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500976
977 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
978
979.. _ref-classes-insane:
980
981``insane.bbclass``
982==================
983
984The ``insane`` class adds a step to the package generation process so
985that output quality assurance checks are generated by the OpenEmbedded
986build system. A range of checks are performed that check the build's
987output for common problems that show up during runtime. Distribution
988policy usually dictates whether to include this class.
989
990You can configure the sanity checks so that specific test failures
991either raise a warning or an error message. Typically, failures for new
992tests generate a warning. Subsequent failures for the same test would
993then generate an error message once the metadata is in a known and good
Andrew Geissler09209ee2020-12-13 08:44:15 -0600994condition. See the ":doc:`/ref-manual/qa-checks`" Chapter for a list of all the warning
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500995and error messages you might encounter using a default configuration.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500996
997Use the :term:`WARN_QA` and
998:term:`ERROR_QA` variables to control the behavior of
999these checks at the global level (i.e. in your custom distro
1000configuration). However, to skip one or more checks in recipes, you
1001should use :term:`INSANE_SKIP`. For example, to skip
1002the check for symbolic link ``.so`` files in the main package of a
1003recipe, add the following to the recipe. You need to realize that the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001004package name override, in this example ``${PN}``, must be used::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001005
1006 INSANE_SKIP_${PN} += "dev-so"
1007
1008Please keep in mind that the QA checks
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001009are meant to detect real or potential problems in the packaged
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001010output. So exercise caution when disabling these checks.
1011
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001012Here are the tests you can list with the ``WARN_QA`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001013``ERROR_QA`` variables:
1014
1015- ``already-stripped:`` Checks that produced binaries have not
1016 already been stripped prior to the build system extracting debug
1017 symbols. It is common for upstream software projects to default to
1018 stripping debug symbols for output binaries. In order for debugging
1019 to work on the target using ``-dbg`` packages, this stripping must be
1020 disabled.
1021
1022- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit
1023 size, and endianness of any binaries to ensure they match the target
1024 architecture. This test fails if any binaries do not match the type
1025 since there would be an incompatibility. The test could indicate that
1026 the wrong compiler or compiler options have been used. Sometimes
1027 software, like bootloaders, might need to bypass this check.
1028
1029- ``buildpaths:`` Checks for paths to locations on the build host
1030 inside the output files. Currently, this test triggers too many false
1031 positives and thus is not normally enabled.
1032
1033- ``build-deps:`` Determines if a build-time dependency that is
1034 specified through :term:`DEPENDS`, explicit
1035 :term:`RDEPENDS`, or task-level dependencies exists
1036 to match any runtime dependency. This determination is particularly
1037 useful to discover where runtime dependencies are detected and added
1038 during packaging. If no explicit dependency has been specified within
1039 the metadata, at the packaging stage it is too late to ensure that
1040 the dependency is built, and thus you can end up with an error when
1041 the package is installed into the image during the
1042 :ref:`ref-tasks-rootfs` task because the auto-detected
1043 dependency was not satisfied. An example of this would be where the
1044 :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically
1045 adds a dependency on the ``initscripts-functions`` package to
1046 packages that install an initscript that refers to
1047 ``/etc/init.d/functions``. The recipe should really have an explicit
1048 ``RDEPENDS`` for the package in question on ``initscripts-functions``
1049 so that the OpenEmbedded build system is able to ensure that the
1050 ``initscripts`` recipe is actually built and thus the
1051 ``initscripts-functions`` package is made available.
1052
1053- ``compile-host-path:`` Checks the
1054 :ref:`ref-tasks-compile` log for indications that
1055 paths to locations on the build host were used. Using such paths
1056 might result in host contamination of the build output.
1057
1058- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
1059 do not depend on ``-dbg`` packages, which would cause a packaging
1060 bug.
1061
1062- ``debug-files:`` Checks for ``.debug`` directories in anything but
1063 the ``-dbg`` package. The debug files should all be in the ``-dbg``
1064 package. Thus, anything packaged elsewhere is incorrect packaging.
1065
1066- ``dep-cmp:`` Checks for invalid version comparison statements in
1067 runtime dependency relationships between packages (i.e. in
1068 :term:`RDEPENDS`,
1069 :term:`RRECOMMENDS`,
1070 :term:`RSUGGESTS`,
1071 :term:`RPROVIDES`,
1072 :term:`RREPLACES`, and
1073 :term:`RCONFLICTS` variable values). Any invalid
1074 comparisons might trigger failures or undesirable behavior when
1075 passed to the package manager.
1076
1077- ``desktop:`` Runs the ``desktop-file-validate`` program against any
1078 ``.desktop`` files to validate their contents against the
1079 specification for ``.desktop`` files.
1080
1081- ``dev-deps:`` Checks that all packages except ``-dev`` or
1082 ``-staticdev`` packages do not depend on ``-dev`` packages, which
1083 would be a packaging bug.
1084
1085- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
1086 ``-dev`` package and not in any of the other packages. In general,
1087 these symlinks are only useful for development purposes. Thus, the
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001088 ``-dev`` package is the correct location for them. In very rare
1089 cases, such as dynamically loaded modules, these symlinks
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001090 are needed instead in the main package.
1091
1092- ``file-rdeps:`` Checks that file-level dependencies identified by
1093 the OpenEmbedded build system at packaging time are satisfied. For
1094 example, a shell script might start with the line ``#!/bin/bash``.
1095 This line would translate to a file dependency on ``/bin/bash``. Of
1096 the three package managers that the OpenEmbedded build system
1097 supports, only RPM directly handles file-level dependencies,
1098 resolving them automatically to packages providing the files.
1099 However, the lack of that functionality in the other two package
1100 managers does not mean the dependencies do not still need resolving.
1101 This QA check attempts to ensure that explicitly declared
1102 :term:`RDEPENDS` exist to handle any file-level
1103 dependency detected in packaged files.
1104
1105- ``files-invalid:`` Checks for :term:`FILES` variable
1106 values that contain "//", which is invalid.
1107
1108- ``host-user-contaminated:`` Checks that no package produced by the
1109 recipe contains any files outside of ``/home`` with a user or group
1110 ID that matches the user running BitBake. A match usually indicates
1111 that the files are being installed with an incorrect UID/GID, since
1112 target IDs are independent from host IDs. For additional information,
1113 see the section describing the
1114 :ref:`ref-tasks-install` task.
1115
1116- ``incompatible-license:`` Report when packages are excluded from
1117 being created due to being marked with a license that is in
1118 :term:`INCOMPATIBLE_LICENSE`.
1119
1120- ``install-host-path:`` Checks the
1121 :ref:`ref-tasks-install` log for indications that
1122 paths to locations on the build host were used. Using such paths
1123 might result in host contamination of the build output.
1124
1125- ``installed-vs-shipped:`` Reports when files have been installed
1126 within ``do_install`` but have not been included in any package by
1127 way of the :term:`FILES` variable. Files that do not
1128 appear in any package cannot be present in an image later on in the
1129 build process. Ideally, all installed files should be packaged or not
1130 installed at all. These files can be deleted at the end of
1131 ``do_install`` if the files are not needed in any package.
1132
1133- ``invalid-chars:`` Checks that the recipe metadata variables
1134 :term:`DESCRIPTION`,
1135 :term:`SUMMARY`, :term:`LICENSE`, and
1136 :term:`SECTION` do not contain non-UTF-8 characters.
1137 Some package managers do not support such characters.
1138
1139- ``invalid-packageconfig:`` Checks that no undefined features are
1140 being added to :term:`PACKAGECONFIG`. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05001141 example, any name "foo" for which the following form does not exist::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001142
1143 PACKAGECONFIG[foo] = "..."
1144
1145- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la``
1146 file containing these paths is incorrect since ``libtool`` adds the
1147 correct sysroot prefix when using the files automatically itself.
1148
1149- ``ldflags:`` Ensures that the binaries were linked with the
1150 :term:`LDFLAGS` options provided by the build system.
1151 If this test fails, check that the ``LDFLAGS`` variable is being
1152 passed to the linker command.
1153
1154- ``libdir:`` Checks for libraries being installed into incorrect
1155 (possibly hardcoded) installation paths. For example, this test will
1156 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
1157 "lib32". Another example is when recipes install
1158 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
1159
1160- ``libexec:`` Checks if a package contains files in
1161 ``/usr/libexec``. This check is not performed if the ``libexecdir``
1162 variable has been set explicitly to ``/usr/libexec``.
1163
1164- ``packages-list:`` Checks for the same package being listed
1165 multiple times through the :term:`PACKAGES` variable
1166 value. Installing the package in this manner can cause errors during
1167 packaging.
1168
1169- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
1170 invalid format.
1171
1172- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
1173 invalid format.
1174
1175- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
1176 'link' where the specified target already exists.
1177
1178- ``perms:`` Currently, this check is unused but reserved.
1179
1180- ``pkgconfig:`` Checks ``.pc`` files for any
1181 :term:`TMPDIR`/:term:`WORKDIR` paths.
1182 Any ``.pc`` file containing these paths is incorrect since
1183 ``pkg-config`` itself adds the correct sysroot prefix when the files
1184 are accessed.
1185
1186- ``pkgname:`` Checks that all packages in
1187 :term:`PACKAGES` have names that do not contain
1188 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1189 -).
1190
1191- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is
1192 undefined during :ref:`ref-tasks-package`.
1193
1194- ``pkgvarcheck:`` Checks through the variables
1195 :term:`RDEPENDS`,
1196 :term:`RRECOMMENDS`,
1197 :term:`RSUGGESTS`,
1198 :term:`RCONFLICTS`,
1199 :term:`RPROVIDES`,
1200 :term:`RREPLACES`, :term:`FILES`,
1201 :term:`ALLOW_EMPTY`, ``pkg_preinst``,
1202 ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if
1203 there are variable sets that are not package-specific. Using these
1204 variables without a package suffix is bad practice, and might
1205 unnecessarily complicate dependencies of other packages within the
1206 same recipe or have other unintended consequences.
1207
1208- ``pn-overrides:`` Checks that a recipe does not have a name
1209 (:term:`PN`) value that appears in
1210 :term:`OVERRIDES`. If a recipe is named such that
1211 its ``PN`` value matches something already in ``OVERRIDES`` (e.g.
1212 ``PN`` happens to be the same as :term:`MACHINE` or
1213 :term:`DISTRO`), it can have unexpected consequences.
1214 For example, assignments such as ``FILES_${PN} = "xyz"`` effectively
1215 turn into ``FILES = "xyz"``.
1216
1217- ``rpaths:`` Checks for rpaths in the binaries that contain build
1218 system paths such as ``TMPDIR``. If this test fails, bad ``-rpath``
1219 options are being passed to the linker commands and your binaries
1220 have potential security issues.
1221
1222- ``split-strip:`` Reports that splitting or stripping debug symbols
1223 from binaries has failed.
1224
1225- ``staticdev:`` Checks for static library files (``*.a``) in
1226 non-``staticdev`` packages.
1227
1228- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
1229 into :term:`TMPDIR` on the host. Such symlinks will
1230 work on the host, but are clearly invalid when running on the target.
1231
1232- ``textrel:`` Checks for ELF binaries that contain relocations in
1233 their ``.text`` sections, which can result in a performance impact at
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001234 runtime. See the explanation for the ``ELF binary`` message in
Andrew Geissler09209ee2020-12-13 08:44:15 -06001235 ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001236 issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001237
1238- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
1239 for a package are also declared on the recipe level (i.e. any license
1240 in ``LICENSE_*`` should appear in :term:`LICENSE`).
1241
1242- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
1243 in the binaries that by default on a standard system are searched by
1244 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
1245 not cause any breakage, they do waste space and are unnecessary.
1246
1247- ``var-undefined:`` Reports when variables fundamental to packaging
1248 (i.e. :term:`WORKDIR`,
1249 :term:`DEPLOY_DIR`, :term:`D`,
1250 :term:`PN`, and :term:`PKGD`) are undefined
1251 during :ref:`ref-tasks-package`.
1252
1253- ``version-going-backwards:`` If Build History is enabled, reports
1254 when a package being written out has a lower version than the
1255 previously written package under the same name. If you are placing
1256 output packages into a feed and upgrading packages on a target system
1257 using that feed, the version of a package going backwards can result
1258 in the target system not correctly upgrading to the "new" version of
1259 the package.
1260
1261 .. note::
1262
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001263 This is only relevant when you are using runtime package management
1264 on your target system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001265
1266- ``xorg-driver-abi:`` Checks that all packages containing Xorg
1267 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
1268 driver ABI names. All drivers should depend on the ABI versions that
1269 they have been built against. Driver recipes that include
1270 ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
1271 automatically get these versions. Consequently, you should only need
1272 to explicitly add dependencies to binary driver recipes.
1273
1274.. _ref-classes-insserv:
1275
1276``insserv.bbclass``
1277===================
1278
1279The ``insserv`` class uses the ``insserv`` utility to update the order
1280of symbolic links in ``/etc/rc?.d/`` within an image based on
1281dependencies specified by LSB headers in the ``init.d`` scripts
1282themselves.
1283
1284.. _ref-classes-kernel:
1285
1286``kernel.bbclass``
1287==================
1288
1289The ``kernel`` class handles building Linux kernels. The class contains
1290code to build all kernel trees. All needed headers are staged into the
1291``STAGING_KERNEL_DIR`` directory to allow out-of-tree module builds
1292using the :ref:`module <ref-classes-module>` class.
1293
1294This means that each built kernel module is packaged separately and
1295inter-module dependencies are created by parsing the ``modinfo`` output.
1296If all modules are required, then installing the ``kernel-modules``
1297package installs all packages with modules and various other kernel
1298packages such as ``kernel-vmlinux``.
1299
1300The ``kernel`` class contains logic that allows you to embed an initial
1301RAM filesystem (initramfs) image when you build the kernel image. For
1302information on how to build an initramfs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001303":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001304the Yocto Project Development Tasks Manual.
1305
1306Various other classes are used by the ``kernel`` and ``module`` classes
1307internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`,
1308:ref:`module-base <ref-classes-module-base>`, and
1309:ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes.
1310
1311.. _ref-classes-kernel-arch:
1312
1313``kernel-arch.bbclass``
1314=======================
1315
1316The ``kernel-arch`` class sets the ``ARCH`` environment variable for
1317Linux kernel compilation (including modules).
1318
1319.. _ref-classes-kernel-devicetree:
1320
1321``kernel-devicetree.bbclass``
1322=============================
1323
1324The ``kernel-devicetree`` class, which is inherited by the
1325:ref:`kernel <ref-classes-kernel>` class, supports device tree
1326generation.
1327
1328.. _ref-classes-kernel-fitimage:
1329
1330``kernel-fitimage.bbclass``
1331===========================
1332
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001333The ``kernel-fitimage`` class provides support to pack a kernel image,
1334device trees, a U-boot script, a Initramfs bundle and a RAM disk
1335into a single FIT image. In theory, a FIT image can support any number
1336of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001337However, ``kernel-fitimage`` currently only supports
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001338limited usescases: just one kernel image, an optional U-boot script,
1339an optional Initramfs bundle, an optional RAM disk, and any number of
1340device tree.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001341
1342To create a FIT image, it is required that :term:`KERNEL_CLASSES`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001343is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001344is set to "fitImage".
1345
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001346The options for the device tree compiler passed to ``mkimage -D``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001347when creating the FIT image are specified using the
1348:term:`UBOOT_MKIMAGE_DTCOPTS` variable.
1349
1350Only a single kernel can be added to the FIT image created by
1351``kernel-fitimage`` and the kernel image in FIT is mandatory. The
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001352address where the kernel image is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001353specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by
1354:term:`UBOOT_ENTRYPOINT`.
1355
1356Multiple device trees can be added to the FIT image created by
1357``kernel-fitimage`` and the device tree is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001358The address where the device tree is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001359specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001360and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001361
1362Only a single RAM disk can be added to the FIT image created by
1363``kernel-fitimage`` and the RAM disk in FIT is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001364The address where the RAM disk image is to be loaded by U-Boot
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001365is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
1366:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001367:term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE`
1368is set to 0.
1369
1370Only a single Initramfs bundle can be added to the FIT image created by
1371``kernel-fitimage`` and the Initramfs bundle in FIT is optional.
1372In case of Initramfs, the kernel is configured to be bundled with the rootfs
1373in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin).
1374When the kernel is copied to RAM and executed, it unpacks the Initramfs rootfs.
1375The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE`
1376is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1.
1377The address where the Initramfs bundle is to be loaded by U-boot is specified
1378by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`.
1379
1380Only a single U-boot boot script can be added to the FIT image created by
1381``kernel-fitimage`` and the boot script is optional.
1382The boot script is specified in the ITS file as a text file containing
1383U-boot commands. When using a boot script the user should configure the
1384U-boot ``do_install`` task to copy the script to sysroot.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001385So the script can be included in the FIT image by the ``kernel-fitimage``
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001386class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
1387load the boot script from the FIT image and executes it.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001388
1389The FIT image generated by ``kernel-fitimage`` class is signed when the
1390variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
1391:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
1392appropriately. The default values used for :term:`FIT_HASH_ALG` and
1393:term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05001394"rsa2048" respectively. The keys for signing fitImage can be generated using
1395the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and
1396:term:`UBOOT_SIGN_ENABLE` are set to "1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001397
1398
1399.. _ref-classes-kernel-grub:
1400
1401``kernel-grub.bbclass``
1402=======================
1403
1404The ``kernel-grub`` class updates the boot area and the boot menu with
1405the kernel as the priority boot mechanism while installing a RPM to
1406update the kernel on a deployed target.
1407
1408.. _ref-classes-kernel-module-split:
1409
1410``kernel-module-split.bbclass``
1411===============================
1412
1413The ``kernel-module-split`` class provides common functionality for
1414splitting Linux kernel modules into separate packages.
1415
1416.. _ref-classes-kernel-uboot:
1417
1418``kernel-uboot.bbclass``
1419========================
1420
1421The ``kernel-uboot`` class provides support for building from
1422vmlinux-style kernel sources.
1423
1424.. _ref-classes-kernel-uimage:
1425
1426``kernel-uimage.bbclass``
1427=========================
1428
1429The ``kernel-uimage`` class provides support to pack uImage.
1430
1431.. _ref-classes-kernel-yocto:
1432
1433``kernel-yocto.bbclass``
1434========================
1435
1436The ``kernel-yocto`` class provides common functionality for building
1437from linux-yocto style kernel source repositories.
1438
1439.. _ref-classes-kernelsrc:
1440
1441``kernelsrc.bbclass``
1442=====================
1443
1444The ``kernelsrc`` class sets the Linux kernel source and version.
1445
1446.. _ref-classes-lib_package:
1447
1448``lib_package.bbclass``
1449=======================
1450
1451The ``lib_package`` class supports recipes that build libraries and
1452produce executable binaries, where those binaries should not be
1453installed by default along with the library. Instead, the binaries are
1454added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to
1455make their installation optional.
1456
1457.. _ref-classes-libc*:
1458
1459``libc*.bbclass``
1460=================
1461
1462The ``libc*`` classes support recipes that build packages with ``libc``:
1463
1464- The ``libc-common`` class provides common support for building with
1465 ``libc``.
1466
1467- The ``libc-package`` class supports packaging up ``glibc`` and
1468 ``eglibc``.
1469
1470.. _ref-classes-license:
1471
1472``license.bbclass``
1473===================
1474
1475The ``license`` class provides license manifest creation and license
1476exclusion. This class is enabled by default using the default value for
1477the :term:`INHERIT_DISTRO` variable.
1478
1479.. _ref-classes-linux-kernel-base:
1480
1481``linux-kernel-base.bbclass``
1482=============================
1483
1484The ``linux-kernel-base`` class provides common functionality for
1485recipes that build out of the Linux kernel source tree. These builds
1486goes beyond the kernel itself. For example, the Perf recipe also
1487inherits this class.
1488
1489.. _ref-classes-linuxloader:
1490
1491``linuxloader.bbclass``
1492=======================
1493
1494Provides the function ``linuxloader()``, which gives the value of the
1495dynamic loader/linker provided on the platform. This value is used by a
1496number of other classes.
1497
1498.. _ref-classes-logging:
1499
1500``logging.bbclass``
1501===================
1502
1503The ``logging`` class provides the standard shell functions used to log
1504messages for various BitBake severity levels (i.e. ``bbplain``,
1505``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``).
1506
1507This class is enabled by default since it is inherited by the ``base``
1508class.
1509
1510.. _ref-classes-meta:
1511
1512``meta.bbclass``
1513================
1514
1515The ``meta`` class is inherited by recipes that do not build any output
1516packages themselves, but act as a "meta" target for building other
1517recipes.
1518
1519.. _ref-classes-metadata_scm:
1520
1521``metadata_scm.bbclass``
1522========================
1523
1524The ``metadata_scm`` class provides functionality for querying the
1525branch and revision of a Source Code Manager (SCM) repository.
1526
1527The :ref:`base <ref-classes-base>` class uses this class to print the
1528revisions of each layer before starting every build. The
1529``metadata_scm`` class is enabled by default because it is inherited by
1530the ``base`` class.
1531
1532.. _ref-classes-migrate_localcount:
1533
1534``migrate_localcount.bbclass``
1535==============================
1536
1537The ``migrate_localcount`` class verifies a recipe's localcount data and
1538increments it appropriately.
1539
1540.. _ref-classes-mime:
1541
1542``mime.bbclass``
1543================
1544
1545The ``mime`` class generates the proper post-install and post-remove
1546(postinst/postrm) scriptlets for packages that install MIME type files.
1547These scriptlets call ``update-mime-database`` to add the MIME types to
1548the shared database.
1549
1550.. _ref-classes-mirrors:
1551
1552``mirrors.bbclass``
1553===================
1554
1555The ``mirrors`` class sets up some standard
1556:term:`MIRRORS` entries for source code mirrors. These
1557mirrors provide a fall-back path in case the upstream source specified
1558in :term:`SRC_URI` within recipes is unavailable.
1559
1560This class is enabled by default since it is inherited by the
1561:ref:`base <ref-classes-base>` class.
1562
1563.. _ref-classes-module:
1564
1565``module.bbclass``
1566==================
1567
1568The ``module`` class provides support for building out-of-tree Linux
1569kernel modules. The class inherits the
1570:ref:`module-base <ref-classes-module-base>` and
1571:ref:`kernel-module-split <ref-classes-kernel-module-split>` classes,
1572and implements the :ref:`ref-tasks-compile` and
1573:ref:`ref-tasks-install` tasks. The class provides
1574everything needed to build and package a kernel module.
1575
1576For general information on out-of-tree Linux kernel modules, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001577":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001578section in the Yocto Project Linux Kernel Development Manual.
1579
1580.. _ref-classes-module-base:
1581
1582``module-base.bbclass``
1583=======================
1584
1585The ``module-base`` class provides the base functionality for building
1586Linux kernel modules. Typically, a recipe that builds software that
1587includes one or more kernel modules and has its own means of building
1588the module inherits this class as opposed to inheriting the
1589:ref:`module <ref-classes-module>` class.
1590
1591.. _ref-classes-multilib*:
1592
1593``multilib*.bbclass``
1594=====================
1595
1596The ``multilib*`` classes provide support for building libraries with
1597different target optimizations or target architectures and installing
1598them side-by-side in the same image.
1599
1600For more information on using the Multilib feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001601":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001602section in the Yocto Project Development Tasks Manual.
1603
1604.. _ref-classes-native:
1605
1606``native.bbclass``
1607==================
1608
1609The ``native`` class provides common functionality for recipes that
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001610build tools to run on the :term:`Build Host` (i.e. tools that use the compiler
1611or other tools from the build host).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001612
1613You can create a recipe that builds tools that run natively on the host
1614a couple different ways:
1615
1616- Create a myrecipe\ ``-native.bb`` recipe that inherits the ``native``
1617 class. If you use this method, you must order the inherit statement
1618 in the recipe after all other inherit statements so that the
1619 ``native`` class is inherited last.
1620
1621 .. note::
1622
1623 When creating a recipe this way, the recipe name must follow this
Andrew Geisslerc926e172021-05-07 16:11:35 -05001624 naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001625
1626 myrecipe-native.bb
1627
1628
1629 Not using this naming convention can lead to subtle problems
1630 caused by existing code that depends on that naming convention.
1631
Andrew Geisslerc926e172021-05-07 16:11:35 -05001632- Create or modify a target recipe that contains the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001633
1634 BBCLASSEXTEND = "native"
1635
1636 Inside the
1637 recipe, use ``_class-native`` and ``_class-target`` overrides to
1638 specify any functionality specific to the respective native or target
1639 case.
1640
1641Although applied differently, the ``native`` class is used with both
1642methods. The advantage of the second method is that you do not need to
1643have two separate recipes (assuming you need both) for native and
1644target. All common parts of the recipe are automatically shared.
1645
1646.. _ref-classes-nativesdk:
1647
1648``nativesdk.bbclass``
1649=====================
1650
1651The ``nativesdk`` class provides common functionality for recipes that
1652wish to build tools to run as part of an SDK (i.e. tools that run on
1653:term:`SDKMACHINE`).
1654
1655You can create a recipe that builds tools that run on the SDK machine a
1656couple different ways:
1657
1658- Create a ``nativesdk-``\ myrecipe\ ``.bb`` recipe that inherits the
1659 ``nativesdk`` class. If you use this method, you must order the
1660 inherit statement in the recipe after all other inherit statements so
1661 that the ``nativesdk`` class is inherited last.
1662
Andrew Geisslerc926e172021-05-07 16:11:35 -05001663- Create a ``nativesdk`` variant of any recipe by adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001664
1665 BBCLASSEXTEND = "nativesdk"
1666
1667 Inside the
1668 recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to
1669 specify any functionality specific to the respective SDK machine or
1670 target case.
1671
1672.. note::
1673
Andrew Geisslerc926e172021-05-07 16:11:35 -05001674 When creating a recipe, you must follow this naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001675
1676 nativesdk-myrecipe.bb
1677
1678
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001679 Not doing so can lead to subtle problems because there is code that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001680 depends on the naming convention.
1681
1682Although applied differently, the ``nativesdk`` class is used with both
1683methods. The advantage of the second method is that you do not need to
1684have two separate recipes (assuming you need both) for the SDK machine
1685and the target. All common parts of the recipe are automatically shared.
1686
1687.. _ref-classes-nopackages:
1688
1689``nopackages.bbclass``
1690======================
1691
1692Disables packaging tasks for those recipes and classes where packaging
1693is not needed.
1694
1695.. _ref-classes-npm:
1696
1697``npm.bbclass``
1698===============
1699
1700Provides support for building Node.js software fetched using the `node
1701package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
1702
1703.. note::
1704
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001705 Currently, recipes inheriting this class must use the ``npm://``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001706 fetcher to have dependencies fetched and packaged automatically.
1707
1708For information on how to create NPM packages, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001709":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001710section in the Yocto Project Development Tasks Manual.
1711
1712.. _ref-classes-oelint:
1713
1714``oelint.bbclass``
1715==================
1716
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001717The ``oelint`` class is an obsolete lint checking tool available in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001718``meta/classes`` in the :term:`Source Directory`.
1719
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001720There are some classes that could be generally useful in OE-Core but
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001721are never actually used within OE-Core itself. The ``oelint`` class is
1722one such example. However, being aware of this class can reduce the
1723proliferation of different versions of similar classes across multiple
1724layers.
1725
1726.. _ref-classes-own-mirrors:
1727
1728``own-mirrors.bbclass``
1729=======================
1730
1731The ``own-mirrors`` class makes it easier to set up your own
1732:term:`PREMIRRORS` from which to first fetch source
1733before attempting to fetch it from the upstream specified in
1734:term:`SRC_URI` within each recipe.
1735
1736To use this class, inherit it globally and specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05001737:term:`SOURCE_MIRROR_URL`. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001738
1739 INHERIT += "own-mirrors"
1740 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1741
1742You can specify only a single URL
1743in ``SOURCE_MIRROR_URL``.
1744
1745.. _ref-classes-package:
1746
1747``package.bbclass``
1748===================
1749
1750The ``package`` class supports generating packages from a build's
1751output. The core generic functionality is in ``package.bbclass``. The
1752code specific to particular package types resides in these
1753package-specific classes:
1754:ref:`package_deb <ref-classes-package_deb>`,
1755:ref:`package_rpm <ref-classes-package_rpm>`,
1756:ref:`package_ipk <ref-classes-package_ipk>`, and
1757:ref:`package_tar <ref-classes-package_tar>`.
1758
1759.. note::
1760
1761 The
1762 package_tar
1763 class is broken and not supported. It is recommended that you do not
1764 use this class.
1765
1766You can control the list of resulting package formats by using the
1767``PACKAGE_CLASSES`` variable defined in your ``conf/local.conf``
1768configuration file, which is located in the :term:`Build Directory`.
1769When defining the variable, you can
1770specify one or more package types. Since images are generated from
1771packages, a packaging class is needed to enable image generation. The
1772first class listed in this variable is used for image generation.
1773
1774If you take the optional step to set up a repository (package feed) on
1775the development host that can be used by DNF, you can install packages
1776from the feed while you are running the image on the target (i.e.
1777runtime installation of packages). For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001778":ref:`dev-manual/common-tasks:using runtime package management`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001779section in the Yocto Project Development Tasks Manual.
1780
1781The package-specific class you choose can affect build-time performance
1782and has space ramifications. In general, building a package with IPK
1783takes about thirty percent less time as compared to using RPM to build
1784the same or similar package. This comparison takes into account a
1785complete build of the package with all dependencies previously built.
1786The reason for this discrepancy is because the RPM package manager
1787creates and processes more :term:`Metadata` than the IPK package
1788manager. Consequently, you might consider setting ``PACKAGE_CLASSES`` to
1789"package_ipk" if you are building smaller systems.
1790
1791Before making your package manager decision, however, you should
1792consider some further things about using RPM:
1793
1794- RPM starts to provide more abilities than IPK due to the fact that it
1795 processes more Metadata. For example, this information includes
1796 individual file types, file checksum generation and evaluation on
1797 install, sparse file support, conflict detection and resolution for
1798 Multilib systems, ACID style upgrade, and repackaging abilities for
1799 rollbacks.
1800
1801- For smaller systems, the extra space used for the Berkeley Database
1802 and the amount of metadata when using RPM can affect your ability to
1803 perform on-device upgrades.
1804
1805You can find additional information on the effects of the package class
1806at these two Yocto Project mailing list links:
1807
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001808- :yocto_lists:`/pipermail/poky/2011-May/006362.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001809
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001810- :yocto_lists:`/pipermail/poky/2011-May/006363.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001811
1812.. _ref-classes-package_deb:
1813
1814``package_deb.bbclass``
1815=======================
1816
1817The ``package_deb`` class provides support for creating packages that
1818use the Debian (i.e. ``.deb``) file format. The class ensures the
1819packages are written out in a ``.deb`` file format to the
1820``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory.
1821
1822This class inherits the :ref:`package <ref-classes-package>` class and
1823is enabled through the :term:`PACKAGE_CLASSES`
1824variable in the ``local.conf`` file.
1825
1826.. _ref-classes-package_ipk:
1827
1828``package_ipk.bbclass``
1829=======================
1830
1831The ``package_ipk`` class provides support for creating packages that
1832use the IPK (i.e. ``.ipk``) file format. The class ensures the packages
1833are written out in a ``.ipk`` file format to the
1834``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory.
1835
1836This class inherits the :ref:`package <ref-classes-package>` class and
1837is enabled through the :term:`PACKAGE_CLASSES`
1838variable in the ``local.conf`` file.
1839
1840.. _ref-classes-package_rpm:
1841
1842``package_rpm.bbclass``
1843=======================
1844
1845The ``package_rpm`` class provides support for creating packages that
1846use the RPM (i.e. ``.rpm``) file format. The class ensures the packages
1847are written out in a ``.rpm`` file format to the
1848``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory.
1849
1850This class inherits the :ref:`package <ref-classes-package>` class and
1851is enabled through the :term:`PACKAGE_CLASSES`
1852variable in the ``local.conf`` file.
1853
1854.. _ref-classes-package_tar:
1855
1856``package_tar.bbclass``
1857=======================
1858
1859The ``package_tar`` class provides support for creating tarballs. The
1860class ensures the packages are written out in a tarball format to the
1861``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory.
1862
1863This class inherits the :ref:`package <ref-classes-package>` class and
1864is enabled through the :term:`PACKAGE_CLASSES`
1865variable in the ``local.conf`` file.
1866
1867.. note::
1868
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001869 You cannot specify the ``package_tar`` class first using the
1870 ``PACKAGE_CLASSES`` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001871 file formats for your image or SDK.
1872
1873.. _ref-classes-packagedata:
1874
1875``packagedata.bbclass``
1876=======================
1877
1878The ``packagedata`` class provides common functionality for reading
1879``pkgdata`` files found in :term:`PKGDATA_DIR`. These
1880files contain information about each output package produced by the
1881OpenEmbedded build system.
1882
1883This class is enabled by default because it is inherited by the
1884:ref:`package <ref-classes-package>` class.
1885
1886.. _ref-classes-packagegroup:
1887
1888``packagegroup.bbclass``
1889========================
1890
1891The ``packagegroup`` class sets default values appropriate for package
1892group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and
1893so forth). It is highly recommended that all package group recipes
1894inherit this class.
1895
1896For information on how to use this class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001897":ref:`dev-manual/common-tasks:customizing images using custom package groups`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001898section in the Yocto Project Development Tasks Manual.
1899
1900Previously, this class was called the ``task`` class.
1901
1902.. _ref-classes-patch:
1903
1904``patch.bbclass``
1905=================
1906
1907The ``patch`` class provides all functionality for applying patches
1908during the :ref:`ref-tasks-patch` task.
1909
1910This class is enabled by default because it is inherited by the
1911:ref:`base <ref-classes-base>` class.
1912
1913.. _ref-classes-perlnative:
1914
1915``perlnative.bbclass``
1916======================
1917
1918When inherited by a recipe, the ``perlnative`` class supports using the
1919native version of Perl built by the build system rather than using the
1920version provided by the build host.
1921
1922.. _ref-classes-pixbufcache:
1923
1924``pixbufcache.bbclass``
1925=======================
1926
1927The ``pixbufcache`` class generates the proper post-install and
1928post-remove (postinst/postrm) scriptlets for packages that install
1929pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets
1930call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache.
1931Since the cache files are architecture-specific, ``update_pixbuf_cache``
1932is run using QEMU if the postinst scriptlets need to be run on the build
1933host during image creation.
1934
1935If the pixbuf loaders being installed are in packages other than the
1936recipe's main package, set
1937:term:`PIXBUF_PACKAGES` to specify the packages
1938containing the loaders.
1939
1940.. _ref-classes-pkgconfig:
1941
1942``pkgconfig.bbclass``
1943=====================
1944
1945The ``pkgconfig`` class provides a standard way to get header and
1946library information by using ``pkg-config``. This class aims to smooth
1947integration of ``pkg-config`` into libraries that use it.
1948
1949During staging, BitBake installs ``pkg-config`` data into the
1950``sysroots/`` directory. By making use of sysroot functionality within
1951``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the
1952files.
1953
1954.. _ref-classes-populate-sdk:
1955
1956``populate_sdk.bbclass``
1957========================
1958
1959The ``populate_sdk`` class provides support for SDK-only recipes. For
1960information on advantages gained when building a cross-development
1961toolchain using the :ref:`ref-tasks-populate_sdk`
Andrew Geissler09209ee2020-12-13 08:44:15 -06001962task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001963section in the Yocto Project Application Development and the Extensible
1964Software Development Kit (eSDK) manual.
1965
1966.. _ref-classes-populate-sdk-*:
1967
1968``populate_sdk_*.bbclass``
1969==========================
1970
1971The ``populate_sdk_*`` classes support SDK creation and consist of the
1972following classes:
1973
1974- ``populate_sdk_base``: The base class supporting SDK creation under
1975 all package managers (i.e. DEB, RPM, and opkg).
1976
1977- ``populate_sdk_deb``: Supports creation of the SDK given the Debian
1978 package manager.
1979
1980- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM
1981 package manager.
1982
1983- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg
1984 (IPK format) package manager.
1985
1986- ``populate_sdk_ext``: Supports extensible SDK creation under all
1987 package managers.
1988
1989The ``populate_sdk_base`` class inherits the appropriate
1990``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on
1991:term:`IMAGE_PKGTYPE`.
1992
1993The base class ensures all source and destination directories are
1994established and then populates the SDK. After populating the SDK, the
1995``populate_sdk_base`` class constructs two sysroots:
1996``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which
1997contains the cross-compiler and associated tooling, and the target,
1998which contains a target root filesystem that is configured for the SDK
1999usage. These two images reside in :term:`SDK_OUTPUT`,
Andrew Geisslerc926e172021-05-07 16:11:35 -05002000which consists of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002001
2002 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
2003 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
2004
2005Finally, the base populate SDK class creates the toolchain environment
2006setup script, the tarball of the SDK, and the installer.
2007
2008The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and
2009``populate_sdk_ipk`` classes each support the specific type of SDK.
2010These classes are inherited by and used with the ``populate_sdk_base``
2011class.
2012
2013For more information on the cross-development toolchain generation, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06002014the ":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002015section in the Yocto Project Overview and Concepts Manual. For
2016information on advantages gained when building a cross-development
2017toolchain using the :ref:`ref-tasks-populate_sdk`
2018task, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002019":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002020section in the Yocto Project Application Development and the Extensible
2021Software Development Kit (eSDK) manual.
2022
2023.. _ref-classes-prexport:
2024
2025``prexport.bbclass``
2026====================
2027
2028The ``prexport`` class provides functionality for exporting
2029:term:`PR` values.
2030
2031.. note::
2032
2033 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002034 when using "``bitbake-prserv-tool export``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002035
2036.. _ref-classes-primport:
2037
2038``primport.bbclass``
2039====================
2040
2041The ``primport`` class provides functionality for importing
2042:term:`PR` values.
2043
2044.. note::
2045
2046 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002047 when using "``bitbake-prserv-tool import``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002048
2049.. _ref-classes-prserv:
2050
2051``prserv.bbclass``
2052==================
2053
2054The ``prserv`` class provides functionality for using a :ref:`PR
Andrew Geissler09209ee2020-12-13 08:44:15 -06002055service <dev-manual/common-tasks:working with a pr service>` in order to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002056automatically manage the incrementing of the :term:`PR`
2057variable for each recipe.
2058
2059This class is enabled by default because it is inherited by the
2060:ref:`package <ref-classes-package>` class. However, the OpenEmbedded
2061build system will not enable the functionality of this class unless
2062:term:`PRSERV_HOST` has been set.
2063
2064.. _ref-classes-ptest:
2065
2066``ptest.bbclass``
2067=================
2068
2069The ``ptest`` class provides functionality for packaging and installing
2070runtime tests for recipes that build software that provides these tests.
2071
2072This class is intended to be inherited by individual recipes. However,
2073the class' functionality is largely disabled unless "ptest" appears in
2074:term:`DISTRO_FEATURES`. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002075":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002076section in the Yocto Project Development Tasks Manual for more information
2077on ptest.
2078
2079.. _ref-classes-ptest-gnome:
2080
2081``ptest-gnome.bbclass``
2082=======================
2083
2084Enables package tests (ptests) specifically for GNOME packages, which
2085have tests intended to be executed with ``gnome-desktop-testing``.
2086
2087For information on setting up and running ptests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002088":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002089section in the Yocto Project Development Tasks Manual.
2090
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002091.. _ref-classes-python3-dir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002092
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002093``python3-dir.bbclass``
2094=======================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002095
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002096The ``python3-dir`` class provides the base version, location, and site
2097package location for Python 3.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002098
2099.. _ref-classes-python3native:
2100
2101``python3native.bbclass``
2102=========================
2103
2104The ``python3native`` class supports using the native version of Python
21053 built by the build system rather than support of the version provided
2106by the build host.
2107
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002108.. _ref-classes-python3targetconfig:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002109
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002110``python3targetconfig.bbclass``
2111===============================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002112
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002113The ``python3targetconfig`` class supports using the native version of Python
21143 built by the build system rather than support of the version provided
2115by the build host, except that the configuration for the target machine
2116is accessible (such as correct installation directories). This also adds a
2117dependency on target ``python3``, so should only be used where appropriate
2118in order to avoid unnecessarily lengthening builds.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002119
2120.. _ref-classes-qemu:
2121
2122``qemu.bbclass``
2123================
2124
2125The ``qemu`` class provides functionality for recipes that either need
2126QEMU or test for the existence of QEMU. Typically, this class is used to
2127run programs for a target system on the build host using QEMU's
2128application emulation mode.
2129
2130.. _ref-classes-recipe_sanity:
2131
2132``recipe_sanity.bbclass``
2133=========================
2134
2135The ``recipe_sanity`` class checks for the presence of any host system
2136recipe prerequisites that might affect the build (e.g. variables that
2137are set or software that is present).
2138
2139.. _ref-classes-relocatable:
2140
2141``relocatable.bbclass``
2142=======================
2143
2144The ``relocatable`` class enables relocation of binaries when they are
2145installed into the sysroot.
2146
2147This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class
2148and is used by both the :ref:`cross <ref-classes-cross>` and
2149:ref:`native <ref-classes-native>` classes.
2150
2151.. _ref-classes-remove-libtool:
2152
2153``remove-libtool.bbclass``
2154==========================
2155
2156The ``remove-libtool`` class adds a post function to the
2157:ref:`ref-tasks-install` task to remove all ``.la`` files
2158installed by ``libtool``. Removing these files results in them being
2159absent from both the sysroot and target packages.
2160
2161If a recipe needs the ``.la`` files to be installed, then the recipe can
Andrew Geisslerc926e172021-05-07 16:11:35 -05002162override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002163
2164 REMOVE_LIBTOOL_LA = "0"
2165
2166.. note::
2167
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002168 The ``remove-libtool`` class is not enabled by default.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002169
2170.. _ref-classes-report-error:
2171
2172``report-error.bbclass``
2173========================
2174
2175The ``report-error`` class supports enabling the :ref:`error reporting
Andrew Geissler09209ee2020-12-13 08:44:15 -06002176tool <dev-manual/common-tasks:using the error reporting tool>`",
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002177which allows you to submit build error information to a central database.
2178
2179The class collects debug information for recipe, recipe version, task,
2180machine, distro, build system, target system, host distro, branch,
2181commit, and log. From the information, report files using a JSON format
2182are created and stored in
2183``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2184
2185.. _ref-classes-rm-work:
2186
2187``rm_work.bbclass``
2188===================
2189
2190The ``rm_work`` class supports deletion of temporary workspace, which
2191can ease your hard drive demands during builds.
2192
2193The OpenEmbedded build system can use a substantial amount of disk space
2194during the build process. A portion of this space is the work files
2195under the ``${TMPDIR}/work`` directory for each recipe. Once the build
2196system generates the packages for a recipe, the work files for that
2197recipe are no longer needed. However, by default, the build system
2198preserves these files for inspection and possible debugging purposes. If
2199you would rather have these files deleted to save disk space as the
2200build progresses, you can enable ``rm_work`` by adding the following to
2201your ``local.conf`` file, which is found in the :term:`Build Directory`.
2202::
2203
2204 INHERIT += "rm_work"
2205
2206If you are
2207modifying and building source code out of the work directory for a
2208recipe, enabling ``rm_work`` will potentially result in your changes to
2209the source being lost. To exclude some recipes from having their work
2210directories deleted by ``rm_work``, you can add the names of the recipe
2211or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which
Andrew Geisslerc926e172021-05-07 16:11:35 -05002212can also be set in your ``local.conf`` file. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002213
2214 RM_WORK_EXCLUDE += "busybox glibc"
2215
2216.. _ref-classes-rootfs*:
2217
2218``rootfs*.bbclass``
2219===================
2220
2221The ``rootfs*`` classes support creating the root filesystem for an
2222image and consist of the following classes:
2223
2224- The ``rootfs-postcommands`` class, which defines filesystem
2225 post-processing functions for image recipes.
2226
2227- The ``rootfs_deb`` class, which supports creation of root filesystems
2228 for images built using ``.deb`` packages.
2229
2230- The ``rootfs_rpm`` class, which supports creation of root filesystems
2231 for images built using ``.rpm`` packages.
2232
2233- The ``rootfs_ipk`` class, which supports creation of root filesystems
2234 for images built using ``.ipk`` packages.
2235
2236- The ``rootfsdebugfiles`` class, which installs additional files found
2237 on the build host directly into the root filesystem.
2238
2239The root filesystem is created from packages using one of the
2240``rootfs*.bbclass`` files as determined by the
2241:term:`PACKAGE_CLASSES` variable.
2242
2243For information on how root filesystem images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002244":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002245section in the Yocto Project Overview and Concepts Manual.
2246
2247.. _ref-classes-sanity:
2248
2249``sanity.bbclass``
2250==================
2251
2252The ``sanity`` class checks to see if prerequisite software is present
2253on the host system so that users can be notified of potential problems
2254that might affect their build. The class also performs basic user
2255configuration checks from the ``local.conf`` configuration file to
2256prevent common mistakes that cause build failures. Distribution policy
2257usually determines whether to include this class.
2258
2259.. _ref-classes-scons:
2260
2261``scons.bbclass``
2262=================
2263
2264The ``scons`` class supports recipes that need to build software that
2265uses the SCons build system. You can use the
2266:term:`EXTRA_OESCONS` variable to specify
2267additional configuration options you want to pass SCons command line.
2268
2269.. _ref-classes-sdl:
2270
2271``sdl.bbclass``
2272===============
2273
2274The ``sdl`` class supports recipes that need to build software that uses
2275the Simple DirectMedia Layer (SDL) library.
2276
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002277.. _ref-classes-setuptools3:
2278
2279``setuptools3.bbclass``
2280=======================
2281
2282The ``setuptools3`` class supports Python version 3.x extensions that
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002283use build systems based on ``setuptools``. If your recipe uses these
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002284build systems, the recipe needs to inherit the ``setuptools3`` class.
2285
2286.. _ref-classes-sign_rpm:
2287
2288``sign_rpm.bbclass``
2289====================
2290
2291The ``sign_rpm`` class supports generating signed RPM packages.
2292
2293.. _ref-classes-sip:
2294
2295``sip.bbclass``
2296===============
2297
2298The ``sip`` class supports recipes that build or package SIP-based
2299Python bindings.
2300
2301.. _ref-classes-siteconfig:
2302
2303``siteconfig.bbclass``
2304======================
2305
2306The ``siteconfig`` class provides functionality for handling site
2307configuration. The class is used by the
2308:ref:`autotools <ref-classes-autotools>` class to accelerate the
2309:ref:`ref-tasks-configure` task.
2310
2311.. _ref-classes-siteinfo:
2312
2313``siteinfo.bbclass``
2314====================
2315
2316The ``siteinfo`` class provides information about the targets that might
2317be needed by other classes or recipes.
2318
2319As an example, consider Autotools, which can require tests that must
2320execute on the target hardware. Since this is not possible in general
2321when cross compiling, site information is used to provide cached test
2322results so these tests can be skipped over but still make the correct
2323values available. The ``meta/site directory`` contains test results
2324sorted into different categories such as architecture, endianness, and
2325the ``libc`` used. Site information provides a list of files containing
2326data relevant to the current build in the ``CONFIG_SITE`` variable that
2327Autotools automatically picks up.
2328
2329The class also provides variables like ``SITEINFO_ENDIANNESS`` and
2330``SITEINFO_BITS`` that can be used elsewhere in the metadata.
2331
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002332.. _ref-classes-sstate:
2333
2334``sstate.bbclass``
2335==================
2336
2337The ``sstate`` class provides support for Shared State (sstate). By
2338default, the class is enabled through the
2339:term:`INHERIT_DISTRO` variable's default value.
2340
2341For more information on sstate, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002342":ref:`overview-manual/concepts:shared state cache`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002343section in the Yocto Project Overview and Concepts Manual.
2344
2345.. _ref-classes-staging:
2346
2347``staging.bbclass``
2348===================
2349
2350The ``staging`` class installs files into individual recipe work
2351directories for sysroots. The class contains the following key tasks:
2352
2353- The :ref:`ref-tasks-populate_sysroot` task,
2354 which is responsible for handing the files that end up in the recipe
2355 sysroots.
2356
2357- The
2358 :ref:`ref-tasks-prepare_recipe_sysroot`
2359 task (a "partner" task to the ``populate_sysroot`` task), which
2360 installs the files into the individual recipe work directories (i.e.
2361 :term:`WORKDIR`).
2362
2363The code in the ``staging`` class is complex and basically works in two
2364stages:
2365
2366- *Stage One:* The first stage addresses recipes that have files they
2367 want to share with other recipes that have dependencies on the
2368 originating recipe. Normally these dependencies are installed through
2369 the :ref:`ref-tasks-install` task into
2370 ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task
2371 copies a subset of these files into ``${SYSROOT_DESTDIR}``. This
2372 subset of files is controlled by the
2373 :term:`SYSROOT_DIRS`,
2374 :term:`SYSROOT_DIRS_NATIVE`, and
2375 :term:`SYSROOT_DIRS_BLACKLIST`
2376 variables.
2377
2378 .. note::
2379
2380 Additionally, a recipe can customize the files further by
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002381 declaring a processing function in the ``SYSROOT_PREPROCESS_FUNCS``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002382 variable.
2383
2384 A shared state (sstate) object is built from these files and the
2385 files are placed into a subdirectory of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002386 :ref:`structure-build-tmp-sysroots-components`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002387 The files are scanned for hardcoded paths to the original
2388 installation location. If the location is found in text files, the
2389 hardcoded locations are replaced by tokens and a list of the files
2390 needing such replacements is created. These adjustments are referred
2391 to as "FIXMEs". The list of files that are scanned for paths is
2392 controlled by the :term:`SSTATE_SCAN_FILES`
2393 variable.
2394
2395- *Stage Two:* The second stage addresses recipes that want to use
2396 something from another recipe and declare a dependency on that recipe
2397 through the :term:`DEPENDS` variable. The recipe will
2398 have a
2399 :ref:`ref-tasks-prepare_recipe_sysroot`
2400 task and when this task executes, it creates the ``recipe-sysroot``
2401 and ``recipe-sysroot-native`` in the recipe work directory (i.e.
2402 :term:`WORKDIR`). The OpenEmbedded build system
2403 creates hard links to copies of the relevant files from
2404 ``sysroots-components`` into the recipe work directory.
2405
2406 .. note::
2407
2408 If hard links are not possible, the build system uses actual
2409 copies.
2410
2411 The build system then addresses any "FIXMEs" to paths as defined from
2412 the list created in the first stage.
2413
2414 Finally, any files in ``${bindir}`` within the sysroot that have the
2415 prefix "``postinst-``" are executed.
2416
2417 .. note::
2418
2419 Although such sysroot post installation scripts are not
2420 recommended for general use, the files do allow some issues such
2421 as user creation and module indexes to be addressed.
2422
2423 Because recipes can have other dependencies outside of ``DEPENDS``
2424 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
2425 the sysroot creation function ``extend_recipe_sysroot`` is also added
2426 as a pre-function for those tasks whose dependencies are not through
2427 ``DEPENDS`` but operate similarly.
2428
2429 When installing dependencies into the sysroot, the code traverses the
2430 dependency graph and processes dependencies in exactly the same way
2431 as the dependencies would or would not be when installed from sstate.
2432 This processing means, for example, a native tool would have its
2433 native dependencies added but a target library would not have its
2434 dependencies traversed or installed. The same sstate dependency code
2435 is used so that builds should be identical regardless of whether
2436 sstate was used or not. For a closer look, see the
2437 ``setscene_depvalid()`` function in the
2438 :ref:`sstate <ref-classes-sstate>` class.
2439
2440 The build system is careful to maintain manifests of the files it
2441 installs so that any given dependency can be installed as needed. The
2442 sstate hash of the installed item is also stored so that if it
2443 changes, the build system can reinstall it.
2444
2445.. _ref-classes-syslinux:
2446
2447``syslinux.bbclass``
2448====================
2449
2450The ``syslinux`` class provides syslinux-specific functions for building
2451bootable images.
2452
2453The class supports the following variables:
2454
2455- :term:`INITRD`: Indicates list of filesystem images to
2456 concatenate and use as an initial RAM disk (initrd). This variable is
2457 optional.
2458
2459- :term:`ROOTFS`: Indicates a filesystem image to include
2460 as the root filesystem. This variable is optional.
2461
2462- :term:`AUTO_SYSLINUXMENU`: Enables creating
2463 an automatic menu when set to "1".
2464
2465- :term:`LABELS`: Lists targets for automatic
2466 configuration.
2467
2468- :term:`APPEND`: Lists append string overrides for each
2469 label.
2470
2471- :term:`SYSLINUX_OPTS`: Lists additional options
2472 to add to the syslinux file. Semicolon characters separate multiple
2473 options.
2474
2475- :term:`SYSLINUX_SPLASH`: Lists a background
2476 for the VGA boot menu when you are using the boot menu.
2477
2478- :term:`SYSLINUX_DEFAULT_CONSOLE`: Set
2479 to "console=ttyX" to change kernel boot default console.
2480
2481- :term:`SYSLINUX_SERIAL`: Sets an alternate
2482 serial port. Or, turns off serial when the variable is set with an
2483 empty string.
2484
2485- :term:`SYSLINUX_SERIAL_TTY`: Sets an
2486 alternate "console=tty..." kernel boot argument.
2487
2488.. _ref-classes-systemd:
2489
2490``systemd.bbclass``
2491===================
2492
2493The ``systemd`` class provides support for recipes that install systemd
2494unit files.
2495
2496The functionality for this class is disabled unless you have "systemd"
2497in :term:`DISTRO_FEATURES`.
2498
2499Under this class, the recipe or Makefile (i.e. whatever the recipe is
2500calling during the :ref:`ref-tasks-install` task)
2501installs unit files into
2502``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit
2503files being installed go into packages other than the main package, you
2504need to set :term:`SYSTEMD_PACKAGES` in your
2505recipe to identify the packages in which the files will be installed.
2506
2507You should set :term:`SYSTEMD_SERVICE` to the
2508name of the service file. You should also use a package name override to
2509indicate the package to which the value applies. If the value applies to
2510the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
Andrew Geisslerc926e172021-05-07 16:11:35 -05002511is an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002512
2513 SYSTEMD_SERVICE_${PN} = "connman.service"
2514
2515Services are set up to start on boot automatically
2516unless you have set
2517:term:`SYSTEMD_AUTO_ENABLE` to "disable".
2518
2519For more information on ``systemd``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002520":ref:`dev-manual/common-tasks:selecting an initialization manager`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002521section in the Yocto Project Development Tasks Manual.
2522
2523.. _ref-classes-systemd-boot:
2524
2525``systemd-boot.bbclass``
2526========================
2527
2528The ``systemd-boot`` class provides functions specific to the
2529systemd-boot bootloader for building bootable images. This is an
2530internal class and is not intended to be used directly.
2531
2532.. note::
2533
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002534 The ``systemd-boot`` class is a result from merging the ``gummiboot`` class
2535 used in previous Yocto Project releases with the ``systemd`` project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002536
2537Set the :term:`EFI_PROVIDER` variable to
2538"systemd-boot" to use this class. Doing so creates a standalone EFI
2539bootloader that is not dependent on systemd.
2540
2541For information on more variables used and supported in this class, see
2542the :term:`SYSTEMD_BOOT_CFG`,
2543:term:`SYSTEMD_BOOT_ENTRIES`, and
2544:term:`SYSTEMD_BOOT_TIMEOUT` variables.
2545
2546You can also see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002547documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002548for more information.
2549
2550.. _ref-classes-terminal:
2551
2552``terminal.bbclass``
2553====================
2554
2555The ``terminal`` class provides support for starting a terminal session.
2556The :term:`OE_TERMINAL` variable controls which
2557terminal emulator is used for the session.
2558
2559Other classes use the ``terminal`` class anywhere a separate terminal
2560session needs to be started. For example, the
2561:ref:`patch <ref-classes-patch>` class assuming
2562:term:`PATCHRESOLVE` is set to "user", the
2563:ref:`cml1 <ref-classes-cml1>` class, and the
2564:ref:`devshell <ref-classes-devshell>` class all use the ``terminal``
2565class.
2566
2567.. _ref-classes-testimage*:
2568
2569``testimage*.bbclass``
2570======================
2571
2572The ``testimage*`` classes support running automated tests against
2573images using QEMU and on actual hardware. The classes handle loading the
2574tests and starting the image. To use the classes, you need to perform
2575steps to set up the environment.
2576
2577.. note::
2578
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002579 Best practices include using :term:`IMAGE_CLASSES` rather than
2580 :term:`INHERIT` to inherit the ``testimage`` class for automated image
2581 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002582
2583The tests are commands that run on the target system over ``ssh``. Each
2584test is written in Python and makes use of the ``unittest`` module.
2585
2586The ``testimage.bbclass`` runs tests on an image when called using the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002587following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002588
2589 $ bitbake -c testimage image
2590
2591The ``testimage-auto`` class
2592runs tests on an image after the image is constructed (i.e.
2593:term:`TESTIMAGE_AUTO` must be set to "1").
2594
2595For information on how to enable, run, and create new tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002596":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002597section in the Yocto Project Development Tasks Manual.
2598
2599.. _ref-classes-testsdk:
2600
2601``testsdk.bbclass``
2602===================
2603
2604This class supports running automated tests against software development
2605kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
Andrew Geisslerc926e172021-05-07 16:11:35 -05002606using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002607
2608 $ bitbake -c testsdk image
2609
2610.. note::
2611
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002612 Best practices include using :term:`IMAGE_CLASSES` rather than
2613 :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK
2614 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002615
2616.. _ref-classes-texinfo:
2617
2618``texinfo.bbclass``
2619===================
2620
2621This class should be inherited by recipes whose upstream packages invoke
2622the ``texinfo`` utilities at build-time. Native and cross recipes are
2623made to use the dummy scripts provided by ``texinfo-dummy-native``, for
2624improved performance. Target architecture recipes use the genuine
2625Texinfo utilities. By default, they use the Texinfo utilities on the
2626host system.
2627
2628.. note::
2629
2630 If you want to use the Texinfo recipe shipped with the build system,
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002631 you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo
2632 from :term:`SANITY_REQUIRED_UTILITIES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002633
2634.. _ref-classes-toaster:
2635
2636``toaster.bbclass``
2637===================
2638
2639The ``toaster`` class collects information about packages and images and
2640sends them as events that the BitBake user interface can receive. The
2641class is enabled when the Toaster user interface is running.
2642
2643This class is not intended to be used directly.
2644
2645.. _ref-classes-toolchain-scripts:
2646
2647``toolchain-scripts.bbclass``
2648=============================
2649
2650The ``toolchain-scripts`` class provides the scripts used for setting up
2651the environment for installed SDKs.
2652
2653.. _ref-classes-typecheck:
2654
2655``typecheck.bbclass``
2656=====================
2657
2658The ``typecheck`` class provides support for validating the values of
2659variables set at the configuration level against their defined types.
2660The OpenEmbedded build system allows you to define the type of a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002661variable using the "type" varflag. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002662
2663 IMAGE_FEATURES[type] = "list"
2664
2665.. _ref-classes-uboot-config:
2666
2667``uboot-config.bbclass``
2668========================
2669
2670The ``uboot-config`` class provides support for U-Boot configuration for
Andrew Geisslerc926e172021-05-07 16:11:35 -05002671a machine. Specify the machine in your recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002672
2673 UBOOT_CONFIG ??= <default>
2674 UBOOT_CONFIG[foo] = "config,images"
2675
Andrew Geisslerc926e172021-05-07 16:11:35 -05002676You can also specify the machine using this method::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002677
2678 UBOOT_MACHINE = "config"
2679
2680See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
2681information.
2682
2683.. _ref-classes-uninative:
2684
2685``uninative.bbclass``
2686=====================
2687
2688Attempts to isolate the build system from the host distribution's C
2689library in order to make re-use of native shared state artifacts across
2690different host distributions practical. With this class enabled, a
2691tarball containing a pre-built C library is downloaded at the start of
2692the build. In the Poky reference distribution this is enabled by default
2693through ``meta/conf/distro/include/yocto-uninative.inc``. Other
2694distributions that do not derive from poky can also
2695"``require conf/distro/include/yocto-uninative.inc``" to use this.
2696Alternatively if you prefer, you can build the uninative-tarball recipe
2697yourself, publish the resulting tarball (e.g. via HTTP) and set
2698``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an
2699example, see the ``meta/conf/distro/include/yocto-uninative.inc``.
2700
2701The ``uninative`` class is also used unconditionally by the extensible
2702SDK. When building the extensible SDK, ``uninative-tarball`` is built
2703and the resulting tarball is included within the SDK.
2704
2705.. _ref-classes-update-alternatives:
2706
2707``update-alternatives.bbclass``
2708===============================
2709
2710The ``update-alternatives`` class helps the alternatives system when
2711multiple sources provide the same command. This situation occurs when
2712several programs that have the same or similar function are installed
2713with the same name. For example, the ``ar`` command is available from
2714the ``busybox``, ``binutils`` and ``elfutils`` packages. The
2715``update-alternatives`` class handles renaming the binaries so that
2716multiple packages can be installed without conflicts. The ``ar`` command
2717still works regardless of which packages are installed or subsequently
2718removed. The class renames the conflicting binary in each package and
2719symlinks the highest priority binary during installation or removal of
2720packages.
2721
2722To use this class, you need to define a number of variables:
2723
2724- :term:`ALTERNATIVE`
2725
2726- :term:`ALTERNATIVE_LINK_NAME`
2727
2728- :term:`ALTERNATIVE_TARGET`
2729
2730- :term:`ALTERNATIVE_PRIORITY`
2731
2732These variables list alternative commands needed by a package, provide
2733pathnames for links, default links for targets, and so forth. For
2734details on how to use this class, see the comments in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002735:yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes/update-alternatives.bbclass>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002736file.
2737
2738.. note::
2739
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002740 You can use the ``update-alternatives`` command directly in your recipes.
2741 However, this class simplifies things in most cases.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002742
2743.. _ref-classes-update-rc.d:
2744
2745``update-rc.d.bbclass``
2746=======================
2747
2748The ``update-rc.d`` class uses ``update-rc.d`` to safely install an
2749initialization script on behalf of the package. The OpenEmbedded build
2750system takes care of details such as making sure the script is stopped
2751before a package is removed and started when the package is installed.
2752
2753Three variables control this class: ``INITSCRIPT_PACKAGES``,
2754``INITSCRIPT_NAME`` and ``INITSCRIPT_PARAMS``. See the variable links
2755for details.
2756
2757.. _ref-classes-useradd:
2758
2759``useradd*.bbclass``
2760====================
2761
2762The ``useradd*`` classes support the addition of users or groups for
2763usage by the package on the target. For example, if you have packages
2764that contain system services that should be run under their own user or
2765group, you can use these classes to enable creation of the user or
2766group. The ``meta-skeleton/recipes-skeleton/useradd/useradd-example.bb``
2767recipe in the :term:`Source Directory` provides a simple
2768example that shows how to add three users and groups to two packages.
2769See the ``useradd-example.bb`` recipe for more information on how to use
2770these classes.
2771
2772The ``useradd_base`` class provides basic functionality for user or
2773groups settings.
2774
2775The ``useradd*`` classes support the
2776:term:`USERADD_PACKAGES`,
2777:term:`USERADD_PARAM`,
2778:term:`GROUPADD_PARAM`, and
2779:term:`GROUPMEMS_PARAM` variables.
2780
2781The ``useradd-staticids`` class supports the addition of users or groups
2782that have static user identification (``uid``) and group identification
2783(``gid``) values.
2784
2785The default behavior of the OpenEmbedded build system for assigning
2786``uid`` and ``gid`` values when packages add users and groups during
2787package install time is to add them dynamically. This works fine for
2788programs that do not care what the values of the resulting users and
2789groups become. In these cases, the order of the installation determines
2790the final ``uid`` and ``gid`` values. However, if non-deterministic
2791``uid`` and ``gid`` values are a problem, you can override the default,
2792dynamic application of these values by setting static values. When you
2793set static values, the OpenEmbedded build system looks in
2794:term:`BBPATH` for ``files/passwd`` and ``files/group``
2795files for the values.
2796
2797To use static ``uid`` and ``gid`` values, you need to set some
2798variables. See the :term:`USERADDEXTENSION`,
2799:term:`USERADD_UID_TABLES`,
2800:term:`USERADD_GID_TABLES`, and
2801:term:`USERADD_ERROR_DYNAMIC` variables.
2802You can also see the :ref:`useradd <ref-classes-useradd>` class for
2803additional information.
2804
2805.. note::
2806
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002807 You do not use the ``useradd-staticids`` class directly. You either enable
2808 or disable the class by setting the ``USERADDEXTENSION`` variable. If you
2809 enable or disable the class in a configured system, :term:`TMPDIR` might
2810 contain incorrect ``uid`` and ``gid`` values. Deleting the ``TMPDIR``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002811 directory will correct this condition.
2812
2813.. _ref-classes-utility-tasks:
2814
2815``utility-tasks.bbclass``
2816=========================
2817
2818The ``utility-tasks`` class provides support for various "utility" type
2819tasks that are applicable to all recipes, such as
2820:ref:`ref-tasks-clean` and
2821:ref:`ref-tasks-listtasks`.
2822
2823This class is enabled by default because it is inherited by the
2824:ref:`base <ref-classes-base>` class.
2825
2826.. _ref-classes-utils:
2827
2828``utils.bbclass``
2829=================
2830
2831The ``utils`` class provides some useful Python functions that are
2832typically used in inline Python expressions (e.g. ``${@...}``). One
2833example use is for ``bb.utils.contains()``.
2834
2835This class is enabled by default because it is inherited by the
2836:ref:`base <ref-classes-base>` class.
2837
2838.. _ref-classes-vala:
2839
2840``vala.bbclass``
2841================
2842
2843The ``vala`` class supports recipes that need to build software written
2844using the Vala programming language.
2845
2846.. _ref-classes-waf:
2847
2848``waf.bbclass``
2849===============
2850
2851The ``waf`` class supports recipes that need to build software that uses
2852the Waf build system. You can use the
2853:term:`EXTRA_OECONF` or
2854:term:`PACKAGECONFIG_CONFARGS` variables
2855to specify additional configuration options to be passed on the Waf
2856command line.