blob: d9065b3619e5e1d563235026e7517ce8c4b5b8de [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
Andrew Geissler09036742021-06-25 14:25:14 -050053 different :term:`MACHINE` is built even when the recipe never changes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050054
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
Andrew Geissler09036742021-06-25 14:25:14 -0500113 additional parameters to ``configure`` through the :term:`EXTRA_OECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114 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
Andrew Geissler5f350902021-07-23 13:09:54 -0400119 additional arguments through the :term:`EXTRA_OEMAKE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500120
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 Geissler09036742021-06-25 14:25:14 -0500171 :term:`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
Andrew Geissler595f6302022-01-24 19:11:47 +0000217building specific recipes. To use this class, inherit
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500218the class globally and set :term:`PNBLACKLIST` for
Andrew Geissler595f6302022-01-24 19:11:47 +0000219each recipe you wish to ignore. Specify the :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220value as a variable flag (varflag) and provide a reason, which is
221reported, if the package is requested to be built as the value. For
Andrew Geissler595f6302022-01-24 19:11:47 +0000222example, if you want to ignore a recipe called "exoticware", you
223add the 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
Andrew Geissler09036742021-06-25 14:25:14 -0500259remove "buildstats" from the :term:`USER_CLASSES` list.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260
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
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500292.. _ref-classes-cmake:
293
294``cmake.bbclass``
295=================
296
297The ``cmake`` class allows for recipes that need to build software using
298the `CMake <https://cmake.org/overview/>`__ build system. You can use
299the :term:`EXTRA_OECMAKE` variable to specify
300additional configuration options to be passed using the ``cmake``
301command line.
302
303On the occasion that you would be installing custom CMake toolchain
304files supplied by the application being built, you should install them
305to the preferred CMake Module directory: ``${D}${datadir}/cmake/``
306Modules during
307:ref:`ref-tasks-install`.
308
309.. _ref-classes-cml1:
310
311``cml1.bbclass``
312================
313
314The ``cml1`` class provides basic support for the Linux kernel style
315build configuration system.
316
317.. _ref-classes-compress_doc:
318
319``compress_doc.bbclass``
320========================
321
322Enables compression for man pages and info pages. This class is intended
323to be inherited globally. The default compression mechanism is gz (gzip)
324but you can select an alternative mechanism by setting the
325:term:`DOC_COMPRESS` variable.
326
327.. _ref-classes-copyleft_compliance:
328
329``copyleft_compliance.bbclass``
330===============================
331
332The ``copyleft_compliance`` class preserves source code for the purposes
333of license compliance. This class is an alternative to the ``archiver``
334class and is still used by some users even though it has been deprecated
335in favor of the :ref:`archiver <ref-classes-archiver>` class.
336
337.. _ref-classes-copyleft_filter:
338
339``copyleft_filter.bbclass``
340===========================
341
342A class used by the :ref:`archiver <ref-classes-archiver>` and
343:ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes
344for filtering licenses. The ``copyleft_filter`` class is an internal
345class and is not intended to be used directly.
346
347.. _ref-classes-core-image:
348
349``core-image.bbclass``
350======================
351
352The ``core-image`` class provides common definitions for the
353``core-image-*`` image recipes, such as support for additional
354:term:`IMAGE_FEATURES`.
355
356.. _ref-classes-cpan:
357
358``cpan*.bbclass``
359=================
360
361The ``cpan*`` classes support Perl modules.
362
363Recipes for Perl modules are simple. These recipes usually only need to
364point to the source's archive and then inherit the proper class file.
365Building is split into two methods depending on which method the module
366authors used.
367
368- Modules that use old ``Makefile.PL``-based build system require
369 ``cpan.bbclass`` in their recipes.
370
371- Modules that use ``Build.PL``-based build system require using
372 ``cpan_build.bbclass`` in their recipes.
373
374Both build methods inherit the ``cpan-base`` class for basic Perl
375support.
376
377.. _ref-classes-cross:
378
379``cross.bbclass``
380=================
381
382The ``cross`` class provides support for the recipes that build the
383cross-compilation tools.
384
385.. _ref-classes-cross-canadian:
386
387``cross-canadian.bbclass``
388==========================
389
390The ``cross-canadian`` class provides support for the recipes that build
391the Canadian Cross-compilation tools for SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600392":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500393section in the Yocto Project Overview and Concepts Manual for more
394discussion on these cross-compilation tools.
395
396.. _ref-classes-crosssdk:
397
398``crosssdk.bbclass``
399====================
400
401The ``crosssdk`` class provides support for the recipes that build the
402cross-compilation tools used for building SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600403":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404section in the Yocto Project Overview and Concepts Manual for more
405discussion on these cross-compilation tools.
406
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500407.. _ref-classes-cve-check:
408
409``cve-check.bbclass``
410=====================
411
412The ``cve-check`` class looks for known CVEs (Common Vulnerabilities
413and Exposures) while building an image. This class is meant to be
414inherited globally from a configuration file::
415
416 INHERIT += "cve-check"
417
418You can also look for vulnerabilities in specific packages by passing
419``-c cve_check`` to BitBake. You will find details in the
420":ref:`dev-manual/common-tasks:checking for vulnerabilities`"
421section in the Development Tasks Manual.
422
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500423.. _ref-classes-debian:
424
425``debian.bbclass``
426==================
427
428The ``debian`` class renames output packages so that they follow the
429Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and
430``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library
431name and version as part of the package name.
432
433If a recipe creates packages for multiple libraries (shared object files
434of ``.so`` type), use the :term:`LEAD_SONAME`
435variable in the recipe to specify the library on which to apply the
436naming scheme.
437
438.. _ref-classes-deploy:
439
440``deploy.bbclass``
441==================
442
443The ``deploy`` class handles deploying files to the
444:term:`DEPLOY_DIR_IMAGE` directory. The main
445function of this class is to allow the deploy step to be accelerated by
446shared state. Recipes that inherit this class should define their own
447:ref:`ref-tasks-deploy` function to copy the files to be
448deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
449add the task at the appropriate place, which is usually after
450:ref:`ref-tasks-compile` or
451:ref:`ref-tasks-install`. The class then takes care of
Andrew Geissler09036742021-06-25 14:25:14 -0500452staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500453
454.. _ref-classes-devshell:
455
456``devshell.bbclass``
457====================
458
459The ``devshell`` class adds the ``do_devshell`` task. Distribution
Andrew Geissler09209ee2020-12-13 08:44:15 -0600460policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500461section in the Yocto Project Development Tasks Manual for more
462information about using ``devshell``.
463
464.. _ref-classes-devupstream:
465
466``devupstream.bbclass``
467=======================
468
469The ``devupstream`` class uses
470:term:`BBCLASSEXTEND` to add a variant of the
471recipe that fetches from an alternative URI (e.g. Git) instead of a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500472tarball. Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473
474 BBCLASSEXTEND = "devupstream:target"
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500475 SRC_URI:class-devupstream = "git://git.example.com/example"
476 SRCREV:class-devupstream = "abcd1234"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500477
478Adding the above statements to your recipe creates a variant that has
479:term:`DEFAULT_PREFERENCE` set to "-1".
480Consequently, you need to select the variant of the recipe to use it.
481Any development-specific adjustments can be done by using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500482``class-devupstream`` override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500483
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500484 DEPENDS:append:class-devupstream = " gperf-native"
485 do_configure:prepend:class-devupstream() {
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500486 touch ${S}/README
487 }
488
489The class
490currently only supports creating a development variant of the target
491recipe, not ``native`` or ``nativesdk`` variants.
492
Andrew Geissler09036742021-06-25 14:25:14 -0500493The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500494support for ``native`` and ``nativesdk`` variants. Consequently, this
495functionality can be added in a future release.
496
497Support for other version control systems such as Subversion is limited
498due to BitBake's automatic fetch dependencies (e.g.
499``subversion-native``).
500
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500501.. _ref-classes-distutils3:
502
503``distutils3*.bbclass``
504=======================
505
506The ``distutils3*`` classes support recipes for Python version 3.x
507extensions, which are simple. These recipes usually only need to point
508to the source's archive and then inherit the proper class. Building is
509split into three methods depending on which method the module authors
510used.
511
512- Extensions that use an Autotools-based build system require Autotools
513 and ``distutils``-based classes in their recipes.
514
515- Extensions that use ``distutils``-based build systems require the
516 ``distutils`` class in their recipes.
517
Andrew Geissler595f6302022-01-24 19:11:47 +0000518 .. note::
519
520 ``distutils`` has been deprecated in Python 3.10 and will be removed
521 in Python 3.12. For this reason the ``distutils3*`` classes are now
522 deprecated and will be removed from core in the near future. Instead,
523 use the ``setuptools3*`` classes.
524
525
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500526- Extensions that use build systems based on ``setuptools3`` require
Andrew Geissler3b8a17c2021-04-15 15:55:55 -0500527 the :ref:`setuptools3 <ref-classes-setuptools3>` class in their
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500528 recipes.
529
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500530.. _ref-classes-externalsrc:
531
532``externalsrc.bbclass``
533=======================
534
535The ``externalsrc`` class supports building software from source code
536that is external to the OpenEmbedded build system. Building software
537from an external source tree means that the build system's normal fetch,
538unpack, and patch process is not used.
539
540By default, the OpenEmbedded build system uses the :term:`S`
541and :term:`B` variables to locate unpacked recipe source code
542and to build it, respectively. When your recipe inherits the
543``externalsrc`` class, you use the
544:term:`EXTERNALSRC` and
545:term:`EXTERNALSRC_BUILD` variables to
Andrew Geissler09036742021-06-25 14:25:14 -0500546ultimately define :term:`S` and :term:`B`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500547
548By default, this class expects the source code to support recipe builds
549that use the :term:`B` variable to point to the directory in
550which the OpenEmbedded build system places the generated objects built
Andrew Geissler09036742021-06-25 14:25:14 -0500551from the recipes. By default, the :term:`B` directory is set to the
552following, which is separate from the source directory (:term:`S`)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500553
Andrew Geissler5199d832021-09-24 16:47:35 -0500554 ${WORKDIR}/${BPN}-{PV}/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500555
556See these variables for more information:
557:term:`WORKDIR`, :term:`BPN`, and
558:term:`PV`,
559
560For more information on the ``externalsrc`` class, see the comments in
561``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
562For information on how to use the
563``externalsrc`` class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600564":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500565section in the Yocto Project Development Tasks Manual.
566
567.. _ref-classes-extrausers:
568
569``extrausers.bbclass``
570======================
571
572The ``extrausers`` class allows additional user and group configuration
573to be applied at the image level. Inheriting this class either globally
574or from an image recipe allows additional user and group operations to
575be performed using the
576:term:`EXTRA_USERS_PARAMS` variable.
577
578.. note::
579
580 The user and group operations added using the
Andrew Geissler595f6302022-01-24 19:11:47 +0000581 :ref:`extrausers <ref-classes-extrausers>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500582 class are not tied to a specific recipe outside of the recipe for the
583 image. Thus, the operations can be performed across the image as a
584 whole. Use the
Andrew Geissler595f6302022-01-24 19:11:47 +0000585 :ref:`useradd <ref-classes-useradd>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500586 class to add user and group configuration to a specific recipe.
587
Andrew Geisslerc926e172021-05-07 16:11:35 -0500588Here is an example that uses this class in an image recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500589
590 inherit extrausers
591 EXTRA_USERS_PARAMS = "\
592 useradd -p '' tester; \
593 groupadd developers; \
594 userdel nobody; \
595 groupdel -g video; \
596 groupmod -g 1020 developers; \
597 usermod -s /bin/sh tester; \
598 "
599
600Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
Andrew Geisslereff27472021-10-29 15:35:00 -0500601passwords. First on host, create the password hash::
602
603 mkpasswd -m sha256crypt tester01
604
605The resulting hash is set to a variable and used in ``useradd`` command parameters.
606Remember to escape the character ``$``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500607
608 inherit extrausers
Andrew Geisslereff27472021-10-29 15:35:00 -0500609 PASSWD = "\$X\$ABC123\$A-Long-Hash"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500610 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500611 useradd -p '${PASSWD}' tester-jim; \
612 useradd -p '${PASSWD}' tester-sue; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500613 "
614
Andrew Geisslereff27472021-10-29 15:35:00 -0500615Finally, here is an example that sets the root password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500616
617 inherit extrausers
618 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500619 usermod -p '${PASSWD}' root; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500620 "
621
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600622.. _ref-classes-features_check:
623
624``features_check.bbclass``
625=================================
626
627The ``features_check`` class allows individual recipes to check
628for required and conflicting
629:term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`.
630
631This class provides support for the following variables:
632
633- :term:`REQUIRED_DISTRO_FEATURES`
634- :term:`CONFLICT_DISTRO_FEATURES`
635- :term:`ANY_OF_DISTRO_FEATURES`
636- ``REQUIRED_MACHINE_FEATURES``
637- ``CONFLICT_MACHINE_FEATURES``
638- ``ANY_OF_MACHINE_FEATURES``
639- ``REQUIRED_COMBINED_FEATURES``
640- ``CONFLICT_COMBINED_FEATURES``
641- ``ANY_OF_COMBINED_FEATURES``
642
643If any conditions specified in the recipe using the above
644variables are not met, the recipe will be skipped, and if the
645build system attempts to build the recipe then an error will be
646triggered.
647
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500648.. _ref-classes-fontcache:
649
650``fontcache.bbclass``
651=====================
652
653The ``fontcache`` class generates the proper post-install and
654post-remove (postinst and postrm) scriptlets for font packages. These
655scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts
656to the font information cache. Since the cache files are
657architecture-specific, ``fc-cache`` runs using QEMU if the postinst
658scriptlets need to be run on the build host during image creation.
659
660If the fonts being installed are in packages other than the main
661package, set :term:`FONT_PACKAGES` to specify the
662packages containing the fonts.
663
664.. _ref-classes-fs-uuid:
665
666``fs-uuid.bbclass``
667===================
668
669The ``fs-uuid`` class extracts UUID from
670``${``\ :term:`ROOTFS`\ ``}``, which must have been built
671by the time that this function gets called. The ``fs-uuid`` class only
672works on ``ext`` file systems and depends on ``tune2fs``.
673
674.. _ref-classes-gconf:
675
676``gconf.bbclass``
677=================
678
679The ``gconf`` class provides common functionality for recipes that need
680to install GConf schemas. The schemas will be put into a separate
681package (``${``\ :term:`PN`\ ``}-gconf``) that is created
682automatically when this class is inherited. This package uses the
683appropriate post-install and post-remove (postinst/postrm) scriptlets to
684register and unregister the schemas in the target image.
685
686.. _ref-classes-gettext:
687
688``gettext.bbclass``
689===================
690
691The ``gettext`` class provides support for building software that uses
692the GNU ``gettext`` internationalization and localization system. All
693recipes building software that use ``gettext`` should inherit this
694class.
695
696.. _ref-classes-gnomebase:
697
698``gnomebase.bbclass``
699=====================
700
701The ``gnomebase`` class is the base class for recipes that build
702software from the GNOME stack. This class sets
703:term:`SRC_URI` to download the source from the GNOME
704mirrors as well as extending :term:`FILES` with the typical
705GNOME installation paths.
706
707.. _ref-classes-gobject-introspection:
708
709``gobject-introspection.bbclass``
710=================================
711
712Provides support for recipes building software that supports GObject
713introspection. This functionality is only enabled if the
714"gobject-introspection-data" feature is in
715:term:`DISTRO_FEATURES` as well as
716"qemu-usermode" being in
717:term:`MACHINE_FEATURES`.
718
719.. note::
720
721 This functionality is backfilled by default and, if not applicable,
Andrew Geissler09036742021-06-25 14:25:14 -0500722 should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
723 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500724
725.. _ref-classes-grub-efi:
726
727``grub-efi.bbclass``
728====================
729
730The ``grub-efi`` class provides ``grub-efi``-specific functions for
731building bootable images.
732
733This class supports several variables:
734
735- :term:`INITRD`: Indicates list of filesystem images to
736 concatenate and use as an initial RAM disk (initrd) (optional).
737
738- :term:`ROOTFS`: Indicates a filesystem image to include
739 as the root filesystem (optional).
740
741- :term:`GRUB_GFXSERIAL`: Set this to "1" to have
742 graphics and serial in the boot menu.
743
744- :term:`LABELS`: A list of targets for the automatic
745 configuration.
746
747- :term:`APPEND`: An override list of append strings for
748 each ``LABEL``.
749
750- :term:`GRUB_OPTS`: Additional options to add to the
751 configuration (optional). Options are delimited using semi-colon
752 characters (``;``).
753
754- :term:`GRUB_TIMEOUT`: Timeout before executing
755 the default ``LABEL`` (optional).
756
757.. _ref-classes-gsettings:
758
759``gsettings.bbclass``
760=====================
761
762The ``gsettings`` class provides common functionality for recipes that
763need to install GSettings (glib) schemas. The schemas are assumed to be
764part of the main package. Appropriate post-install and post-remove
765(postinst/postrm) scriptlets are added to register and unregister the
766schemas in the target image.
767
768.. _ref-classes-gtk-doc:
769
770``gtk-doc.bbclass``
771===================
772
773The ``gtk-doc`` class is a helper class to pull in the appropriate
774``gtk-doc`` dependencies and disable ``gtk-doc``.
775
776.. _ref-classes-gtk-icon-cache:
777
778``gtk-icon-cache.bbclass``
779==========================
780
781The ``gtk-icon-cache`` class generates the proper post-install and
782post-remove (postinst/postrm) scriptlets for packages that use GTK+ and
783install icons. These scriptlets call ``gtk-update-icon-cache`` to add
784the fonts to GTK+'s icon cache. Since the cache files are
785architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if
786the postinst scriptlets need to be run on the build host during image
787creation.
788
789.. _ref-classes-gtk-immodules-cache:
790
791``gtk-immodules-cache.bbclass``
792===============================
793
794The ``gtk-immodules-cache`` class generates the proper post-install and
795post-remove (postinst/postrm) scriptlets for packages that install GTK+
796input method modules for virtual keyboards. These scriptlets call
797``gtk-update-icon-cache`` to add the input method modules to the cache.
798Since the cache files are architecture-specific,
799``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets
800need to be run on the build host during image creation.
801
802If the input method modules being installed are in packages other than
803the main package, set
804:term:`GTKIMMODULES_PACKAGES` to specify
805the packages containing the modules.
806
807.. _ref-classes-gzipnative:
808
809``gzipnative.bbclass``
810======================
811
812The ``gzipnative`` class enables the use of different native versions of
813``gzip`` and ``pigz`` rather than the versions of these tools from the
814build host.
815
816.. _ref-classes-icecc:
817
818``icecc.bbclass``
819=================
820
821The ``icecc`` class supports
822`Icecream <https://github.com/icecc/icecream>`__, which facilitates
823taking compile jobs and distributing them among remote machines.
824
825The class stages directories with symlinks from ``gcc`` and ``g++`` to
826``icecc``, for both native and cross compilers. Depending on each
827configure or compile, the OpenEmbedded build system adds the directories
828at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and
829``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc``
830compilers, respectively.
831
832For the cross compiler, the class creates a ``tar.gz`` file that
833contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which
834is the version of the cross-compiler used in the cross-development
835toolchain, accordingly.
836
837The class handles all three different compile stages (i.e native
838,cross-kernel and target) and creates the necessary environment
839``tar.gz`` file to be used by the remote machines. The class also
840supports SDK generation.
841
842If :term:`ICECC_PATH` is not set in your
843``local.conf`` file, then the class tries to locate the ``icecc`` binary
844using ``which``. If :term:`ICECC_ENV_EXEC` is set
845in your ``local.conf`` file, the variable should point to the
846``icecc-create-env`` script provided by the user. If you do not point to
847a user-provided script, the build system uses the default script
848provided by the recipe ``icecc-create-env-native.bb``.
849
850.. note::
851
852 This script is a modified version and not the one that comes with
853 icecc.
854
855If you do not want the Icecream distributed compile support to apply to
Andrew Geissler595f6302022-01-24 19:11:47 +0000856specific recipes or classes, you can ask them to be ignored by Icecream
857by listing the recipes and classes using the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500858:term:`ICECC_USER_PACKAGE_BL` and
Andrew Geissler595f6302022-01-24 19:11:47 +0000859:term:`ICECC_USER_CLASS_BL` variables,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500860respectively, in your ``local.conf`` file. Doing so causes the
861OpenEmbedded build system to handle these compilations locally.
862
863Additionally, you can list recipes using the
864:term:`ICECC_USER_PACKAGE_WL` variable in
865your ``local.conf`` file to force ``icecc`` to be enabled for recipes
866using an empty :term:`PARALLEL_MAKE` variable.
867
868Inheriting the ``icecc`` class changes all sstate signatures.
869Consequently, if a development team has a dedicated build system that
870populates :term:`SSTATE_MIRRORS` and they want to
Andrew Geissler09036742021-06-25 14:25:14 -0500871reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500872system need to either inherit the ``icecc`` class or nobody should.
873
874At the distribution level, you can inherit the ``icecc`` class to be
875sure that all builders start with the same sstate signatures. After
876inheriting the class, you can then disable the feature by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500877:term:`ICECC_DISABLED` variable to "1" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500878
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500879 INHERIT_DISTRO:append = " icecc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500880 ICECC_DISABLED ??= "1"
881
882This practice
883makes sure everyone is using the same signatures but also requires
884individuals that do want to use Icecream to enable the feature
Andrew Geisslerc926e172021-05-07 16:11:35 -0500885individually as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500886
887 ICECC_DISABLED = ""
888
889.. _ref-classes-image:
890
891``image.bbclass``
892=================
893
894The ``image`` class helps support creating images in different formats.
895First, the root filesystem is created from packages using one of the
896``rootfs*.bbclass`` files (depending on the package format used) and
897then one or more image files are created.
898
Andrew Geissler09036742021-06-25 14:25:14 -0500899- The :term:`IMAGE_FSTYPES` variable controls the types of images to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500900 generate.
901
Andrew Geissler09036742021-06-25 14:25:14 -0500902- The :term:`IMAGE_INSTALL` variable controls the list of packages to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500903 install into the image.
904
905For information on customizing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600906":ref:`dev-manual/common-tasks:customizing images`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500907in the Yocto Project Development Tasks Manual. For information on how
908images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600909":ref:`overview-manual/concepts:images`" section in the
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600910Yocto Project Overview and Concepts Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500911
912.. _ref-classes-image-buildinfo:
913
914``image-buildinfo.bbclass``
915===========================
916
917The ``image-buildinfo`` class writes information to the target
918filesystem on ``/etc/build``.
919
920.. _ref-classes-image_types:
921
922``image_types.bbclass``
923=======================
924
925The ``image_types`` class defines all of the standard image output types
926that you can enable through the
927:term:`IMAGE_FSTYPES` variable. You can use this
928class as a reference on how to add support for custom image output
929types.
930
931By default, the :ref:`image <ref-classes-image>` class automatically
932enables the ``image_types`` class. The ``image`` class uses the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500933``IMGCLASSES`` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500934
935 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
936 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
937 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
938 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
939 IMGCLASSES += "image_types_wic"
940 IMGCLASSES += "rootfs-postcommands"
941 IMGCLASSES += "image-postinst-intercepts"
942 inherit ${IMGCLASSES}
943
944The ``image_types`` class also handles conversion and compression of images.
945
946.. note::
947
948 To build a VMware VMDK image, you need to add "wic.vmdk" to
Andrew Geissler09036742021-06-25 14:25:14 -0500949 :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500950 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500951
952.. _ref-classes-image-live:
953
954``image-live.bbclass``
955======================
956
957This class controls building "live" (i.e. HDDIMG and ISO) images. Live
958images contain syslinux for legacy booting, as well as the bootloader
959specified by :term:`EFI_PROVIDER` if
960:term:`MACHINE_FEATURES` contains "efi".
961
962Normally, you do not use this class directly. Instead, you add "live" to
963:term:`IMAGE_FSTYPES`.
964
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500965.. _ref-classes-image-prelink:
966
967``image-prelink.bbclass``
968=========================
969
970The ``image-prelink`` class enables the use of the ``prelink`` utility
971during the :ref:`ref-tasks-rootfs` task, which optimizes
972the dynamic linking of shared libraries to reduce executable startup
973time.
974
975By default, the class is enabled in the ``local.conf.template`` using
Andrew Geisslerc926e172021-05-07 16:11:35 -0500976the :term:`USER_CLASSES` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500977
Andrew Geissler5f350902021-07-23 13:09:54 -0400978 USER_CLASSES ?= "buildstats image-prelink"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500979
980.. _ref-classes-insane:
981
982``insane.bbclass``
983==================
984
985The ``insane`` class adds a step to the package generation process so
986that output quality assurance checks are generated by the OpenEmbedded
987build system. A range of checks are performed that check the build's
988output for common problems that show up during runtime. Distribution
989policy usually dictates whether to include this class.
990
991You can configure the sanity checks so that specific test failures
992either raise a warning or an error message. Typically, failures for new
993tests generate a warning. Subsequent failures for the same test would
994then generate an error message once the metadata is in a known and good
Andrew Geissler09209ee2020-12-13 08:44:15 -0600995condition. See the ":doc:`/ref-manual/qa-checks`" Chapter for a list of all the warning
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500996and error messages you might encounter using a default configuration.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500997
998Use the :term:`WARN_QA` and
999:term:`ERROR_QA` variables to control the behavior of
1000these checks at the global level (i.e. in your custom distro
1001configuration). However, to skip one or more checks in recipes, you
1002should use :term:`INSANE_SKIP`. For example, to skip
1003the check for symbolic link ``.so`` files in the main package of a
1004recipe, add the following to the recipe. You need to realize that the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001005package name override, in this example ``${PN}``, must be used::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001006
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001007 INSANE_SKIP:${PN} += "dev-so"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001008
1009Please keep in mind that the QA checks
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001010are meant to detect real or potential problems in the packaged
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001011output. So exercise caution when disabling these checks.
1012
Andrew Geissler09036742021-06-25 14:25:14 -05001013Here are the tests you can list with the :term:`WARN_QA` and
Andrew Geissler5f350902021-07-23 13:09:54 -04001014:term:`ERROR_QA` variables:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001015
1016- ``already-stripped:`` Checks that produced binaries have not
1017 already been stripped prior to the build system extracting debug
1018 symbols. It is common for upstream software projects to default to
1019 stripping debug symbols for output binaries. In order for debugging
1020 to work on the target using ``-dbg`` packages, this stripping must be
1021 disabled.
1022
1023- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit
1024 size, and endianness of any binaries to ensure they match the target
1025 architecture. This test fails if any binaries do not match the type
1026 since there would be an incompatibility. The test could indicate that
1027 the wrong compiler or compiler options have been used. Sometimes
1028 software, like bootloaders, might need to bypass this check.
1029
1030- ``buildpaths:`` Checks for paths to locations on the build host
1031 inside the output files. Currently, this test triggers too many false
1032 positives and thus is not normally enabled.
1033
1034- ``build-deps:`` Determines if a build-time dependency that is
1035 specified through :term:`DEPENDS`, explicit
1036 :term:`RDEPENDS`, or task-level dependencies exists
1037 to match any runtime dependency. This determination is particularly
1038 useful to discover where runtime dependencies are detected and added
1039 during packaging. If no explicit dependency has been specified within
1040 the metadata, at the packaging stage it is too late to ensure that
1041 the dependency is built, and thus you can end up with an error when
1042 the package is installed into the image during the
1043 :ref:`ref-tasks-rootfs` task because the auto-detected
1044 dependency was not satisfied. An example of this would be where the
1045 :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically
1046 adds a dependency on the ``initscripts-functions`` package to
1047 packages that install an initscript that refers to
1048 ``/etc/init.d/functions``. The recipe should really have an explicit
Andrew Geissler5f350902021-07-23 13:09:54 -04001049 :term:`RDEPENDS` for the package in question on ``initscripts-functions``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001050 so that the OpenEmbedded build system is able to ensure that the
1051 ``initscripts`` recipe is actually built and thus the
1052 ``initscripts-functions`` package is made available.
1053
1054- ``compile-host-path:`` Checks the
1055 :ref:`ref-tasks-compile` log for indications that
1056 paths to locations on the build host were used. Using such paths
1057 might result in host contamination of the build output.
1058
1059- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
1060 do not depend on ``-dbg`` packages, which would cause a packaging
1061 bug.
1062
1063- ``debug-files:`` Checks for ``.debug`` directories in anything but
1064 the ``-dbg`` package. The debug files should all be in the ``-dbg``
1065 package. Thus, anything packaged elsewhere is incorrect packaging.
1066
1067- ``dep-cmp:`` Checks for invalid version comparison statements in
1068 runtime dependency relationships between packages (i.e. in
1069 :term:`RDEPENDS`,
1070 :term:`RRECOMMENDS`,
1071 :term:`RSUGGESTS`,
1072 :term:`RPROVIDES`,
1073 :term:`RREPLACES`, and
1074 :term:`RCONFLICTS` variable values). Any invalid
1075 comparisons might trigger failures or undesirable behavior when
1076 passed to the package manager.
1077
1078- ``desktop:`` Runs the ``desktop-file-validate`` program against any
1079 ``.desktop`` files to validate their contents against the
1080 specification for ``.desktop`` files.
1081
1082- ``dev-deps:`` Checks that all packages except ``-dev`` or
1083 ``-staticdev`` packages do not depend on ``-dev`` packages, which
1084 would be a packaging bug.
1085
1086- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
1087 ``-dev`` package and not in any of the other packages. In general,
1088 these symlinks are only useful for development purposes. Thus, the
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001089 ``-dev`` package is the correct location for them. In very rare
1090 cases, such as dynamically loaded modules, these symlinks
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001091 are needed instead in the main package.
1092
1093- ``file-rdeps:`` Checks that file-level dependencies identified by
1094 the OpenEmbedded build system at packaging time are satisfied. For
1095 example, a shell script might start with the line ``#!/bin/bash``.
1096 This line would translate to a file dependency on ``/bin/bash``. Of
1097 the three package managers that the OpenEmbedded build system
1098 supports, only RPM directly handles file-level dependencies,
1099 resolving them automatically to packages providing the files.
1100 However, the lack of that functionality in the other two package
1101 managers does not mean the dependencies do not still need resolving.
1102 This QA check attempts to ensure that explicitly declared
1103 :term:`RDEPENDS` exist to handle any file-level
1104 dependency detected in packaged files.
1105
1106- ``files-invalid:`` Checks for :term:`FILES` variable
1107 values that contain "//", which is invalid.
1108
1109- ``host-user-contaminated:`` Checks that no package produced by the
1110 recipe contains any files outside of ``/home`` with a user or group
1111 ID that matches the user running BitBake. A match usually indicates
1112 that the files are being installed with an incorrect UID/GID, since
1113 target IDs are independent from host IDs. For additional information,
1114 see the section describing the
1115 :ref:`ref-tasks-install` task.
1116
1117- ``incompatible-license:`` Report when packages are excluded from
1118 being created due to being marked with a license that is in
1119 :term:`INCOMPATIBLE_LICENSE`.
1120
1121- ``install-host-path:`` Checks the
1122 :ref:`ref-tasks-install` log for indications that
1123 paths to locations on the build host were used. Using such paths
1124 might result in host contamination of the build output.
1125
1126- ``installed-vs-shipped:`` Reports when files have been installed
1127 within ``do_install`` but have not been included in any package by
1128 way of the :term:`FILES` variable. Files that do not
1129 appear in any package cannot be present in an image later on in the
1130 build process. Ideally, all installed files should be packaged or not
1131 installed at all. These files can be deleted at the end of
1132 ``do_install`` if the files are not needed in any package.
1133
1134- ``invalid-chars:`` Checks that the recipe metadata variables
1135 :term:`DESCRIPTION`,
1136 :term:`SUMMARY`, :term:`LICENSE`, and
1137 :term:`SECTION` do not contain non-UTF-8 characters.
1138 Some package managers do not support such characters.
1139
1140- ``invalid-packageconfig:`` Checks that no undefined features are
1141 being added to :term:`PACKAGECONFIG`. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05001142 example, any name "foo" for which the following form does not exist::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001143
1144 PACKAGECONFIG[foo] = "..."
1145
Andrew Geissler09036742021-06-25 14:25:14 -05001146- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001147 file containing these paths is incorrect since ``libtool`` adds the
1148 correct sysroot prefix when using the files automatically itself.
1149
1150- ``ldflags:`` Ensures that the binaries were linked with the
1151 :term:`LDFLAGS` options provided by the build system.
Andrew Geissler09036742021-06-25 14:25:14 -05001152 If this test fails, check that the :term:`LDFLAGS` variable is being
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001153 passed to the linker command.
1154
1155- ``libdir:`` Checks for libraries being installed into incorrect
1156 (possibly hardcoded) installation paths. For example, this test will
1157 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
1158 "lib32". Another example is when recipes install
1159 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
1160
1161- ``libexec:`` Checks if a package contains files in
1162 ``/usr/libexec``. This check is not performed if the ``libexecdir``
1163 variable has been set explicitly to ``/usr/libexec``.
1164
1165- ``packages-list:`` Checks for the same package being listed
1166 multiple times through the :term:`PACKAGES` variable
1167 value. Installing the package in this manner can cause errors during
1168 packaging.
1169
1170- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
1171 invalid format.
1172
1173- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
1174 invalid format.
1175
1176- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
1177 'link' where the specified target already exists.
1178
1179- ``perms:`` Currently, this check is unused but reserved.
1180
1181- ``pkgconfig:`` Checks ``.pc`` files for any
1182 :term:`TMPDIR`/:term:`WORKDIR` paths.
1183 Any ``.pc`` file containing these paths is incorrect since
1184 ``pkg-config`` itself adds the correct sysroot prefix when the files
1185 are accessed.
1186
1187- ``pkgname:`` Checks that all packages in
1188 :term:`PACKAGES` have names that do not contain
1189 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1190 -).
1191
Andrew Geissler09036742021-06-25 14:25:14 -05001192- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001193 undefined during :ref:`ref-tasks-package`.
1194
1195- ``pkgvarcheck:`` Checks through the variables
1196 :term:`RDEPENDS`,
1197 :term:`RRECOMMENDS`,
1198 :term:`RSUGGESTS`,
1199 :term:`RCONFLICTS`,
1200 :term:`RPROVIDES`,
1201 :term:`RREPLACES`, :term:`FILES`,
1202 :term:`ALLOW_EMPTY`, ``pkg_preinst``,
1203 ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if
1204 there are variable sets that are not package-specific. Using these
1205 variables without a package suffix is bad practice, and might
1206 unnecessarily complicate dependencies of other packages within the
1207 same recipe or have other unintended consequences.
1208
1209- ``pn-overrides:`` Checks that a recipe does not have a name
1210 (:term:`PN`) value that appears in
1211 :term:`OVERRIDES`. If a recipe is named such that
Andrew Geissler09036742021-06-25 14:25:14 -05001212 its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
1213 :term:`PN` happens to be the same as :term:`MACHINE` or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001214 :term:`DISTRO`), it can have unexpected consequences.
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001215 For example, assignments such as ``FILES:${PN} = "xyz"`` effectively
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001216 turn into ``FILES = "xyz"``.
1217
1218- ``rpaths:`` Checks for rpaths in the binaries that contain build
Andrew Geissler5f350902021-07-23 13:09:54 -04001219 system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001220 options are being passed to the linker commands and your binaries
1221 have potential security issues.
1222
1223- ``split-strip:`` Reports that splitting or stripping debug symbols
1224 from binaries has failed.
1225
1226- ``staticdev:`` Checks for static library files (``*.a``) in
1227 non-``staticdev`` packages.
1228
1229- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
1230 into :term:`TMPDIR` on the host. Such symlinks will
1231 work on the host, but are clearly invalid when running on the target.
1232
1233- ``textrel:`` Checks for ELF binaries that contain relocations in
1234 their ``.text`` sections, which can result in a performance impact at
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001235 runtime. See the explanation for the ``ELF binary`` message in
Andrew Geissler09209ee2020-12-13 08:44:15 -06001236 ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001237 issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001238
1239- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
1240 for a package are also declared on the recipe level (i.e. any license
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001241 in ``LICENSE:*`` should appear in :term:`LICENSE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001242
1243- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
1244 in the binaries that by default on a standard system are searched by
1245 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
1246 not cause any breakage, they do waste space and are unnecessary.
1247
1248- ``var-undefined:`` Reports when variables fundamental to packaging
1249 (i.e. :term:`WORKDIR`,
1250 :term:`DEPLOY_DIR`, :term:`D`,
1251 :term:`PN`, and :term:`PKGD`) are undefined
1252 during :ref:`ref-tasks-package`.
1253
1254- ``version-going-backwards:`` If Build History is enabled, reports
1255 when a package being written out has a lower version than the
1256 previously written package under the same name. If you are placing
1257 output packages into a feed and upgrading packages on a target system
1258 using that feed, the version of a package going backwards can result
1259 in the target system not correctly upgrading to the "new" version of
1260 the package.
1261
1262 .. note::
1263
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001264 This is only relevant when you are using runtime package management
1265 on your target system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001266
1267- ``xorg-driver-abi:`` Checks that all packages containing Xorg
1268 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
1269 driver ABI names. All drivers should depend on the ABI versions that
1270 they have been built against. Driver recipes that include
1271 ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
1272 automatically get these versions. Consequently, you should only need
1273 to explicitly add dependencies to binary driver recipes.
1274
1275.. _ref-classes-insserv:
1276
1277``insserv.bbclass``
1278===================
1279
1280The ``insserv`` class uses the ``insserv`` utility to update the order
1281of symbolic links in ``/etc/rc?.d/`` within an image based on
1282dependencies specified by LSB headers in the ``init.d`` scripts
1283themselves.
1284
1285.. _ref-classes-kernel:
1286
1287``kernel.bbclass``
1288==================
1289
1290The ``kernel`` class handles building Linux kernels. The class contains
1291code to build all kernel trees. All needed headers are staged into the
Andrew Geissler5f350902021-07-23 13:09:54 -04001292:term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001293using the :ref:`module <ref-classes-module>` class.
1294
1295This means that each built kernel module is packaged separately and
1296inter-module dependencies are created by parsing the ``modinfo`` output.
1297If all modules are required, then installing the ``kernel-modules``
1298package installs all packages with modules and various other kernel
1299packages such as ``kernel-vmlinux``.
1300
1301The ``kernel`` class contains logic that allows you to embed an initial
1302RAM filesystem (initramfs) image when you build the kernel image. For
1303information on how to build an initramfs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001304":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001305the Yocto Project Development Tasks Manual.
1306
1307Various other classes are used by the ``kernel`` and ``module`` classes
1308internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`,
1309:ref:`module-base <ref-classes-module-base>`, and
1310:ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes.
1311
1312.. _ref-classes-kernel-arch:
1313
1314``kernel-arch.bbclass``
1315=======================
1316
1317The ``kernel-arch`` class sets the ``ARCH`` environment variable for
1318Linux kernel compilation (including modules).
1319
1320.. _ref-classes-kernel-devicetree:
1321
1322``kernel-devicetree.bbclass``
1323=============================
1324
1325The ``kernel-devicetree`` class, which is inherited by the
1326:ref:`kernel <ref-classes-kernel>` class, supports device tree
1327generation.
1328
1329.. _ref-classes-kernel-fitimage:
1330
1331``kernel-fitimage.bbclass``
1332===========================
1333
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001334The ``kernel-fitimage`` class provides support to pack a kernel image,
1335device trees, a U-boot script, a Initramfs bundle and a RAM disk
1336into a single FIT image. In theory, a FIT image can support any number
1337of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001338However, ``kernel-fitimage`` currently only supports
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001339limited usescases: just one kernel image, an optional U-boot script,
1340an optional Initramfs bundle, an optional RAM disk, and any number of
1341device tree.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001342
1343To create a FIT image, it is required that :term:`KERNEL_CLASSES`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001344is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001345is set to "fitImage".
1346
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001347The options for the device tree compiler passed to ``mkimage -D``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001348when creating the FIT image are specified using the
1349:term:`UBOOT_MKIMAGE_DTCOPTS` variable.
1350
1351Only a single kernel can be added to the FIT image created by
1352``kernel-fitimage`` and the kernel image in FIT is mandatory. The
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001353address where the kernel image is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001354specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by
1355:term:`UBOOT_ENTRYPOINT`.
1356
1357Multiple device trees can be added to the FIT image created by
1358``kernel-fitimage`` and the device tree is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001359The address where the device tree is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001360specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001361and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001362
1363Only a single RAM disk can be added to the FIT image created by
1364``kernel-fitimage`` and the RAM disk in FIT is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001365The address where the RAM disk image is to be loaded by U-Boot
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001366is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
1367:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001368:term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE`
1369is set to 0.
1370
1371Only a single Initramfs bundle can be added to the FIT image created by
1372``kernel-fitimage`` and the Initramfs bundle in FIT is optional.
Andrew Geissler595f6302022-01-24 19:11:47 +00001373In case of Initramfs, the kernel is configured to be bundled with the root filesystem
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001374in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin).
Andrew Geissler595f6302022-01-24 19:11:47 +00001375When the kernel is copied to RAM and executed, it unpacks the Initramfs root filesystem.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001376The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE`
1377is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1.
1378The address where the Initramfs bundle is to be loaded by U-boot is specified
1379by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`.
1380
1381Only a single U-boot boot script can be added to the FIT image created by
1382``kernel-fitimage`` and the boot script is optional.
1383The boot script is specified in the ITS file as a text file containing
1384U-boot commands. When using a boot script the user should configure the
1385U-boot ``do_install`` task to copy the script to sysroot.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001386So the script can be included in the FIT image by the ``kernel-fitimage``
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001387class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
1388load the boot script from the FIT image and executes it.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001389
1390The FIT image generated by ``kernel-fitimage`` class is signed when the
1391variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
1392:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
1393appropriately. The default values used for :term:`FIT_HASH_ALG` and
1394:term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05001395"rsa2048" respectively. The keys for signing fitImage can be generated using
1396the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and
1397:term:`UBOOT_SIGN_ENABLE` are set to "1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001398
1399
1400.. _ref-classes-kernel-grub:
1401
1402``kernel-grub.bbclass``
1403=======================
1404
1405The ``kernel-grub`` class updates the boot area and the boot menu with
1406the kernel as the priority boot mechanism while installing a RPM to
1407update the kernel on a deployed target.
1408
1409.. _ref-classes-kernel-module-split:
1410
1411``kernel-module-split.bbclass``
1412===============================
1413
1414The ``kernel-module-split`` class provides common functionality for
1415splitting Linux kernel modules into separate packages.
1416
1417.. _ref-classes-kernel-uboot:
1418
1419``kernel-uboot.bbclass``
1420========================
1421
1422The ``kernel-uboot`` class provides support for building from
1423vmlinux-style kernel sources.
1424
1425.. _ref-classes-kernel-uimage:
1426
1427``kernel-uimage.bbclass``
1428=========================
1429
1430The ``kernel-uimage`` class provides support to pack uImage.
1431
1432.. _ref-classes-kernel-yocto:
1433
1434``kernel-yocto.bbclass``
1435========================
1436
1437The ``kernel-yocto`` class provides common functionality for building
1438from linux-yocto style kernel source repositories.
1439
1440.. _ref-classes-kernelsrc:
1441
1442``kernelsrc.bbclass``
1443=====================
1444
1445The ``kernelsrc`` class sets the Linux kernel source and version.
1446
1447.. _ref-classes-lib_package:
1448
1449``lib_package.bbclass``
1450=======================
1451
1452The ``lib_package`` class supports recipes that build libraries and
1453produce executable binaries, where those binaries should not be
1454installed by default along with the library. Instead, the binaries are
1455added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to
1456make their installation optional.
1457
1458.. _ref-classes-libc*:
1459
1460``libc*.bbclass``
1461=================
1462
1463The ``libc*`` classes support recipes that build packages with ``libc``:
1464
1465- The ``libc-common`` class provides common support for building with
1466 ``libc``.
1467
1468- The ``libc-package`` class supports packaging up ``glibc`` and
1469 ``eglibc``.
1470
1471.. _ref-classes-license:
1472
1473``license.bbclass``
1474===================
1475
1476The ``license`` class provides license manifest creation and license
1477exclusion. This class is enabled by default using the default value for
1478the :term:`INHERIT_DISTRO` variable.
1479
1480.. _ref-classes-linux-kernel-base:
1481
1482``linux-kernel-base.bbclass``
1483=============================
1484
1485The ``linux-kernel-base`` class provides common functionality for
1486recipes that build out of the Linux kernel source tree. These builds
1487goes beyond the kernel itself. For example, the Perf recipe also
1488inherits this class.
1489
1490.. _ref-classes-linuxloader:
1491
1492``linuxloader.bbclass``
1493=======================
1494
1495Provides the function ``linuxloader()``, which gives the value of the
1496dynamic loader/linker provided on the platform. This value is used by a
1497number of other classes.
1498
1499.. _ref-classes-logging:
1500
1501``logging.bbclass``
1502===================
1503
1504The ``logging`` class provides the standard shell functions used to log
1505messages for various BitBake severity levels (i.e. ``bbplain``,
1506``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``).
1507
1508This class is enabled by default since it is inherited by the ``base``
1509class.
1510
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001511.. _ref-classes-metadata_scm:
1512
1513``metadata_scm.bbclass``
1514========================
1515
1516The ``metadata_scm`` class provides functionality for querying the
1517branch and revision of a Source Code Manager (SCM) repository.
1518
1519The :ref:`base <ref-classes-base>` class uses this class to print the
1520revisions of each layer before starting every build. The
1521``metadata_scm`` class is enabled by default because it is inherited by
1522the ``base`` class.
1523
1524.. _ref-classes-migrate_localcount:
1525
1526``migrate_localcount.bbclass``
1527==============================
1528
1529The ``migrate_localcount`` class verifies a recipe's localcount data and
1530increments it appropriately.
1531
1532.. _ref-classes-mime:
1533
1534``mime.bbclass``
1535================
1536
1537The ``mime`` class generates the proper post-install and post-remove
1538(postinst/postrm) scriptlets for packages that install MIME type files.
1539These scriptlets call ``update-mime-database`` to add the MIME types to
1540the shared database.
1541
1542.. _ref-classes-mirrors:
1543
1544``mirrors.bbclass``
1545===================
1546
1547The ``mirrors`` class sets up some standard
1548:term:`MIRRORS` entries for source code mirrors. These
1549mirrors provide a fall-back path in case the upstream source specified
1550in :term:`SRC_URI` within recipes is unavailable.
1551
1552This class is enabled by default since it is inherited by the
1553:ref:`base <ref-classes-base>` class.
1554
1555.. _ref-classes-module:
1556
1557``module.bbclass``
1558==================
1559
1560The ``module`` class provides support for building out-of-tree Linux
1561kernel modules. The class inherits the
1562:ref:`module-base <ref-classes-module-base>` and
1563:ref:`kernel-module-split <ref-classes-kernel-module-split>` classes,
1564and implements the :ref:`ref-tasks-compile` and
1565:ref:`ref-tasks-install` tasks. The class provides
1566everything needed to build and package a kernel module.
1567
1568For general information on out-of-tree Linux kernel modules, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001569":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001570section in the Yocto Project Linux Kernel Development Manual.
1571
1572.. _ref-classes-module-base:
1573
1574``module-base.bbclass``
1575=======================
1576
1577The ``module-base`` class provides the base functionality for building
1578Linux kernel modules. Typically, a recipe that builds software that
1579includes one or more kernel modules and has its own means of building
1580the module inherits this class as opposed to inheriting the
1581:ref:`module <ref-classes-module>` class.
1582
1583.. _ref-classes-multilib*:
1584
1585``multilib*.bbclass``
1586=====================
1587
1588The ``multilib*`` classes provide support for building libraries with
1589different target optimizations or target architectures and installing
1590them side-by-side in the same image.
1591
1592For more information on using the Multilib feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001593":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001594section in the Yocto Project Development Tasks Manual.
1595
1596.. _ref-classes-native:
1597
1598``native.bbclass``
1599==================
1600
1601The ``native`` class provides common functionality for recipes that
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001602build tools to run on the :term:`Build Host` (i.e. tools that use the compiler
1603or other tools from the build host).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001604
1605You can create a recipe that builds tools that run natively on the host
1606a couple different ways:
1607
Andrew Geisslereff27472021-10-29 15:35:00 -05001608- Create a ``myrecipe-native.bb`` recipe that inherits the ``native``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001609 class. If you use this method, you must order the inherit statement
1610 in the recipe after all other inherit statements so that the
1611 ``native`` class is inherited last.
1612
1613 .. note::
1614
1615 When creating a recipe this way, the recipe name must follow this
Andrew Geisslerc926e172021-05-07 16:11:35 -05001616 naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001617
1618 myrecipe-native.bb
1619
1620
1621 Not using this naming convention can lead to subtle problems
1622 caused by existing code that depends on that naming convention.
1623
Andrew Geisslerc926e172021-05-07 16:11:35 -05001624- Create or modify a target recipe that contains the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001625
1626 BBCLASSEXTEND = "native"
1627
1628 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001629 recipe, use ``:class-native`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001630 specify any functionality specific to the respective native or target
1631 case.
1632
1633Although applied differently, the ``native`` class is used with both
1634methods. The advantage of the second method is that you do not need to
1635have two separate recipes (assuming you need both) for native and
1636target. All common parts of the recipe are automatically shared.
1637
1638.. _ref-classes-nativesdk:
1639
1640``nativesdk.bbclass``
1641=====================
1642
1643The ``nativesdk`` class provides common functionality for recipes that
1644wish to build tools to run as part of an SDK (i.e. tools that run on
1645:term:`SDKMACHINE`).
1646
1647You can create a recipe that builds tools that run on the SDK machine a
1648couple different ways:
1649
Andrew Geisslereff27472021-10-29 15:35:00 -05001650- Create a ``nativesdk-myrecipe.bb`` recipe that inherits the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001651 ``nativesdk`` class. If you use this method, you must order the
1652 inherit statement in the recipe after all other inherit statements so
1653 that the ``nativesdk`` class is inherited last.
1654
Andrew Geisslerc926e172021-05-07 16:11:35 -05001655- Create a ``nativesdk`` variant of any recipe by adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001656
1657 BBCLASSEXTEND = "nativesdk"
1658
1659 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001660 recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001661 specify any functionality specific to the respective SDK machine or
1662 target case.
1663
1664.. note::
1665
Andrew Geisslerc926e172021-05-07 16:11:35 -05001666 When creating a recipe, you must follow this naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001667
1668 nativesdk-myrecipe.bb
1669
1670
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001671 Not doing so can lead to subtle problems because there is code that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001672 depends on the naming convention.
1673
1674Although applied differently, the ``nativesdk`` class is used with both
1675methods. The advantage of the second method is that you do not need to
1676have two separate recipes (assuming you need both) for the SDK machine
1677and the target. All common parts of the recipe are automatically shared.
1678
1679.. _ref-classes-nopackages:
1680
1681``nopackages.bbclass``
1682======================
1683
1684Disables packaging tasks for those recipes and classes where packaging
1685is not needed.
1686
1687.. _ref-classes-npm:
1688
1689``npm.bbclass``
1690===============
1691
1692Provides support for building Node.js software fetched using the `node
1693package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
1694
1695.. note::
1696
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001697 Currently, recipes inheriting this class must use the ``npm://``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001698 fetcher to have dependencies fetched and packaged automatically.
1699
1700For information on how to create NPM packages, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001701":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001702section in the Yocto Project Development Tasks Manual.
1703
1704.. _ref-classes-oelint:
1705
1706``oelint.bbclass``
1707==================
1708
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001709The ``oelint`` class is an obsolete lint checking tool available in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001710``meta/classes`` in the :term:`Source Directory`.
1711
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001712There are some classes that could be generally useful in OE-Core but
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001713are never actually used within OE-Core itself. The ``oelint`` class is
1714one such example. However, being aware of this class can reduce the
1715proliferation of different versions of similar classes across multiple
1716layers.
1717
Andrew Geissler5199d832021-09-24 16:47:35 -05001718.. _ref-classes-overlayfs:
1719
1720``overlayfs.bbclass``
1721=======================
1722
Andrew Geissler595f6302022-01-24 19:11:47 +00001723It's often desired in Embedded System design to have a read-only root filesystem.
Andrew Geissler5199d832021-09-24 16:47:35 -05001724But a lot of different applications might want to have read-write access to
1725some parts of a filesystem. It can be especially useful when your update mechanism
Andrew Geissler595f6302022-01-24 19:11:47 +00001726overwrites the whole root filesystem, but you may want your application data to be preserved
Andrew Geissler5199d832021-09-24 16:47:35 -05001727between updates. The :ref:`overlayfs <ref-classes-overlayfs>` class provides a way
1728to achieve that by means of ``overlayfs`` and at the same time keeping the base
Andrew Geissler595f6302022-01-24 19:11:47 +00001729root filesystem read-only.
Andrew Geissler5199d832021-09-24 16:47:35 -05001730
1731To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper
1732layer in your machine configuration. The underlying file system can be anything that
1733is supported by ``overlayfs``. This has to be done in your machine configuration::
1734
1735 OVERLAYFS_MOUNT_POINT[data] = "/data"
1736
1737.. note::
1738
1739 * QA checks fail to catch file existence if you redefine this variable in your recipe!
1740 * Only the existence of the systemd mount unit file is checked, not its contents.
1741 * To get more details on ``overlayfs``, its internals and supported operations, please refer
1742 to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_.
1743
1744The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
1745(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
1746
1747Then you can specify writable directories on a recipe basis (e.g. in my-application.bb)::
1748
1749 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
1750
1751To support several mount points you can use a different variable flag. Assuming we
1752want to have a writable location on the file system, but do not need that the data
Andrew Geissler595f6302022-01-24 19:11:47 +00001753survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs``
1754file system.
Andrew Geissler5199d832021-09-24 16:47:35 -05001755
1756In your machine configuration::
1757
1758 OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
1759
1760and then in your recipe::
1761
1762 OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
1763
Andrew Geissler595f6302022-01-24 19:11:47 +00001764On a practical note, your application recipe might require multiple
1765overlays to be mounted before running to avoid writing to the underlying
1766file system (which can be forbidden in case of read-only file system)
1767To achieve that :ref:`overlayfs <ref-classes-overlayfs>` provides a ``systemd``
1768helper service for mounting overlays. This helper service is named
1769``${PN}-overlays.service`` and can be depended on in your application recipe
1770(named ``application`` in the following example) ``systemd`` unit by adding
1771to the unit the following::
1772
1773 [Unit]
1774 After=application-overlays.service
1775 Requires=application-overlays.service
1776
Andrew Geissler5199d832021-09-24 16:47:35 -05001777.. note::
1778
1779 The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
Andrew Geissler595f6302022-01-24 19:11:47 +00001780 In order to get ``/etc`` in overlayfs, see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>`.
1781
1782.. _ref-classes-overlayfs-etc:
1783
1784``overlayfs-etc.bbclass``
1785=========================
1786
1787In order to have the ``/etc`` directory in overlayfs a special handling at early
1788boot stage is required. The idea is to supply a custom init script that mounts
1789``/etc`` before launching the actual init program, because the latter already
1790requires ``/etc`` to be mounted.
1791
1792Example usage in image recipe::
1793
1794 IMAGE_FEATURES += "overlayfs-etc"
1795
1796.. note::
1797
1798 This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`
1799
1800Your machine configuration should define at least the device, mount point, and file system type
1801you are going to use for ``overlayfs``::
1802
1803 OVERLAYFS_ETC_MOUNT_POINT = "/data"
1804 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
1805 OVERLAYFS_ETC_FSTYPE ?= "ext4"
1806
1807To control more mount options you should consider setting mount options
1808(``defaults`` is used by default)::
1809
1810 OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
1811
1812The class provides two options for ``/sbin/init`` generation:
1813
1814- The default option is to rename the original ``/sbin/init`` to ``/sbin/init.orig``
1815 and place the generated init under original name, i.e. ``/sbin/init``. It has an advantage
1816 that you won't need to change any kernel parameters in order to make it work,
1817 but it poses a restriction that package-management can't be used, because updating
1818 the init manager would remove the generated script.
1819
1820- If you wish to keep original init as is, you can set::
1821
1822 OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
1823
1824 Then the generated init will be named ``/sbin/preinit`` and you would need to extend your
1825 kernel parameters manually in your bootloader configuration.
Andrew Geissler5199d832021-09-24 16:47:35 -05001826
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001827.. _ref-classes-own-mirrors:
1828
1829``own-mirrors.bbclass``
1830=======================
1831
1832The ``own-mirrors`` class makes it easier to set up your own
1833:term:`PREMIRRORS` from which to first fetch source
1834before attempting to fetch it from the upstream specified in
1835:term:`SRC_URI` within each recipe.
1836
1837To use this class, inherit it globally and specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05001838:term:`SOURCE_MIRROR_URL`. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001839
1840 INHERIT += "own-mirrors"
1841 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1842
1843You can specify only a single URL
Andrew Geissler09036742021-06-25 14:25:14 -05001844in :term:`SOURCE_MIRROR_URL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001845
1846.. _ref-classes-package:
1847
1848``package.bbclass``
1849===================
1850
1851The ``package`` class supports generating packages from a build's
1852output. The core generic functionality is in ``package.bbclass``. The
1853code specific to particular package types resides in these
1854package-specific classes:
1855:ref:`package_deb <ref-classes-package_deb>`,
1856:ref:`package_rpm <ref-classes-package_rpm>`,
1857:ref:`package_ipk <ref-classes-package_ipk>`, and
1858:ref:`package_tar <ref-classes-package_tar>`.
1859
1860.. note::
1861
1862 The
1863 package_tar
1864 class is broken and not supported. It is recommended that you do not
1865 use this class.
1866
1867You can control the list of resulting package formats by using the
Andrew Geissler09036742021-06-25 14:25:14 -05001868:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001869configuration file, which is located in the :term:`Build Directory`.
1870When defining the variable, you can
1871specify one or more package types. Since images are generated from
1872packages, a packaging class is needed to enable image generation. The
1873first class listed in this variable is used for image generation.
1874
1875If you take the optional step to set up a repository (package feed) on
1876the development host that can be used by DNF, you can install packages
1877from the feed while you are running the image on the target (i.e.
1878runtime installation of packages). For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001879":ref:`dev-manual/common-tasks:using runtime package management`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001880section in the Yocto Project Development Tasks Manual.
1881
1882The package-specific class you choose can affect build-time performance
1883and has space ramifications. In general, building a package with IPK
1884takes about thirty percent less time as compared to using RPM to build
1885the same or similar package. This comparison takes into account a
1886complete build of the package with all dependencies previously built.
1887The reason for this discrepancy is because the RPM package manager
1888creates and processes more :term:`Metadata` than the IPK package
Andrew Geissler09036742021-06-25 14:25:14 -05001889manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001890"package_ipk" if you are building smaller systems.
1891
1892Before making your package manager decision, however, you should
1893consider some further things about using RPM:
1894
1895- RPM starts to provide more abilities than IPK due to the fact that it
1896 processes more Metadata. For example, this information includes
1897 individual file types, file checksum generation and evaluation on
1898 install, sparse file support, conflict detection and resolution for
1899 Multilib systems, ACID style upgrade, and repackaging abilities for
1900 rollbacks.
1901
1902- For smaller systems, the extra space used for the Berkeley Database
1903 and the amount of metadata when using RPM can affect your ability to
1904 perform on-device upgrades.
1905
1906You can find additional information on the effects of the package class
1907at these two Yocto Project mailing list links:
1908
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001909- :yocto_lists:`/pipermail/poky/2011-May/006362.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001910
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001911- :yocto_lists:`/pipermail/poky/2011-May/006363.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001912
1913.. _ref-classes-package_deb:
1914
1915``package_deb.bbclass``
1916=======================
1917
1918The ``package_deb`` class provides support for creating packages that
1919use the Debian (i.e. ``.deb``) file format. The class ensures the
1920packages are written out in a ``.deb`` file format to the
1921``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory.
1922
1923This class inherits the :ref:`package <ref-classes-package>` class and
1924is enabled through the :term:`PACKAGE_CLASSES`
1925variable in the ``local.conf`` file.
1926
1927.. _ref-classes-package_ipk:
1928
1929``package_ipk.bbclass``
1930=======================
1931
1932The ``package_ipk`` class provides support for creating packages that
1933use the IPK (i.e. ``.ipk``) file format. The class ensures the packages
1934are written out in a ``.ipk`` file format to the
1935``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory.
1936
1937This class inherits the :ref:`package <ref-classes-package>` class and
1938is enabled through the :term:`PACKAGE_CLASSES`
1939variable in the ``local.conf`` file.
1940
1941.. _ref-classes-package_rpm:
1942
1943``package_rpm.bbclass``
1944=======================
1945
1946The ``package_rpm`` class provides support for creating packages that
1947use the RPM (i.e. ``.rpm``) file format. The class ensures the packages
1948are written out in a ``.rpm`` file format to the
1949``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory.
1950
1951This class inherits the :ref:`package <ref-classes-package>` class and
1952is enabled through the :term:`PACKAGE_CLASSES`
1953variable in the ``local.conf`` file.
1954
1955.. _ref-classes-package_tar:
1956
1957``package_tar.bbclass``
1958=======================
1959
1960The ``package_tar`` class provides support for creating tarballs. The
1961class ensures the packages are written out in a tarball format to the
1962``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory.
1963
1964This class inherits the :ref:`package <ref-classes-package>` class and
1965is enabled through the :term:`PACKAGE_CLASSES`
1966variable in the ``local.conf`` file.
1967
1968.. note::
1969
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001970 You cannot specify the ``package_tar`` class first using the
Andrew Geissler09036742021-06-25 14:25:14 -05001971 :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001972 file formats for your image or SDK.
1973
1974.. _ref-classes-packagedata:
1975
1976``packagedata.bbclass``
1977=======================
1978
1979The ``packagedata`` class provides common functionality for reading
1980``pkgdata`` files found in :term:`PKGDATA_DIR`. These
1981files contain information about each output package produced by the
1982OpenEmbedded build system.
1983
1984This class is enabled by default because it is inherited by the
1985:ref:`package <ref-classes-package>` class.
1986
1987.. _ref-classes-packagegroup:
1988
1989``packagegroup.bbclass``
1990========================
1991
1992The ``packagegroup`` class sets default values appropriate for package
Andrew Geissler09036742021-06-25 14:25:14 -05001993group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001994so forth). It is highly recommended that all package group recipes
1995inherit this class.
1996
1997For information on how to use this class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001998":ref:`dev-manual/common-tasks:customizing images using custom package groups`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001999section in the Yocto Project Development Tasks Manual.
2000
2001Previously, this class was called the ``task`` class.
2002
2003.. _ref-classes-patch:
2004
2005``patch.bbclass``
2006=================
2007
2008The ``patch`` class provides all functionality for applying patches
2009during the :ref:`ref-tasks-patch` task.
2010
2011This class is enabled by default because it is inherited by the
2012:ref:`base <ref-classes-base>` class.
2013
2014.. _ref-classes-perlnative:
2015
2016``perlnative.bbclass``
2017======================
2018
2019When inherited by a recipe, the ``perlnative`` class supports using the
2020native version of Perl built by the build system rather than using the
2021version provided by the build host.
2022
2023.. _ref-classes-pixbufcache:
2024
2025``pixbufcache.bbclass``
2026=======================
2027
2028The ``pixbufcache`` class generates the proper post-install and
2029post-remove (postinst/postrm) scriptlets for packages that install
2030pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets
2031call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache.
2032Since the cache files are architecture-specific, ``update_pixbuf_cache``
2033is run using QEMU if the postinst scriptlets need to be run on the build
2034host during image creation.
2035
2036If the pixbuf loaders being installed are in packages other than the
2037recipe's main package, set
2038:term:`PIXBUF_PACKAGES` to specify the packages
2039containing the loaders.
2040
2041.. _ref-classes-pkgconfig:
2042
2043``pkgconfig.bbclass``
2044=====================
2045
2046The ``pkgconfig`` class provides a standard way to get header and
2047library information by using ``pkg-config``. This class aims to smooth
2048integration of ``pkg-config`` into libraries that use it.
2049
2050During staging, BitBake installs ``pkg-config`` data into the
2051``sysroots/`` directory. By making use of sysroot functionality within
2052``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the
2053files.
2054
2055.. _ref-classes-populate-sdk:
2056
2057``populate_sdk.bbclass``
2058========================
2059
2060The ``populate_sdk`` class provides support for SDK-only recipes. For
2061information on advantages gained when building a cross-development
2062toolchain using the :ref:`ref-tasks-populate_sdk`
Andrew Geissler09209ee2020-12-13 08:44:15 -06002063task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002064section in the Yocto Project Application Development and the Extensible
2065Software Development Kit (eSDK) manual.
2066
2067.. _ref-classes-populate-sdk-*:
2068
2069``populate_sdk_*.bbclass``
2070==========================
2071
2072The ``populate_sdk_*`` classes support SDK creation and consist of the
2073following classes:
2074
2075- ``populate_sdk_base``: The base class supporting SDK creation under
2076 all package managers (i.e. DEB, RPM, and opkg).
2077
2078- ``populate_sdk_deb``: Supports creation of the SDK given the Debian
2079 package manager.
2080
2081- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM
2082 package manager.
2083
2084- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg
2085 (IPK format) package manager.
2086
2087- ``populate_sdk_ext``: Supports extensible SDK creation under all
2088 package managers.
2089
2090The ``populate_sdk_base`` class inherits the appropriate
2091``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on
2092:term:`IMAGE_PKGTYPE`.
2093
2094The base class ensures all source and destination directories are
2095established and then populates the SDK. After populating the SDK, the
2096``populate_sdk_base`` class constructs two sysroots:
2097``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which
2098contains the cross-compiler and associated tooling, and the target,
2099which contains a target root filesystem that is configured for the SDK
2100usage. These two images reside in :term:`SDK_OUTPUT`,
Andrew Geisslerc926e172021-05-07 16:11:35 -05002101which consists of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002102
2103 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
2104 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
2105
2106Finally, the base populate SDK class creates the toolchain environment
2107setup script, the tarball of the SDK, and the installer.
2108
2109The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and
2110``populate_sdk_ipk`` classes each support the specific type of SDK.
2111These classes are inherited by and used with the ``populate_sdk_base``
2112class.
2113
2114For more information on the cross-development toolchain generation, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06002115the ":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002116section in the Yocto Project Overview and Concepts Manual. For
2117information on advantages gained when building a cross-development
2118toolchain using the :ref:`ref-tasks-populate_sdk`
2119task, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002120":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002121section in the Yocto Project Application Development and the Extensible
2122Software Development Kit (eSDK) manual.
2123
2124.. _ref-classes-prexport:
2125
2126``prexport.bbclass``
2127====================
2128
2129The ``prexport`` class provides functionality for exporting
2130:term:`PR` values.
2131
2132.. note::
2133
2134 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002135 when using "``bitbake-prserv-tool export``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002136
2137.. _ref-classes-primport:
2138
2139``primport.bbclass``
2140====================
2141
2142The ``primport`` class provides functionality for importing
2143:term:`PR` values.
2144
2145.. note::
2146
2147 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002148 when using "``bitbake-prserv-tool import``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002149
2150.. _ref-classes-prserv:
2151
2152``prserv.bbclass``
2153==================
2154
2155The ``prserv`` class provides functionality for using a :ref:`PR
Andrew Geissler09209ee2020-12-13 08:44:15 -06002156service <dev-manual/common-tasks:working with a pr service>` in order to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002157automatically manage the incrementing of the :term:`PR`
2158variable for each recipe.
2159
2160This class is enabled by default because it is inherited by the
2161:ref:`package <ref-classes-package>` class. However, the OpenEmbedded
2162build system will not enable the functionality of this class unless
2163:term:`PRSERV_HOST` has been set.
2164
2165.. _ref-classes-ptest:
2166
2167``ptest.bbclass``
2168=================
2169
2170The ``ptest`` class provides functionality for packaging and installing
2171runtime tests for recipes that build software that provides these tests.
2172
2173This class is intended to be inherited by individual recipes. However,
2174the class' functionality is largely disabled unless "ptest" appears in
2175:term:`DISTRO_FEATURES`. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002176":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002177section in the Yocto Project Development Tasks Manual for more information
2178on ptest.
2179
2180.. _ref-classes-ptest-gnome:
2181
2182``ptest-gnome.bbclass``
2183=======================
2184
2185Enables package tests (ptests) specifically for GNOME packages, which
2186have tests intended to be executed with ``gnome-desktop-testing``.
2187
2188For information on setting up and running ptests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002189":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002190section in the Yocto Project Development Tasks Manual.
2191
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002192.. _ref-classes-python3-dir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002193
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002194``python3-dir.bbclass``
2195=======================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002196
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002197The ``python3-dir`` class provides the base version, location, and site
2198package location for Python 3.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002199
2200.. _ref-classes-python3native:
2201
2202``python3native.bbclass``
2203=========================
2204
2205The ``python3native`` class supports using the native version of Python
22063 built by the build system rather than support of the version provided
2207by the build host.
2208
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002209.. _ref-classes-python3targetconfig:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002210
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002211``python3targetconfig.bbclass``
2212===============================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002213
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002214The ``python3targetconfig`` class supports using the native version of Python
22153 built by the build system rather than support of the version provided
2216by the build host, except that the configuration for the target machine
2217is accessible (such as correct installation directories). This also adds a
2218dependency on target ``python3``, so should only be used where appropriate
2219in order to avoid unnecessarily lengthening builds.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002220
2221.. _ref-classes-qemu:
2222
2223``qemu.bbclass``
2224================
2225
2226The ``qemu`` class provides functionality for recipes that either need
2227QEMU or test for the existence of QEMU. Typically, this class is used to
2228run programs for a target system on the build host using QEMU's
2229application emulation mode.
2230
2231.. _ref-classes-recipe_sanity:
2232
2233``recipe_sanity.bbclass``
2234=========================
2235
2236The ``recipe_sanity`` class checks for the presence of any host system
2237recipe prerequisites that might affect the build (e.g. variables that
2238are set or software that is present).
2239
2240.. _ref-classes-relocatable:
2241
2242``relocatable.bbclass``
2243=======================
2244
2245The ``relocatable`` class enables relocation of binaries when they are
2246installed into the sysroot.
2247
2248This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class
2249and is used by both the :ref:`cross <ref-classes-cross>` and
2250:ref:`native <ref-classes-native>` classes.
2251
2252.. _ref-classes-remove-libtool:
2253
2254``remove-libtool.bbclass``
2255==========================
2256
2257The ``remove-libtool`` class adds a post function to the
2258:ref:`ref-tasks-install` task to remove all ``.la`` files
2259installed by ``libtool``. Removing these files results in them being
2260absent from both the sysroot and target packages.
2261
2262If a recipe needs the ``.la`` files to be installed, then the recipe can
Andrew Geisslerc926e172021-05-07 16:11:35 -05002263override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002264
2265 REMOVE_LIBTOOL_LA = "0"
2266
2267.. note::
2268
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002269 The ``remove-libtool`` class is not enabled by default.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002270
2271.. _ref-classes-report-error:
2272
2273``report-error.bbclass``
2274========================
2275
2276The ``report-error`` class supports enabling the :ref:`error reporting
Andrew Geissler09209ee2020-12-13 08:44:15 -06002277tool <dev-manual/common-tasks:using the error reporting tool>`",
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002278which allows you to submit build error information to a central database.
2279
2280The class collects debug information for recipe, recipe version, task,
2281machine, distro, build system, target system, host distro, branch,
2282commit, and log. From the information, report files using a JSON format
2283are created and stored in
2284``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2285
2286.. _ref-classes-rm-work:
2287
2288``rm_work.bbclass``
2289===================
2290
2291The ``rm_work`` class supports deletion of temporary workspace, which
2292can ease your hard drive demands during builds.
2293
2294The OpenEmbedded build system can use a substantial amount of disk space
2295during the build process. A portion of this space is the work files
2296under the ``${TMPDIR}/work`` directory for each recipe. Once the build
2297system generates the packages for a recipe, the work files for that
2298recipe are no longer needed. However, by default, the build system
2299preserves these files for inspection and possible debugging purposes. If
2300you would rather have these files deleted to save disk space as the
2301build progresses, you can enable ``rm_work`` by adding the following to
2302your ``local.conf`` file, which is found in the :term:`Build Directory`.
2303::
2304
2305 INHERIT += "rm_work"
2306
2307If you are
2308modifying and building source code out of the work directory for a
2309recipe, enabling ``rm_work`` will potentially result in your changes to
2310the source being lost. To exclude some recipes from having their work
2311directories deleted by ``rm_work``, you can add the names of the recipe
Andrew Geissler09036742021-06-25 14:25:14 -05002312or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which
Andrew Geisslerc926e172021-05-07 16:11:35 -05002313can also be set in your ``local.conf`` file. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002314
2315 RM_WORK_EXCLUDE += "busybox glibc"
2316
2317.. _ref-classes-rootfs*:
2318
2319``rootfs*.bbclass``
2320===================
2321
2322The ``rootfs*`` classes support creating the root filesystem for an
2323image and consist of the following classes:
2324
2325- The ``rootfs-postcommands`` class, which defines filesystem
2326 post-processing functions for image recipes.
2327
2328- The ``rootfs_deb`` class, which supports creation of root filesystems
2329 for images built using ``.deb`` packages.
2330
2331- The ``rootfs_rpm`` class, which supports creation of root filesystems
2332 for images built using ``.rpm`` packages.
2333
2334- The ``rootfs_ipk`` class, which supports creation of root filesystems
2335 for images built using ``.ipk`` packages.
2336
2337- The ``rootfsdebugfiles`` class, which installs additional files found
2338 on the build host directly into the root filesystem.
2339
2340The root filesystem is created from packages using one of the
2341``rootfs*.bbclass`` files as determined by the
2342:term:`PACKAGE_CLASSES` variable.
2343
2344For information on how root filesystem images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002345":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002346section in the Yocto Project Overview and Concepts Manual.
2347
2348.. _ref-classes-sanity:
2349
2350``sanity.bbclass``
2351==================
2352
2353The ``sanity`` class checks to see if prerequisite software is present
2354on the host system so that users can be notified of potential problems
2355that might affect their build. The class also performs basic user
2356configuration checks from the ``local.conf`` configuration file to
2357prevent common mistakes that cause build failures. Distribution policy
2358usually determines whether to include this class.
2359
2360.. _ref-classes-scons:
2361
2362``scons.bbclass``
2363=================
2364
2365The ``scons`` class supports recipes that need to build software that
2366uses the SCons build system. You can use the
2367:term:`EXTRA_OESCONS` variable to specify
2368additional configuration options you want to pass SCons command line.
2369
2370.. _ref-classes-sdl:
2371
2372``sdl.bbclass``
2373===============
2374
2375The ``sdl`` class supports recipes that need to build software that uses
2376the Simple DirectMedia Layer (SDL) library.
2377
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002378.. _ref-classes-setuptools3:
2379
2380``setuptools3.bbclass``
2381=======================
2382
2383The ``setuptools3`` class supports Python version 3.x extensions that
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002384use build systems based on ``setuptools``. If your recipe uses these
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002385build systems, the recipe needs to inherit the ``setuptools3`` class.
2386
Andrew Geissler595f6302022-01-24 19:11:47 +00002387.. _ref-classes-setuptools3-base:
2388
2389``setuptools3-base.bbclass``
2390============================
2391
2392The ``setuptools3-base`` class provides a reusable base for other classes
2393that support building Python version 3.x extensions. If you need
2394functionality that is not provided by the :ref:`setuptools3 <ref-classes-setuptools3>` class, you may
2395want to ``inherit setuptools3-base``. Some recipes do not need the tasks
2396in the :ref:`setuptools3 <ref-classes-setuptools3>` class and inherit this class instead.
2397
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002398.. _ref-classes-sign_rpm:
2399
2400``sign_rpm.bbclass``
2401====================
2402
2403The ``sign_rpm`` class supports generating signed RPM packages.
2404
2405.. _ref-classes-sip:
2406
2407``sip.bbclass``
2408===============
2409
2410The ``sip`` class supports recipes that build or package SIP-based
2411Python bindings.
2412
2413.. _ref-classes-siteconfig:
2414
2415``siteconfig.bbclass``
2416======================
2417
2418The ``siteconfig`` class provides functionality for handling site
2419configuration. The class is used by the
2420:ref:`autotools <ref-classes-autotools>` class to accelerate the
2421:ref:`ref-tasks-configure` task.
2422
2423.. _ref-classes-siteinfo:
2424
2425``siteinfo.bbclass``
2426====================
2427
2428The ``siteinfo`` class provides information about the targets that might
2429be needed by other classes or recipes.
2430
2431As an example, consider Autotools, which can require tests that must
2432execute on the target hardware. Since this is not possible in general
2433when cross compiling, site information is used to provide cached test
2434results so these tests can be skipped over but still make the correct
2435values available. The ``meta/site directory`` contains test results
2436sorted into different categories such as architecture, endianness, and
2437the ``libc`` used. Site information provides a list of files containing
Andrew Geissler09036742021-06-25 14:25:14 -05002438data relevant to the current build in the :term:`CONFIG_SITE` variable that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002439Autotools automatically picks up.
2440
Andrew Geissler09036742021-06-25 14:25:14 -05002441The class also provides variables like :term:`SITEINFO_ENDIANNESS` and
2442:term:`SITEINFO_BITS` that can be used elsewhere in the metadata.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002443
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002444.. _ref-classes-sstate:
2445
2446``sstate.bbclass``
2447==================
2448
2449The ``sstate`` class provides support for Shared State (sstate). By
2450default, the class is enabled through the
2451:term:`INHERIT_DISTRO` variable's default value.
2452
2453For more information on sstate, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002454":ref:`overview-manual/concepts:shared state cache`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002455section in the Yocto Project Overview and Concepts Manual.
2456
2457.. _ref-classes-staging:
2458
2459``staging.bbclass``
2460===================
2461
2462The ``staging`` class installs files into individual recipe work
2463directories for sysroots. The class contains the following key tasks:
2464
2465- The :ref:`ref-tasks-populate_sysroot` task,
2466 which is responsible for handing the files that end up in the recipe
2467 sysroots.
2468
2469- The
2470 :ref:`ref-tasks-prepare_recipe_sysroot`
2471 task (a "partner" task to the ``populate_sysroot`` task), which
2472 installs the files into the individual recipe work directories (i.e.
2473 :term:`WORKDIR`).
2474
2475The code in the ``staging`` class is complex and basically works in two
2476stages:
2477
2478- *Stage One:* The first stage addresses recipes that have files they
2479 want to share with other recipes that have dependencies on the
2480 originating recipe. Normally these dependencies are installed through
2481 the :ref:`ref-tasks-install` task into
2482 ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task
2483 copies a subset of these files into ``${SYSROOT_DESTDIR}``. This
2484 subset of files is controlled by the
2485 :term:`SYSROOT_DIRS`,
2486 :term:`SYSROOT_DIRS_NATIVE`, and
2487 :term:`SYSROOT_DIRS_BLACKLIST`
2488 variables.
2489
2490 .. note::
2491
2492 Additionally, a recipe can customize the files further by
Andrew Geissler09036742021-06-25 14:25:14 -05002493 declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002494 variable.
2495
2496 A shared state (sstate) object is built from these files and the
2497 files are placed into a subdirectory of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002498 :ref:`structure-build-tmp-sysroots-components`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002499 The files are scanned for hardcoded paths to the original
2500 installation location. If the location is found in text files, the
2501 hardcoded locations are replaced by tokens and a list of the files
2502 needing such replacements is created. These adjustments are referred
2503 to as "FIXMEs". The list of files that are scanned for paths is
2504 controlled by the :term:`SSTATE_SCAN_FILES`
2505 variable.
2506
2507- *Stage Two:* The second stage addresses recipes that want to use
2508 something from another recipe and declare a dependency on that recipe
2509 through the :term:`DEPENDS` variable. The recipe will
2510 have a
2511 :ref:`ref-tasks-prepare_recipe_sysroot`
2512 task and when this task executes, it creates the ``recipe-sysroot``
2513 and ``recipe-sysroot-native`` in the recipe work directory (i.e.
2514 :term:`WORKDIR`). The OpenEmbedded build system
2515 creates hard links to copies of the relevant files from
2516 ``sysroots-components`` into the recipe work directory.
2517
2518 .. note::
2519
2520 If hard links are not possible, the build system uses actual
2521 copies.
2522
2523 The build system then addresses any "FIXMEs" to paths as defined from
2524 the list created in the first stage.
2525
2526 Finally, any files in ``${bindir}`` within the sysroot that have the
2527 prefix "``postinst-``" are executed.
2528
2529 .. note::
2530
2531 Although such sysroot post installation scripts are not
2532 recommended for general use, the files do allow some issues such
2533 as user creation and module indexes to be addressed.
2534
Andrew Geissler09036742021-06-25 14:25:14 -05002535 Because recipes can have other dependencies outside of :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002536 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
2537 the sysroot creation function ``extend_recipe_sysroot`` is also added
2538 as a pre-function for those tasks whose dependencies are not through
Andrew Geissler09036742021-06-25 14:25:14 -05002539 :term:`DEPENDS` but operate similarly.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002540
2541 When installing dependencies into the sysroot, the code traverses the
2542 dependency graph and processes dependencies in exactly the same way
2543 as the dependencies would or would not be when installed from sstate.
2544 This processing means, for example, a native tool would have its
2545 native dependencies added but a target library would not have its
2546 dependencies traversed or installed. The same sstate dependency code
2547 is used so that builds should be identical regardless of whether
2548 sstate was used or not. For a closer look, see the
2549 ``setscene_depvalid()`` function in the
2550 :ref:`sstate <ref-classes-sstate>` class.
2551
2552 The build system is careful to maintain manifests of the files it
2553 installs so that any given dependency can be installed as needed. The
2554 sstate hash of the installed item is also stored so that if it
2555 changes, the build system can reinstall it.
2556
2557.. _ref-classes-syslinux:
2558
2559``syslinux.bbclass``
2560====================
2561
2562The ``syslinux`` class provides syslinux-specific functions for building
2563bootable images.
2564
2565The class supports the following variables:
2566
2567- :term:`INITRD`: Indicates list of filesystem images to
2568 concatenate and use as an initial RAM disk (initrd). This variable is
2569 optional.
2570
2571- :term:`ROOTFS`: Indicates a filesystem image to include
2572 as the root filesystem. This variable is optional.
2573
2574- :term:`AUTO_SYSLINUXMENU`: Enables creating
2575 an automatic menu when set to "1".
2576
2577- :term:`LABELS`: Lists targets for automatic
2578 configuration.
2579
2580- :term:`APPEND`: Lists append string overrides for each
2581 label.
2582
2583- :term:`SYSLINUX_OPTS`: Lists additional options
2584 to add to the syslinux file. Semicolon characters separate multiple
2585 options.
2586
2587- :term:`SYSLINUX_SPLASH`: Lists a background
2588 for the VGA boot menu when you are using the boot menu.
2589
2590- :term:`SYSLINUX_DEFAULT_CONSOLE`: Set
2591 to "console=ttyX" to change kernel boot default console.
2592
2593- :term:`SYSLINUX_SERIAL`: Sets an alternate
2594 serial port. Or, turns off serial when the variable is set with an
2595 empty string.
2596
2597- :term:`SYSLINUX_SERIAL_TTY`: Sets an
2598 alternate "console=tty..." kernel boot argument.
2599
2600.. _ref-classes-systemd:
2601
2602``systemd.bbclass``
2603===================
2604
2605The ``systemd`` class provides support for recipes that install systemd
2606unit files.
2607
2608The functionality for this class is disabled unless you have "systemd"
2609in :term:`DISTRO_FEATURES`.
2610
2611Under this class, the recipe or Makefile (i.e. whatever the recipe is
2612calling during the :ref:`ref-tasks-install` task)
2613installs unit files into
2614``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit
2615files being installed go into packages other than the main package, you
2616need to set :term:`SYSTEMD_PACKAGES` in your
2617recipe to identify the packages in which the files will be installed.
2618
2619You should set :term:`SYSTEMD_SERVICE` to the
2620name of the service file. You should also use a package name override to
2621indicate the package to which the value applies. If the value applies to
2622the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
Andrew Geisslerc926e172021-05-07 16:11:35 -05002623is an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002624
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002625 SYSTEMD_SERVICE:${PN} = "connman.service"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002626
2627Services are set up to start on boot automatically
2628unless you have set
2629:term:`SYSTEMD_AUTO_ENABLE` to "disable".
2630
2631For more information on ``systemd``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002632":ref:`dev-manual/common-tasks:selecting an initialization manager`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002633section in the Yocto Project Development Tasks Manual.
2634
2635.. _ref-classes-systemd-boot:
2636
2637``systemd-boot.bbclass``
2638========================
2639
2640The ``systemd-boot`` class provides functions specific to the
2641systemd-boot bootloader for building bootable images. This is an
2642internal class and is not intended to be used directly.
2643
2644.. note::
2645
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002646 The ``systemd-boot`` class is a result from merging the ``gummiboot`` class
2647 used in previous Yocto Project releases with the ``systemd`` project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002648
2649Set the :term:`EFI_PROVIDER` variable to
2650"systemd-boot" to use this class. Doing so creates a standalone EFI
2651bootloader that is not dependent on systemd.
2652
2653For information on more variables used and supported in this class, see
2654the :term:`SYSTEMD_BOOT_CFG`,
2655:term:`SYSTEMD_BOOT_ENTRIES`, and
2656:term:`SYSTEMD_BOOT_TIMEOUT` variables.
2657
2658You can also see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002659documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002660for more information.
2661
2662.. _ref-classes-terminal:
2663
2664``terminal.bbclass``
2665====================
2666
2667The ``terminal`` class provides support for starting a terminal session.
2668The :term:`OE_TERMINAL` variable controls which
2669terminal emulator is used for the session.
2670
2671Other classes use the ``terminal`` class anywhere a separate terminal
2672session needs to be started. For example, the
2673:ref:`patch <ref-classes-patch>` class assuming
2674:term:`PATCHRESOLVE` is set to "user", the
2675:ref:`cml1 <ref-classes-cml1>` class, and the
2676:ref:`devshell <ref-classes-devshell>` class all use the ``terminal``
2677class.
2678
2679.. _ref-classes-testimage*:
2680
2681``testimage*.bbclass``
2682======================
2683
2684The ``testimage*`` classes support running automated tests against
2685images using QEMU and on actual hardware. The classes handle loading the
2686tests and starting the image. To use the classes, you need to perform
2687steps to set up the environment.
2688
2689.. note::
2690
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002691 Best practices include using :term:`IMAGE_CLASSES` rather than
2692 :term:`INHERIT` to inherit the ``testimage`` class for automated image
2693 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002694
2695The tests are commands that run on the target system over ``ssh``. Each
2696test is written in Python and makes use of the ``unittest`` module.
2697
2698The ``testimage.bbclass`` runs tests on an image when called using the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002699following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002700
2701 $ bitbake -c testimage image
2702
2703The ``testimage-auto`` class
2704runs tests on an image after the image is constructed (i.e.
2705:term:`TESTIMAGE_AUTO` must be set to "1").
2706
2707For information on how to enable, run, and create new tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002708":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002709section in the Yocto Project Development Tasks Manual.
2710
2711.. _ref-classes-testsdk:
2712
2713``testsdk.bbclass``
2714===================
2715
2716This class supports running automated tests against software development
2717kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
Andrew Geisslerc926e172021-05-07 16:11:35 -05002718using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002719
2720 $ bitbake -c testsdk image
2721
2722.. note::
2723
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002724 Best practices include using :term:`IMAGE_CLASSES` rather than
2725 :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK
2726 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002727
2728.. _ref-classes-texinfo:
2729
2730``texinfo.bbclass``
2731===================
2732
2733This class should be inherited by recipes whose upstream packages invoke
2734the ``texinfo`` utilities at build-time. Native and cross recipes are
2735made to use the dummy scripts provided by ``texinfo-dummy-native``, for
2736improved performance. Target architecture recipes use the genuine
2737Texinfo utilities. By default, they use the Texinfo utilities on the
2738host system.
2739
2740.. note::
2741
2742 If you want to use the Texinfo recipe shipped with the build system,
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002743 you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo
2744 from :term:`SANITY_REQUIRED_UTILITIES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002745
2746.. _ref-classes-toaster:
2747
2748``toaster.bbclass``
2749===================
2750
2751The ``toaster`` class collects information about packages and images and
2752sends them as events that the BitBake user interface can receive. The
2753class is enabled when the Toaster user interface is running.
2754
2755This class is not intended to be used directly.
2756
2757.. _ref-classes-toolchain-scripts:
2758
2759``toolchain-scripts.bbclass``
2760=============================
2761
2762The ``toolchain-scripts`` class provides the scripts used for setting up
2763the environment for installed SDKs.
2764
2765.. _ref-classes-typecheck:
2766
2767``typecheck.bbclass``
2768=====================
2769
2770The ``typecheck`` class provides support for validating the values of
2771variables set at the configuration level against their defined types.
2772The OpenEmbedded build system allows you to define the type of a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002773variable using the "type" varflag. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002774
2775 IMAGE_FEATURES[type] = "list"
2776
2777.. _ref-classes-uboot-config:
2778
2779``uboot-config.bbclass``
2780========================
2781
2782The ``uboot-config`` class provides support for U-Boot configuration for
Andrew Geisslerc926e172021-05-07 16:11:35 -05002783a machine. Specify the machine in your recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002784
2785 UBOOT_CONFIG ??= <default>
2786 UBOOT_CONFIG[foo] = "config,images"
2787
Andrew Geisslerc926e172021-05-07 16:11:35 -05002788You can also specify the machine using this method::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002789
2790 UBOOT_MACHINE = "config"
2791
2792See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
2793information.
2794
2795.. _ref-classes-uninative:
2796
2797``uninative.bbclass``
2798=====================
2799
2800Attempts to isolate the build system from the host distribution's C
2801library in order to make re-use of native shared state artifacts across
2802different host distributions practical. With this class enabled, a
2803tarball containing a pre-built C library is downloaded at the start of
2804the build. In the Poky reference distribution this is enabled by default
2805through ``meta/conf/distro/include/yocto-uninative.inc``. Other
2806distributions that do not derive from poky can also
2807"``require conf/distro/include/yocto-uninative.inc``" to use this.
2808Alternatively if you prefer, you can build the uninative-tarball recipe
2809yourself, publish the resulting tarball (e.g. via HTTP) and set
2810``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an
2811example, see the ``meta/conf/distro/include/yocto-uninative.inc``.
2812
2813The ``uninative`` class is also used unconditionally by the extensible
2814SDK. When building the extensible SDK, ``uninative-tarball`` is built
2815and the resulting tarball is included within the SDK.
2816
2817.. _ref-classes-update-alternatives:
2818
2819``update-alternatives.bbclass``
2820===============================
2821
2822The ``update-alternatives`` class helps the alternatives system when
2823multiple sources provide the same command. This situation occurs when
2824several programs that have the same or similar function are installed
2825with the same name. For example, the ``ar`` command is available from
2826the ``busybox``, ``binutils`` and ``elfutils`` packages. The
2827``update-alternatives`` class handles renaming the binaries so that
2828multiple packages can be installed without conflicts. The ``ar`` command
2829still works regardless of which packages are installed or subsequently
2830removed. The class renames the conflicting binary in each package and
2831symlinks the highest priority binary during installation or removal of
2832packages.
2833
2834To use this class, you need to define a number of variables:
2835
2836- :term:`ALTERNATIVE`
2837
2838- :term:`ALTERNATIVE_LINK_NAME`
2839
2840- :term:`ALTERNATIVE_TARGET`
2841
2842- :term:`ALTERNATIVE_PRIORITY`
2843
2844These variables list alternative commands needed by a package, provide
2845pathnames for links, default links for targets, and so forth. For
2846details on how to use this class, see the comments in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002847:yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes/update-alternatives.bbclass>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002848file.
2849
2850.. note::
2851
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002852 You can use the ``update-alternatives`` command directly in your recipes.
2853 However, this class simplifies things in most cases.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002854
2855.. _ref-classes-update-rc.d:
2856
2857``update-rc.d.bbclass``
2858=======================
2859
2860The ``update-rc.d`` class uses ``update-rc.d`` to safely install an
2861initialization script on behalf of the package. The OpenEmbedded build
2862system takes care of details such as making sure the script is stopped
2863before a package is removed and started when the package is installed.
2864
Andrew Geissler09036742021-06-25 14:25:14 -05002865Three variables control this class: :term:`INITSCRIPT_PACKAGES`,
2866:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002867for details.
2868
2869.. _ref-classes-useradd:
2870
2871``useradd*.bbclass``
2872====================
2873
2874The ``useradd*`` classes support the addition of users or groups for
2875usage by the package on the target. For example, if you have packages
2876that contain system services that should be run under their own user or
2877group, you can use these classes to enable creation of the user or
Andrew Geissler595f6302022-01-24 19:11:47 +00002878group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb
2879</openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002880recipe in the :term:`Source Directory` provides a simple
2881example that shows how to add three users and groups to two packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002882
2883The ``useradd_base`` class provides basic functionality for user or
2884groups settings.
2885
2886The ``useradd*`` classes support the
2887:term:`USERADD_PACKAGES`,
2888:term:`USERADD_PARAM`,
2889:term:`GROUPADD_PARAM`, and
2890:term:`GROUPMEMS_PARAM` variables.
2891
2892The ``useradd-staticids`` class supports the addition of users or groups
2893that have static user identification (``uid``) and group identification
2894(``gid``) values.
2895
2896The default behavior of the OpenEmbedded build system for assigning
2897``uid`` and ``gid`` values when packages add users and groups during
2898package install time is to add them dynamically. This works fine for
2899programs that do not care what the values of the resulting users and
2900groups become. In these cases, the order of the installation determines
2901the final ``uid`` and ``gid`` values. However, if non-deterministic
2902``uid`` and ``gid`` values are a problem, you can override the default,
2903dynamic application of these values by setting static values. When you
2904set static values, the OpenEmbedded build system looks in
2905:term:`BBPATH` for ``files/passwd`` and ``files/group``
2906files for the values.
2907
2908To use static ``uid`` and ``gid`` values, you need to set some
2909variables. See the :term:`USERADDEXTENSION`,
2910:term:`USERADD_UID_TABLES`,
2911:term:`USERADD_GID_TABLES`, and
2912:term:`USERADD_ERROR_DYNAMIC` variables.
2913You can also see the :ref:`useradd <ref-classes-useradd>` class for
2914additional information.
2915
2916.. note::
2917
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002918 You do not use the ``useradd-staticids`` class directly. You either enable
Andrew Geissler09036742021-06-25 14:25:14 -05002919 or disable the class by setting the :term:`USERADDEXTENSION` variable. If you
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002920 enable or disable the class in a configured system, :term:`TMPDIR` might
Andrew Geissler09036742021-06-25 14:25:14 -05002921 contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002922 directory will correct this condition.
2923
2924.. _ref-classes-utility-tasks:
2925
2926``utility-tasks.bbclass``
2927=========================
2928
2929The ``utility-tasks`` class provides support for various "utility" type
2930tasks that are applicable to all recipes, such as
2931:ref:`ref-tasks-clean` and
2932:ref:`ref-tasks-listtasks`.
2933
2934This class is enabled by default because it is inherited by the
2935:ref:`base <ref-classes-base>` class.
2936
2937.. _ref-classes-utils:
2938
2939``utils.bbclass``
2940=================
2941
2942The ``utils`` class provides some useful Python functions that are
2943typically used in inline Python expressions (e.g. ``${@...}``). One
2944example use is for ``bb.utils.contains()``.
2945
2946This class is enabled by default because it is inherited by the
2947:ref:`base <ref-classes-base>` class.
2948
2949.. _ref-classes-vala:
2950
2951``vala.bbclass``
2952================
2953
2954The ``vala`` class supports recipes that need to build software written
2955using the Vala programming language.
2956
2957.. _ref-classes-waf:
2958
2959``waf.bbclass``
2960===============
2961
2962The ``waf`` class supports recipes that need to build software that uses
2963the Waf build system. You can use the
2964:term:`EXTRA_OECONF` or
2965:term:`PACKAGECONFIG_CONFARGS` variables
2966to specify additional configuration options to be passed on the Waf
2967command line.