blob: 3b33783c588b05442f117de62627f04598ea909d [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
Patrick Williams975a06f2022-10-21 14:42:47 -050016``.bbclass`` and are usually placed in one of a set of subdirectories
17beneath the ``meta*/`` directory found in the :term:`Source Directory`:
18
19 - ``classes-recipe/`` - classes intended to be inherited by recipes
20 individually
21 - ``classes-global/`` - classes intended to be inherited globally
22 - ``classes/`` - classes whose usage context is not clearly defined
23
Andrew Geisslerc9f78652020-09-18 14:11:35 -050024Class files can also be pointed to by
25:term:`BUILDDIR` (e.g. ``build/``) in the same way as
26``.conf`` files in the ``conf`` directory. Class files are searched for
27in :term:`BBPATH` using the same method by which ``.conf``
28files are searched.
29
30This chapter discusses only the most useful and important classes. Other
Patrick Williams975a06f2022-10-21 14:42:47 -050031classes do exist within the ``meta/classes*`` directories in the Source
Andrew Geisslerc9f78652020-09-18 14:11:35 -050032Directory. You can reference the ``.bbclass`` files directly for more
33information.
34
35.. _ref-classes-allarch:
36
37``allarch.bbclass``
38===================
39
Patrick Williams2390b1b2022-11-03 13:47:49 -050040The :ref:`allarch <ref-classes-allarch>` class is inherited by recipes that do not produce
Andrew Geisslerc9f78652020-09-18 14:11:35 -050041architecture-specific output. The class disables functionality that is
42normally needed for recipes that produce executable binaries (such as
43building the cross-compiler and a C library as pre-requisites, and
44splitting out of debug symbols during packaging).
45
46.. note::
47
48 Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes that
49 produce packages that depend on tunings through use of the
50 :term:`RDEPENDS` and
51 :term:`TUNE_PKGARCH` variables, should never be
Patrick Williams2390b1b2022-11-03 13:47:49 -050052 configured for all architectures using :ref:`allarch <ref-classes-allarch>`. This is the case
Andrew Geisslerc9f78652020-09-18 14:11:35 -050053 even if the recipes do not produce architecture-specific output.
54
55 Configuring such recipes for all architectures causes the
Patrick Williams2194f502022-10-16 14:26:09 -050056 :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks to
Andrew Geisslerc9f78652020-09-18 14:11:35 -050057 have different signatures for the machines with different tunings.
58 Additionally, unnecessary rebuilds occur every time an image for a
Andrew Geissler09036742021-06-25 14:25:14 -050059 different :term:`MACHINE` is built even when the recipe never changes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050060
61By default, all recipes inherit the :ref:`base <ref-classes-base>` and
62:ref:`package <ref-classes-package>` classes, which enable
63functionality needed for recipes that produce executable output. If your
64recipe, for example, only produces packages that contain configuration
65files, media files, or scripts (e.g. Python and Perl), then it should
Patrick Williams2390b1b2022-11-03 13:47:49 -050066inherit the :ref:`allarch <ref-classes-allarch>` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050067
68.. _ref-classes-archiver:
69
70``archiver.bbclass``
71====================
72
Patrick Williams2390b1b2022-11-03 13:47:49 -050073The :ref:`archiver <ref-classes-archiver>` class supports releasing source code and other
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074materials with the binaries.
75
Patrick Williams2390b1b2022-11-03 13:47:49 -050076For more details on the source :ref:`archiver <ref-classes-archiver>`, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060077":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050078section in the Yocto Project Development Tasks Manual. You can also see
79the :term:`ARCHIVER_MODE` variable for information
80about the variable flags (varflags) that help control archive creation.
81
82.. _ref-classes-autotools:
83
84``autotools*.bbclass``
85======================
86
Patrick Williams2390b1b2022-11-03 13:47:49 -050087The :ref:`autotools* <ref-classes-autotools>` classes support packages built with the
Patrick Williams03907ee2022-05-01 06:28:52 -050088`GNU Autotools <https://en.wikipedia.org/wiki/GNU_Autotools>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050089
90The ``autoconf``, ``automake``, and ``libtool`` packages bring
91standardization. This class defines a set of tasks (e.g. ``configure``,
92``compile`` and so forth) that work for all Autotooled packages. It
93should usually be enough to define a few standard variables and then
94simply ``inherit autotools``. These classes can also work with software
95that emulates Autotools. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060096":ref:`dev-manual/common-tasks:autotooled package`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -050097in the Yocto Project Development Tasks Manual.
98
Patrick Williams2390b1b2022-11-03 13:47:49 -050099By default, the :ref:`autotools* <ref-classes-autotools>` classes use out-of-tree builds (i.e.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500100``autotools.bbclass`` building with ``B != S``).
101
102If the software being built by a recipe does not support using
103out-of-tree builds, you should have the recipe inherit the
Patrick Williams2390b1b2022-11-03 13:47:49 -0500104:ref:`autotools-brokensep <ref-classes-autotools>` class. The :ref:`autotools-brokensep <ref-classes-autotools>` class behaves
105the same as the :ref:`autotools <ref-classes-autotools>` class but builds with :term:`B`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500106== :term:`S`. This method is useful when out-of-tree build
107support is either not present or is broken.
108
109.. note::
110
111 It is recommended that out-of-tree support be fixed and used if at
112 all possible.
113
114It's useful to have some idea of how the tasks defined by the
Patrick Williams2390b1b2022-11-03 13:47:49 -0500115:ref:`autotools* <ref-classes-autotools>` classes work and what they do behind the scenes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500116
Andrew Geissler615f2f12022-07-15 14:00:58 -0500117- :ref:`ref-tasks-configure` --- regenerates the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500118 configure script (using ``autoreconf``) and then launches it with a
119 standard set of arguments used during cross-compilation. You can pass
Andrew Geissler09036742021-06-25 14:25:14 -0500120 additional parameters to ``configure`` through the :term:`EXTRA_OECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121 or :term:`PACKAGECONFIG_CONFARGS`
122 variables.
123
Andrew Geissler615f2f12022-07-15 14:00:58 -0500124- :ref:`ref-tasks-compile` --- runs ``make`` with
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500125 arguments that specify the compiler and linker. You can pass
Andrew Geissler5f350902021-07-23 13:09:54 -0400126 additional arguments through the :term:`EXTRA_OEMAKE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500127
Andrew Geissler615f2f12022-07-15 14:00:58 -0500128- :ref:`ref-tasks-install` --- runs ``make install`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500129 passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``.
130
131.. _ref-classes-base:
132
133``base.bbclass``
134================
135
Patrick Williams2390b1b2022-11-03 13:47:49 -0500136The :ref:`base <ref-classes-base>` class is special in that every ``.bb`` file implicitly
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500137inherits the class. This class contains definitions for standard basic
138tasks such as fetching, unpacking, configuring (empty by default),
139compiling (runs any ``Makefile`` present), installing (empty by default)
140and packaging (empty by default). These classes are often overridden or
141extended by other classes such as the
142:ref:`autotools <ref-classes-autotools>` class or the
143:ref:`package <ref-classes-package>` class.
144
145The class also contains some commonly used functions such as
146``oe_runmake``, which runs ``make`` with the arguments specified in
147:term:`EXTRA_OEMAKE` variable as well as the
148arguments passed directly to ``oe_runmake``.
149
150.. _ref-classes-bash-completion:
151
152``bash-completion.bbclass``
153===========================
154
155Sets up packaging and dependencies appropriate for recipes that build
156software that includes bash-completion data.
157
158.. _ref-classes-bin-package:
159
160``bin_package.bbclass``
161=======================
162
Patrick Williams2390b1b2022-11-03 13:47:49 -0500163The :ref:`bin_package <ref-classes-bin-package>` class is a helper class for recipes that extract the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500164contents of a binary package (e.g. an RPM) and install those contents
165rather than building the binary from source. The binary package is
166extracted and new packages in the configured output package format are
167created. Extraction and installation of proprietary binaries is a good
168example use for this class.
169
170.. note::
171
172 For RPMs and other packages that do not contain a subdirectory, you
173 should specify an appropriate fetcher parameter to point to the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500174 subdirectory. For example, if BitBake is using the Git fetcher (``git://``),
175 the "subpath" parameter limits the checkout to a specific subpath
176 of the tree. Here is an example where ``${BP}`` is used so that the files
177 are extracted into the subdirectory expected by the default value of
Andrew Geissler09036742021-06-25 14:25:14 -0500178 :term:`S`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179
Andrew Geissler9aee5002022-03-30 16:27:02 +0000180 SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500182 See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for
183 more information on supported BitBake Fetchers.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500184
185.. _ref-classes-binconfig:
186
187``binconfig.bbclass``
188=====================
189
Patrick Williams2390b1b2022-11-03 13:47:49 -0500190The :ref:`binconfig <ref-classes-binconfig>` class helps to correct paths in shell scripts.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500191
192Before ``pkg-config`` had become widespread, libraries shipped shell
193scripts to give information about the libraries and include paths needed
194to build software (usually named ``LIBNAME-config``). This class assists
195any recipe using such scripts.
196
197During staging, the OpenEmbedded build system installs such scripts into
198the ``sysroots/`` directory. Inheriting this class results in all paths
199in these scripts being changed to point into the ``sysroots/`` directory
200so that all builds that use the script use the correct directories for
201the cross compiling layout. See the
202:term:`BINCONFIG_GLOB` variable for more
203information.
204
205.. _ref-classes-binconfig-disabled:
206
207``binconfig-disabled.bbclass``
208==============================
209
210An alternative version of the :ref:`binconfig <ref-classes-binconfig>`
211class, which disables binary configuration scripts by making them return
212an error in favor of using ``pkg-config`` to query the information. The
213scripts to be disabled should be specified using the
214:term:`BINCONFIG` variable within the recipe inheriting
215the class.
216
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217.. _ref-classes-buildhistory:
218
219``buildhistory.bbclass``
220========================
221
Patrick Williams2390b1b2022-11-03 13:47:49 -0500222The :ref:`buildhistory <ref-classes-buildhistory>` class records a history of build output metadata,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223which can be used to detect possible regressions as well as used for
224analysis of the build output. For more information on using Build
225History, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600226":ref:`dev-manual/common-tasks:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500227section in the Yocto Project Development Tasks Manual.
228
229.. _ref-classes-buildstats:
230
231``buildstats.bbclass``
232======================
233
Patrick Williams2390b1b2022-11-03 13:47:49 -0500234The :ref:`buildstats <ref-classes-buildstats>` class records performance statistics about each task
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500235executed during the build (e.g. elapsed time, CPU usage, and I/O usage).
236
237When you use this class, the output goes into the
238:term:`BUILDSTATS_BASE` directory, which defaults
239to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using
240``scripts/pybootchartgui/pybootchartgui.py``, which produces a cascading
241chart of the entire build process and can be useful for highlighting
242bottlenecks.
243
244Collecting build statistics is enabled by default through the
245:term:`USER_CLASSES` variable from your
246``local.conf`` file. Consequently, you do not have to do anything to
247enable the class. However, if you want to disable the class, simply
Patrick Williams2390b1b2022-11-03 13:47:49 -0500248remove ":ref:`buildstats <ref-classes-buildstats>`" from the :term:`USER_CLASSES` list.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500249
250.. _ref-classes-buildstats-summary:
251
252``buildstats-summary.bbclass``
253==============================
254
255When inherited globally, prints statistics at the end of the build on
256sstate re-use. In order to function, this class requires the
257:ref:`buildstats <ref-classes-buildstats>` class be enabled.
258
259.. _ref-classes-ccache:
260
261``ccache.bbclass``
262==================
263
Patrick Williams2390b1b2022-11-03 13:47:49 -0500264The :ref:`ccache <ref-classes-ccache>` class enables the C/C++ Compiler Cache for the build.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500265This class is used to give a minor performance boost during the build.
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000266
267See https://ccache.samba.org/ for information on the C/C++ Compiler
268Cache, and the :oe_git:`ccache.bbclass </openembedded-core/tree/meta/classes/ccache.bbclass>`
269file for details about how to enable this mechanism in your configuration
270file, how to disable it for specific recipes, and how to share ``ccache``
271files between builds.
272
273However, using the class can lead to unexpected side-effects. Thus, using
274this class is not recommended.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500275
276.. _ref-classes-chrpath:
277
278``chrpath.bbclass``
279===================
280
Patrick Williams2390b1b2022-11-03 13:47:49 -0500281The :ref:`chrpath <ref-classes-chrpath>` class is a wrapper around the "chrpath" utility, which
282is used during the build process for :ref:`nativesdk <ref-classes-nativesdk>`, :ref:`cross <ref-classes-cross>`, and
283:ref:`cross-canadian <ref-classes-cross-canadian>` recipes to change ``RPATH`` records within binaries
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500284in order to make them relocatable.
285
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500286.. _ref-classes-cmake:
287
288``cmake.bbclass``
289=================
290
Patrick Williams2390b1b2022-11-03 13:47:49 -0500291The ref:`cmake <ref-classes-cmake>` class allows for recipes that need to build software using
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500292the `CMake <https://cmake.org/overview/>`__ build system. You can use
293the :term:`EXTRA_OECMAKE` variable to specify
294additional configuration options to be passed using the ``cmake``
295command line.
296
297On the occasion that you would be installing custom CMake toolchain
298files supplied by the application being built, you should install them
299to the preferred CMake Module directory: ``${D}${datadir}/cmake/``
300Modules during
301:ref:`ref-tasks-install`.
302
303.. _ref-classes-cml1:
304
305``cml1.bbclass``
306================
307
Patrick Williams2390b1b2022-11-03 13:47:49 -0500308The :ref:`cml1 <ref-classes-cml1>` class provides basic support for the Linux kernel style
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500309build configuration system.
310
311.. _ref-classes-compress_doc:
312
313``compress_doc.bbclass``
314========================
315
316Enables compression for man pages and info pages. This class is intended
317to be inherited globally. The default compression mechanism is gz (gzip)
318but you can select an alternative mechanism by setting the
319:term:`DOC_COMPRESS` variable.
320
321.. _ref-classes-copyleft_compliance:
322
323``copyleft_compliance.bbclass``
324===============================
325
Patrick Williams2390b1b2022-11-03 13:47:49 -0500326The :ref:`copyleft_compliance <ref-classes-copyleft_compliance>` class preserves source code for the purposes
327of license compliance. This class is an alternative to the :ref:`archiver <ref-classes-archiver>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500328class and is still used by some users even though it has been deprecated
329in favor of the :ref:`archiver <ref-classes-archiver>` class.
330
331.. _ref-classes-copyleft_filter:
332
333``copyleft_filter.bbclass``
334===========================
335
336A class used by the :ref:`archiver <ref-classes-archiver>` and
337:ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes
338for filtering licenses. The ``copyleft_filter`` class is an internal
339class and is not intended to be used directly.
340
341.. _ref-classes-core-image:
342
343``core-image.bbclass``
344======================
345
Patrick Williams2390b1b2022-11-03 13:47:49 -0500346The :ref:`core-image <ref-classes-core-image>` class provides common definitions for the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500347``core-image-*`` image recipes, such as support for additional
348:term:`IMAGE_FEATURES`.
349
350.. _ref-classes-cpan:
351
352``cpan*.bbclass``
353=================
354
Patrick Williams2390b1b2022-11-03 13:47:49 -0500355The :ref:`cpan* <ref-classes-cpan>` classes support Perl modules.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500356
357Recipes for Perl modules are simple. These recipes usually only need to
358point to the source's archive and then inherit the proper class file.
359Building is split into two methods depending on which method the module
360authors used.
361
362- Modules that use old ``Makefile.PL``-based build system require
363 ``cpan.bbclass`` in their recipes.
364
365- Modules that use ``Build.PL``-based build system require using
366 ``cpan_build.bbclass`` in their recipes.
367
Patrick Williams2390b1b2022-11-03 13:47:49 -0500368Both build methods inherit the :ref:`cpan-base <ref-classes-cpan>` class for basic Perl
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500369support.
370
Patrick Williams975a06f2022-10-21 14:42:47 -0500371.. _ref-classes-create-spdx:
372
373``create-spdx.bbclass``
374=======================
375
Patrick Williams2390b1b2022-11-03 13:47:49 -0500376The :ref:`create-spdx <ref-classes-create-spdx>` class provides support for automatically creating
Patrick Williams975a06f2022-10-21 14:42:47 -0500377SPDX SBoM documents based upon image and SDK contents.
378
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500379.. _ref-classes-cross:
380
381``cross.bbclass``
382=================
383
Patrick Williams2390b1b2022-11-03 13:47:49 -0500384The :ref:`cross <ref-classes-cross>` class provides support for the recipes that build the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500385cross-compilation tools.
386
387.. _ref-classes-cross-canadian:
388
389``cross-canadian.bbclass``
390==========================
391
Patrick Williams2390b1b2022-11-03 13:47:49 -0500392The :ref:`cross-canadian <ref-classes-cross-canadian>` class provides support for the recipes that build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500393the Canadian Cross-compilation tools for SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600394":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500395section in the Yocto Project Overview and Concepts Manual for more
396discussion on these cross-compilation tools.
397
398.. _ref-classes-crosssdk:
399
400``crosssdk.bbclass``
401====================
402
Patrick Williams2390b1b2022-11-03 13:47:49 -0500403The :ref:`crosssdk <ref-classes-crosssdk>` class provides support for the recipes that build the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500404cross-compilation tools used for building SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600405":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500406section in the Yocto Project Overview and Concepts Manual for more
407discussion on these cross-compilation tools.
408
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500409.. _ref-classes-cve-check:
410
411``cve-check.bbclass``
412=====================
413
Patrick Williams2390b1b2022-11-03 13:47:49 -0500414The :ref:`cve-check <ref-classes-cve-check>` class looks for known CVEs (Common Vulnerabilities
415and Exposures) while building with BitBake. This class is meant to be
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500416inherited globally from a configuration file::
417
418 INHERIT += "cve-check"
419
Patrick Williams2390b1b2022-11-03 13:47:49 -0500420To filter out obsolete CVE database entries which are known not to impact software from Poky and OE-Core,
421add following line to the build configuration file::
422
423 include cve-extra-exclusions.inc
424
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500425You can also look for vulnerabilities in specific packages by passing
Patrick Williams2390b1b2022-11-03 13:47:49 -0500426``-c cve_check`` to BitBake.
427
428After building the software with Bitbake, CVE check output reports are available in ``tmp/deploy/cve``
429and image specific summaries in ``tmp/deploy/images/*.cve`` or ``tmp/deploy/images/*.json`` files.
430
431When building, the CVE checker will emit build time warnings for any detected
432issues which are in the state ``Unpatched``, meaning that CVE issue seems to affect the software component
433and version being compiled and no patches to address the issue are applied. Other states
434for detected CVE issues are: ``Patched`` meaning that a patch to address the issue is already
435applied, and ``Ignored`` meaning that the issue can be ignored.
436
437The ``Patched`` state of a CVE issue is detected from patch files with the format
438``CVE-ID.patch``, e.g. ``CVE-2019-20633.patch``, in the :term:`SRC_URI` and using
439CVE metadata of format ``CVE: CVE-ID`` in the commit message of the patch file.
440
441If the recipe lists the ``CVE-ID`` in :term:`CVE_CHECK_IGNORE` variable, then the CVE state is reported
442as ``Ignored``. Multiple CVEs can be listed separated by spaces. Example::
443
444 CVE_CHECK_IGNORE += "CVE-2020-29509 CVE-2020-29511"
445
446If CVE check reports that a recipe contains false positives or false negatives, these may be
447fixed in recipes by adjusting the CVE product name using :term:`CVE_PRODUCT` and :term:`CVE_VERSION` variables.
448:term:`CVE_PRODUCT` defaults to the plain recipe name :term:`BPN` which can be adjusted to one or more CVE
449database vendor and product pairs using the syntax::
450
451 CVE_PRODUCT = "flex_project:flex"
452
453where ``flex_project`` is the CVE database vendor name and ``flex`` is the product name. Similarly
454if the default recipe version :term:`PV` does not match the version numbers of the software component
455in upstream releases or the CVE database, then the :term:`CVE_VERSION` variable can be used to set the
456CVE database compatible version number, for example::
457
458 CVE_VERSION = "2.39"
459
460Any bugs or missing or incomplete information in the CVE database entries should be fixed in the CVE database
461via the `NVD feedback form <https://nvd.nist.gov/info/contact-form>`__.
462
463Users should note that security is a process, not a product, and thus also CVE checking, analyzing results,
464patching and updating the software should be done as a regular process. The data and assumptions
465required for CVE checker to reliably detect issues are frequently broken in various ways.
466These can only be detected by reviewing the details of the issues and iterating over the generated reports,
467and following what happens in other Linux distributions and in the greater open source community.
468
469You will find some more details in the
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500470":ref:`dev-manual/common-tasks:checking for vulnerabilities`"
471section in the Development Tasks Manual.
472
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473.. _ref-classes-debian:
474
475``debian.bbclass``
476==================
477
Patrick Williams2390b1b2022-11-03 13:47:49 -0500478The :ref:`debian <ref-classes-debian>` class renames output packages so that they follow the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500479Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and
480``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library
481name and version as part of the package name.
482
483If a recipe creates packages for multiple libraries (shared object files
484of ``.so`` type), use the :term:`LEAD_SONAME`
485variable in the recipe to specify the library on which to apply the
486naming scheme.
487
488.. _ref-classes-deploy:
489
490``deploy.bbclass``
491==================
492
Patrick Williams2390b1b2022-11-03 13:47:49 -0500493The :ref:`deploy <ref-classes-deploy>` class handles deploying files to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500494:term:`DEPLOY_DIR_IMAGE` directory. The main
495function of this class is to allow the deploy step to be accelerated by
496shared state. Recipes that inherit this class should define their own
497:ref:`ref-tasks-deploy` function to copy the files to be
498deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
499add the task at the appropriate place, which is usually after
500:ref:`ref-tasks-compile` or
501:ref:`ref-tasks-install`. The class then takes care of
Andrew Geissler09036742021-06-25 14:25:14 -0500502staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503
504.. _ref-classes-devshell:
505
506``devshell.bbclass``
507====================
508
Patrick Williams2390b1b2022-11-03 13:47:49 -0500509The :ref:`devshell <ref-classes-devshell>` class adds the :ref:`ref-tasks-devshell` task. Distribution
Andrew Geissler09209ee2020-12-13 08:44:15 -0600510policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500511section in the Yocto Project Development Tasks Manual for more
Patrick Williams2390b1b2022-11-03 13:47:49 -0500512information about using :ref:`devshell <ref-classes-devshell>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500513
514.. _ref-classes-devupstream:
515
516``devupstream.bbclass``
517=======================
518
Patrick Williams2390b1b2022-11-03 13:47:49 -0500519The :ref:`devupstream <ref-classes-devupstream>` class uses
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500520:term:`BBCLASSEXTEND` to add a variant of the
521recipe that fetches from an alternative URI (e.g. Git) instead of a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500522tarball. Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500523
524 BBCLASSEXTEND = "devupstream:target"
Andrew Geissler9aee5002022-03-30 16:27:02 +0000525 SRC_URI:class-devupstream = "git://git.example.com/example;branch=main"
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500526 SRCREV:class-devupstream = "abcd1234"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500527
528Adding the above statements to your recipe creates a variant that has
529:term:`DEFAULT_PREFERENCE` set to "-1".
530Consequently, you need to select the variant of the recipe to use it.
531Any development-specific adjustments can be done by using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500532``class-devupstream`` override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500533
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500534 DEPENDS:append:class-devupstream = " gperf-native"
535 do_configure:prepend:class-devupstream() {
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500536 touch ${S}/README
537 }
538
539The class
540currently only supports creating a development variant of the target
Patrick Williams2390b1b2022-11-03 13:47:49 -0500541recipe, not :ref:`native <ref-classes-native>` or :ref:`nativesdk <ref-classes-nativesdk>` variants.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500542
Andrew Geissler09036742021-06-25 14:25:14 -0500543The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides
Patrick Williams2390b1b2022-11-03 13:47:49 -0500544support for :ref:`native <ref-classes-native>` and :ref:`nativesdk <ref-classes-nativesdk>` variants. Consequently, this
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500545functionality can be added in a future release.
546
547Support for other version control systems such as Subversion is limited
548due to BitBake's automatic fetch dependencies (e.g.
549``subversion-native``).
550
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500551.. _ref-classes-externalsrc:
552
553``externalsrc.bbclass``
554=======================
555
Patrick Williams2390b1b2022-11-03 13:47:49 -0500556The :ref:`externalsrc <ref-classes-externalsrc>` class supports building software from source code
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500557that is external to the OpenEmbedded build system. Building software
558from an external source tree means that the build system's normal fetch,
559unpack, and patch process is not used.
560
561By default, the OpenEmbedded build system uses the :term:`S`
562and :term:`B` variables to locate unpacked recipe source code
563and to build it, respectively. When your recipe inherits the
Patrick Williams2390b1b2022-11-03 13:47:49 -0500564:ref:`externalsrc <ref-classes-externalsrc>` class, you use the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500565:term:`EXTERNALSRC` and
566:term:`EXTERNALSRC_BUILD` variables to
Andrew Geissler09036742021-06-25 14:25:14 -0500567ultimately define :term:`S` and :term:`B`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568
569By default, this class expects the source code to support recipe builds
570that use the :term:`B` variable to point to the directory in
571which the OpenEmbedded build system places the generated objects built
Andrew Geissler09036742021-06-25 14:25:14 -0500572from the recipes. By default, the :term:`B` directory is set to the
573following, which is separate from the source directory (:term:`S`)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500574
Andrew Geissler5199d832021-09-24 16:47:35 -0500575 ${WORKDIR}/${BPN}-{PV}/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500576
577See these variables for more information:
578:term:`WORKDIR`, :term:`BPN`, and
579:term:`PV`,
580
Patrick Williams2390b1b2022-11-03 13:47:49 -0500581For more information on the :ref:`externalsrc <ref-classes-externalsrc>` class, see the comments in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500582``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
583For information on how to use the
Patrick Williams2390b1b2022-11-03 13:47:49 -0500584:ref:`externalsrc <ref-classes-externalsrc>` class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600585":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500586section in the Yocto Project Development Tasks Manual.
587
588.. _ref-classes-extrausers:
589
590``extrausers.bbclass``
591======================
592
Patrick Williams2390b1b2022-11-03 13:47:49 -0500593The :ref:`extrausers <ref-classes-extrausers>` class allows additional user and group configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500594to be applied at the image level. Inheriting this class either globally
595or from an image recipe allows additional user and group operations to
596be performed using the
597:term:`EXTRA_USERS_PARAMS` variable.
598
599.. note::
600
601 The user and group operations added using the
Andrew Geissler595f6302022-01-24 19:11:47 +0000602 :ref:`extrausers <ref-classes-extrausers>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500603 class are not tied to a specific recipe outside of the recipe for the
604 image. Thus, the operations can be performed across the image as a
605 whole. Use the
Andrew Geissler595f6302022-01-24 19:11:47 +0000606 :ref:`useradd <ref-classes-useradd>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500607 class to add user and group configuration to a specific recipe.
608
Andrew Geisslerc926e172021-05-07 16:11:35 -0500609Here is an example that uses this class in an image recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500610
611 inherit extrausers
612 EXTRA_USERS_PARAMS = "\
613 useradd -p '' tester; \
614 groupadd developers; \
615 userdel nobody; \
616 groupdel -g video; \
617 groupmod -g 1020 developers; \
618 usermod -s /bin/sh tester; \
619 "
620
621Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
Andrew Geissler9aee5002022-03-30 16:27:02 +0000622passwords. First on host, create the (escaped) password hash::
Andrew Geisslereff27472021-10-29 15:35:00 -0500623
Andrew Geissler9aee5002022-03-30 16:27:02 +0000624 printf "%q" $(mkpasswd -m sha256crypt tester01)
Andrew Geisslereff27472021-10-29 15:35:00 -0500625
Andrew Geissler9aee5002022-03-30 16:27:02 +0000626The resulting hash is set to a variable and used in ``useradd`` command parameters::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500627
628 inherit extrausers
Andrew Geisslereff27472021-10-29 15:35:00 -0500629 PASSWD = "\$X\$ABC123\$A-Long-Hash"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500630 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500631 useradd -p '${PASSWD}' tester-jim; \
632 useradd -p '${PASSWD}' tester-sue; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500633 "
634
Andrew Geisslereff27472021-10-29 15:35:00 -0500635Finally, here is an example that sets the root password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500636
637 inherit extrausers
638 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500639 usermod -p '${PASSWD}' root; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500640 "
641
Patrick Williams03907ee2022-05-01 06:28:52 -0500642.. note::
643
644 From a security perspective, hardcoding a default password is not
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500645 generally a good idea or even legal in some jurisdictions. It is
646 recommended that you do not do this if you are building a production
Patrick Williams03907ee2022-05-01 06:28:52 -0500647 image.
648
649
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600650.. _ref-classes-features_check:
651
652``features_check.bbclass``
653=================================
654
Patrick Williams2390b1b2022-11-03 13:47:49 -0500655The :ref:`features_check <ref-classes-features_check>` class allows individual recipes to check
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600656for required and conflicting
657:term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`.
658
659This class provides support for the following variables:
660
661- :term:`REQUIRED_DISTRO_FEATURES`
662- :term:`CONFLICT_DISTRO_FEATURES`
663- :term:`ANY_OF_DISTRO_FEATURES`
664- ``REQUIRED_MACHINE_FEATURES``
665- ``CONFLICT_MACHINE_FEATURES``
666- ``ANY_OF_MACHINE_FEATURES``
667- ``REQUIRED_COMBINED_FEATURES``
668- ``CONFLICT_COMBINED_FEATURES``
669- ``ANY_OF_COMBINED_FEATURES``
670
671If any conditions specified in the recipe using the above
672variables are not met, the recipe will be skipped, and if the
673build system attempts to build the recipe then an error will be
674triggered.
675
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500676.. _ref-classes-fontcache:
677
678``fontcache.bbclass``
679=====================
680
Patrick Williams2390b1b2022-11-03 13:47:49 -0500681The :ref:`fontcache <ref-classes-fontcache>` class generates the proper post-install and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500682post-remove (postinst and postrm) scriptlets for font packages. These
683scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts
684to the font information cache. Since the cache files are
685architecture-specific, ``fc-cache`` runs using QEMU if the postinst
686scriptlets need to be run on the build host during image creation.
687
688If the fonts being installed are in packages other than the main
689package, set :term:`FONT_PACKAGES` to specify the
690packages containing the fonts.
691
692.. _ref-classes-fs-uuid:
693
694``fs-uuid.bbclass``
695===================
696
Patrick Williams2390b1b2022-11-03 13:47:49 -0500697The :ref:`fs-uuid <ref-classes-fs-uuid>` class extracts UUID from
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500698``${``\ :term:`ROOTFS`\ ``}``, which must have been built
Patrick Williams2390b1b2022-11-03 13:47:49 -0500699by the time that this function gets called. The :ref:`fs-uuid <ref-classes-fs-uuid>` class only
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500700works on ``ext`` file systems and depends on ``tune2fs``.
701
702.. _ref-classes-gconf:
703
704``gconf.bbclass``
705=================
706
Patrick Williams2390b1b2022-11-03 13:47:49 -0500707The :ref:`gconf <ref-classes-gconf>` class provides common functionality for recipes that need
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500708to install GConf schemas. The schemas will be put into a separate
709package (``${``\ :term:`PN`\ ``}-gconf``) that is created
710automatically when this class is inherited. This package uses the
711appropriate post-install and post-remove (postinst/postrm) scriptlets to
712register and unregister the schemas in the target image.
713
714.. _ref-classes-gettext:
715
716``gettext.bbclass``
717===================
718
Patrick Williams2390b1b2022-11-03 13:47:49 -0500719The :ref:`gettext <ref-classes-gettext>` class provides support for building software that uses
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500720the GNU ``gettext`` internationalization and localization system. All
721recipes building software that use ``gettext`` should inherit this
722class.
723
Patrick Williams975a06f2022-10-21 14:42:47 -0500724.. _ref-classes-github-releases:
725
726``github-releases``
727===================
728
Patrick Williams2390b1b2022-11-03 13:47:49 -0500729For recipes that fetch release tarballs from github, the :ref:`github-releases <ref-classes-github-releases>`
Patrick Williams975a06f2022-10-21 14:42:47 -0500730class sets up a standard way for checking available upstream versions
731(to support ``devtool upgrade`` and the Automated Upgrade Helper (AUH)).
732
Patrick Williams2390b1b2022-11-03 13:47:49 -0500733To use it, add ":ref:`github-releases <ref-classes-github-releases>`" to the inherit line in the recipe,
Patrick Williams975a06f2022-10-21 14:42:47 -0500734and if the default value of :term:`GITHUB_BASE_URI` is not suitable,
735then set your own value in the recipe. You should then use ``${GITHUB_BASE_URI}``
736in the value you set for :term:`SRC_URI` within the recipe.
737
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500738.. _ref-classes-gnomebase:
739
740``gnomebase.bbclass``
741=====================
742
Patrick Williams2390b1b2022-11-03 13:47:49 -0500743The :ref:`gnomebase <ref-classes-gnomebase>` class is the base class for recipes that build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500744software from the GNOME stack. This class sets
745:term:`SRC_URI` to download the source from the GNOME
746mirrors as well as extending :term:`FILES` with the typical
747GNOME installation paths.
748
749.. _ref-classes-gobject-introspection:
750
751``gobject-introspection.bbclass``
752=================================
753
754Provides support for recipes building software that supports GObject
755introspection. This functionality is only enabled if the
756"gobject-introspection-data" feature is in
757:term:`DISTRO_FEATURES` as well as
758"qemu-usermode" being in
759:term:`MACHINE_FEATURES`.
760
761.. note::
762
763 This functionality is backfilled by default and, if not applicable,
Andrew Geissler09036742021-06-25 14:25:14 -0500764 should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
765 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500766
767.. _ref-classes-grub-efi:
768
769``grub-efi.bbclass``
770====================
771
Patrick Williams2390b1b2022-11-03 13:47:49 -0500772The :ref:`grub-efi <ref-classes-grub-efi>` class provides ``grub-efi``-specific functions for
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500773building bootable images.
774
775This class supports several variables:
776
777- :term:`INITRD`: Indicates list of filesystem images to
778 concatenate and use as an initial RAM disk (initrd) (optional).
779
780- :term:`ROOTFS`: Indicates a filesystem image to include
781 as the root filesystem (optional).
782
783- :term:`GRUB_GFXSERIAL`: Set this to "1" to have
784 graphics and serial in the boot menu.
785
786- :term:`LABELS`: A list of targets for the automatic
787 configuration.
788
789- :term:`APPEND`: An override list of append strings for
790 each ``LABEL``.
791
792- :term:`GRUB_OPTS`: Additional options to add to the
793 configuration (optional). Options are delimited using semi-colon
794 characters (``;``).
795
796- :term:`GRUB_TIMEOUT`: Timeout before executing
797 the default ``LABEL`` (optional).
798
799.. _ref-classes-gsettings:
800
801``gsettings.bbclass``
802=====================
803
Patrick Williams2390b1b2022-11-03 13:47:49 -0500804The :ref:`gsettings <ref-classes-gsettings>` class provides common functionality for recipes that
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500805need to install GSettings (glib) schemas. The schemas are assumed to be
806part of the main package. Appropriate post-install and post-remove
807(postinst/postrm) scriptlets are added to register and unregister the
808schemas in the target image.
809
810.. _ref-classes-gtk-doc:
811
812``gtk-doc.bbclass``
813===================
814
Patrick Williams2390b1b2022-11-03 13:47:49 -0500815The :ref:`gtk-doc <ref-classes-gtk-doc>` class is a helper class to pull in the appropriate
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500816``gtk-doc`` dependencies and disable ``gtk-doc``.
817
818.. _ref-classes-gtk-icon-cache:
819
820``gtk-icon-cache.bbclass``
821==========================
822
Patrick Williams2390b1b2022-11-03 13:47:49 -0500823The :ref:`gtk-icon-cache <ref-classes-gtk-icon-cache>` class generates the proper post-install and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500824post-remove (postinst/postrm) scriptlets for packages that use GTK+ and
825install icons. These scriptlets call ``gtk-update-icon-cache`` to add
826the fonts to GTK+'s icon cache. Since the cache files are
827architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if
828the postinst scriptlets need to be run on the build host during image
829creation.
830
831.. _ref-classes-gtk-immodules-cache:
832
833``gtk-immodules-cache.bbclass``
834===============================
835
Patrick Williams2390b1b2022-11-03 13:47:49 -0500836The :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class generates the proper post-install and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500837post-remove (postinst/postrm) scriptlets for packages that install GTK+
838input method modules for virtual keyboards. These scriptlets call
839``gtk-update-icon-cache`` to add the input method modules to the cache.
840Since the cache files are architecture-specific,
841``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets
842need to be run on the build host during image creation.
843
844If the input method modules being installed are in packages other than
845the main package, set
846:term:`GTKIMMODULES_PACKAGES` to specify
847the packages containing the modules.
848
849.. _ref-classes-gzipnative:
850
851``gzipnative.bbclass``
852======================
853
Patrick Williams2390b1b2022-11-03 13:47:49 -0500854The :ref:`gzipnative <ref-classes-gzipnative>` class enables the use of different native versions of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500855``gzip`` and ``pigz`` rather than the versions of these tools from the
856build host.
857
858.. _ref-classes-icecc:
859
860``icecc.bbclass``
861=================
862
Patrick Williams2390b1b2022-11-03 13:47:49 -0500863The :ref:`icecc <ref-classes-icecc>` class supports
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500864`Icecream <https://github.com/icecc/icecream>`__, which facilitates
865taking compile jobs and distributing them among remote machines.
866
867The class stages directories with symlinks from ``gcc`` and ``g++`` to
868``icecc``, for both native and cross compilers. Depending on each
869configure or compile, the OpenEmbedded build system adds the directories
870at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500871``ICECC_CC`` variables, which are the paths to the ``g++`` and ``gcc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500872compilers, respectively.
873
874For the cross compiler, the class creates a ``tar.gz`` file that
875contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which
876is the version of the cross-compiler used in the cross-development
877toolchain, accordingly.
878
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500879The class handles all three different compile stages (i.e native,
880cross-kernel and target) and creates the necessary environment
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500881``tar.gz`` file to be used by the remote machines. The class also
882supports SDK generation.
883
884If :term:`ICECC_PATH` is not set in your
885``local.conf`` file, then the class tries to locate the ``icecc`` binary
886using ``which``. If :term:`ICECC_ENV_EXEC` is set
887in your ``local.conf`` file, the variable should point to the
888``icecc-create-env`` script provided by the user. If you do not point to
889a user-provided script, the build system uses the default script
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500890provided by the recipe :oe_git:`icecc-create-env_0.1.bb
891</openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500892
893.. note::
894
895 This script is a modified version and not the one that comes with
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500896 ``icecream``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500897
898If you do not want the Icecream distributed compile support to apply to
Andrew Geissler595f6302022-01-24 19:11:47 +0000899specific recipes or classes, you can ask them to be ignored by Icecream
900by listing the recipes and classes using the
Andrew Geissler9aee5002022-03-30 16:27:02 +0000901:term:`ICECC_RECIPE_DISABLE` and
902:term:`ICECC_CLASS_DISABLE` variables,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500903respectively, in your ``local.conf`` file. Doing so causes the
904OpenEmbedded build system to handle these compilations locally.
905
906Additionally, you can list recipes using the
Andrew Geissler9aee5002022-03-30 16:27:02 +0000907:term:`ICECC_RECIPE_ENABLE` variable in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500908your ``local.conf`` file to force ``icecc`` to be enabled for recipes
909using an empty :term:`PARALLEL_MAKE` variable.
910
Patrick Williams2390b1b2022-11-03 13:47:49 -0500911Inheriting the :ref:`icecc <ref-classes-icecc>` class changes all sstate signatures.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500912Consequently, if a development team has a dedicated build system that
913populates :term:`SSTATE_MIRRORS` and they want to
Andrew Geissler09036742021-06-25 14:25:14 -0500914reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
Patrick Williams2390b1b2022-11-03 13:47:49 -0500915system need to either inherit the :ref:`icecc <ref-classes-icecc>` class or nobody should.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500916
Patrick Williams2390b1b2022-11-03 13:47:49 -0500917At the distribution level, you can inherit the :ref:`icecc <ref-classes-icecc>` class to be
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500918sure that all builders start with the same sstate signatures. After
919inheriting the class, you can then disable the feature by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500920:term:`ICECC_DISABLED` variable to "1" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500921
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500922 INHERIT_DISTRO:append = " icecc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500923 ICECC_DISABLED ??= "1"
924
925This practice
926makes sure everyone is using the same signatures but also requires
927individuals that do want to use Icecream to enable the feature
Andrew Geisslerc926e172021-05-07 16:11:35 -0500928individually as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500929
930 ICECC_DISABLED = ""
931
932.. _ref-classes-image:
933
934``image.bbclass``
935=================
936
Patrick Williams2390b1b2022-11-03 13:47:49 -0500937The :ref:`image <ref-classes-image>` class helps support creating images in different formats.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500938First, the root filesystem is created from packages using one of the
939``rootfs*.bbclass`` files (depending on the package format used) and
940then one or more image files are created.
941
Andrew Geissler09036742021-06-25 14:25:14 -0500942- The :term:`IMAGE_FSTYPES` variable controls the types of images to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500943 generate.
944
Andrew Geissler09036742021-06-25 14:25:14 -0500945- The :term:`IMAGE_INSTALL` variable controls the list of packages to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500946 install into the image.
947
948For information on customizing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600949":ref:`dev-manual/common-tasks:customizing images`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500950in the Yocto Project Development Tasks Manual. For information on how
951images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600952":ref:`overview-manual/concepts:images`" section in the
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600953Yocto Project Overview and Concepts Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500954
955.. _ref-classes-image-buildinfo:
956
957``image-buildinfo.bbclass``
958===========================
959
Patrick Williams2390b1b2022-11-03 13:47:49 -0500960The :ref:`image-buildinfo <ref-classes-image-buildinfo>` class writes a plain text file containing
Patrick Williams975a06f2022-10-21 14:42:47 -0500961build information to the target filesystem at ``${sysconfdir}/buildinfo``
962by default (as specified by :term:`IMAGE_BUILDINFO_FILE`.
963This can be useful for manually determining the origin of any given
964image. It writes out two sections:
965
9661. `Build Configuration`: a list of variables and their values (specified
967 by :term:`IMAGE_BUILDINFO_VARS`, which defaults to :term:`DISTRO` and
968 :term:`DISTRO_VERSION`)
969
9702. `Layer Revisions`: the revisions of all of the layers used in the
971 build.
972
973Additionally, when building an SDK it will write the same contents
974to ``/buildinfo`` by default (as specified by
975:term:`SDK_BUILDINFO_FILE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500976
977.. _ref-classes-image_types:
978
979``image_types.bbclass``
980=======================
981
Patrick Williams2390b1b2022-11-03 13:47:49 -0500982The :ref:`image_types <ref-classes-image_types>` class defines all of the standard image output types
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500983that you can enable through the
984:term:`IMAGE_FSTYPES` variable. You can use this
985class as a reference on how to add support for custom image output
986types.
987
988By default, the :ref:`image <ref-classes-image>` class automatically
Patrick Williams2390b1b2022-11-03 13:47:49 -0500989enables the :ref:`image_types <ref-classes-image_types>` class. The :ref:`image <ref-classes-image>` class uses the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500990``IMGCLASSES`` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500991
992 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
993 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
994 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
995 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
996 IMGCLASSES += "image_types_wic"
997 IMGCLASSES += "rootfs-postcommands"
998 IMGCLASSES += "image-postinst-intercepts"
999 inherit ${IMGCLASSES}
1000
Patrick Williams2390b1b2022-11-03 13:47:49 -05001001The :ref:`image_types <ref-classes-image_types>` class also handles conversion and compression of images.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001002
1003.. note::
1004
1005 To build a VMware VMDK image, you need to add "wic.vmdk" to
Andrew Geissler09036742021-06-25 14:25:14 -05001006 :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001007 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001008
1009.. _ref-classes-image-live:
1010
1011``image-live.bbclass``
1012======================
1013
1014This class controls building "live" (i.e. HDDIMG and ISO) images. Live
1015images contain syslinux for legacy booting, as well as the bootloader
1016specified by :term:`EFI_PROVIDER` if
1017:term:`MACHINE_FEATURES` contains "efi".
1018
1019Normally, you do not use this class directly. Instead, you add "live" to
1020:term:`IMAGE_FSTYPES`.
1021
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001022.. _ref-classes-insane:
1023
1024``insane.bbclass``
1025==================
1026
Patrick Williams2390b1b2022-11-03 13:47:49 -05001027The :ref:`insane <ref-classes-insane>` class adds a step to the package generation process so
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001028that output quality assurance checks are generated by the OpenEmbedded
1029build system. A range of checks are performed that check the build's
1030output for common problems that show up during runtime. Distribution
1031policy usually dictates whether to include this class.
1032
1033You can configure the sanity checks so that specific test failures
1034either raise a warning or an error message. Typically, failures for new
1035tests generate a warning. Subsequent failures for the same test would
1036then generate an error message once the metadata is in a known and good
Andrew Geissler09209ee2020-12-13 08:44:15 -06001037condition. See the ":doc:`/ref-manual/qa-checks`" Chapter for a list of all the warning
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001038and error messages you might encounter using a default configuration.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001039
1040Use the :term:`WARN_QA` and
1041:term:`ERROR_QA` variables to control the behavior of
1042these checks at the global level (i.e. in your custom distro
1043configuration). However, to skip one or more checks in recipes, you
1044should use :term:`INSANE_SKIP`. For example, to skip
1045the check for symbolic link ``.so`` files in the main package of a
1046recipe, add the following to the recipe. You need to realize that the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001047package name override, in this example ``${PN}``, must be used::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001048
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001049 INSANE_SKIP:${PN} += "dev-so"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001050
1051Please keep in mind that the QA checks
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001052are meant to detect real or potential problems in the packaged
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001053output. So exercise caution when disabling these checks.
1054
Andrew Geissler09036742021-06-25 14:25:14 -05001055Here are the tests you can list with the :term:`WARN_QA` and
Andrew Geissler5f350902021-07-23 13:09:54 -04001056:term:`ERROR_QA` variables:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001057
1058- ``already-stripped:`` Checks that produced binaries have not
1059 already been stripped prior to the build system extracting debug
1060 symbols. It is common for upstream software projects to default to
1061 stripping debug symbols for output binaries. In order for debugging
1062 to work on the target using ``-dbg`` packages, this stripping must be
1063 disabled.
1064
1065- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit
1066 size, and endianness of any binaries to ensure they match the target
1067 architecture. This test fails if any binaries do not match the type
1068 since there would be an incompatibility. The test could indicate that
1069 the wrong compiler or compiler options have been used. Sometimes
1070 software, like bootloaders, might need to bypass this check.
1071
1072- ``buildpaths:`` Checks for paths to locations on the build host
Patrick Williams975a06f2022-10-21 14:42:47 -05001073 inside the output files. Not only can these leak information about
1074 the build environment, they also hinder binary reproducibility.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001075
1076- ``build-deps:`` Determines if a build-time dependency that is
1077 specified through :term:`DEPENDS`, explicit
1078 :term:`RDEPENDS`, or task-level dependencies exists
1079 to match any runtime dependency. This determination is particularly
1080 useful to discover where runtime dependencies are detected and added
1081 during packaging. If no explicit dependency has been specified within
1082 the metadata, at the packaging stage it is too late to ensure that
1083 the dependency is built, and thus you can end up with an error when
1084 the package is installed into the image during the
1085 :ref:`ref-tasks-rootfs` task because the auto-detected
1086 dependency was not satisfied. An example of this would be where the
1087 :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically
1088 adds a dependency on the ``initscripts-functions`` package to
1089 packages that install an initscript that refers to
1090 ``/etc/init.d/functions``. The recipe should really have an explicit
Andrew Geissler5f350902021-07-23 13:09:54 -04001091 :term:`RDEPENDS` for the package in question on ``initscripts-functions``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001092 so that the OpenEmbedded build system is able to ensure that the
1093 ``initscripts`` recipe is actually built and thus the
1094 ``initscripts-functions`` package is made available.
1095
1096- ``compile-host-path:`` Checks the
1097 :ref:`ref-tasks-compile` log for indications that
1098 paths to locations on the build host were used. Using such paths
1099 might result in host contamination of the build output.
1100
1101- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
1102 do not depend on ``-dbg`` packages, which would cause a packaging
1103 bug.
1104
1105- ``debug-files:`` Checks for ``.debug`` directories in anything but
1106 the ``-dbg`` package. The debug files should all be in the ``-dbg``
1107 package. Thus, anything packaged elsewhere is incorrect packaging.
1108
1109- ``dep-cmp:`` Checks for invalid version comparison statements in
1110 runtime dependency relationships between packages (i.e. in
1111 :term:`RDEPENDS`,
1112 :term:`RRECOMMENDS`,
1113 :term:`RSUGGESTS`,
1114 :term:`RPROVIDES`,
1115 :term:`RREPLACES`, and
1116 :term:`RCONFLICTS` variable values). Any invalid
1117 comparisons might trigger failures or undesirable behavior when
1118 passed to the package manager.
1119
1120- ``desktop:`` Runs the ``desktop-file-validate`` program against any
1121 ``.desktop`` files to validate their contents against the
1122 specification for ``.desktop`` files.
1123
1124- ``dev-deps:`` Checks that all packages except ``-dev`` or
1125 ``-staticdev`` packages do not depend on ``-dev`` packages, which
1126 would be a packaging bug.
1127
1128- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
1129 ``-dev`` package and not in any of the other packages. In general,
1130 these symlinks are only useful for development purposes. Thus, the
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001131 ``-dev`` package is the correct location for them. In very rare
1132 cases, such as dynamically loaded modules, these symlinks
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001133 are needed instead in the main package.
1134
Patrick Williams03907ee2022-05-01 06:28:52 -05001135- ``empty-dirs:`` Checks that packages are not installing files to
1136 directories that are normally expected to be empty (such as ``/tmp``)
1137 The list of directories that are checked is specified by the
1138 :term:`QA_EMPTY_DIRS` variable.
1139
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001140- ``file-rdeps:`` Checks that file-level dependencies identified by
1141 the OpenEmbedded build system at packaging time are satisfied. For
1142 example, a shell script might start with the line ``#!/bin/bash``.
1143 This line would translate to a file dependency on ``/bin/bash``. Of
1144 the three package managers that the OpenEmbedded build system
1145 supports, only RPM directly handles file-level dependencies,
1146 resolving them automatically to packages providing the files.
1147 However, the lack of that functionality in the other two package
1148 managers does not mean the dependencies do not still need resolving.
1149 This QA check attempts to ensure that explicitly declared
1150 :term:`RDEPENDS` exist to handle any file-level
1151 dependency detected in packaged files.
1152
1153- ``files-invalid:`` Checks for :term:`FILES` variable
1154 values that contain "//", which is invalid.
1155
1156- ``host-user-contaminated:`` Checks that no package produced by the
1157 recipe contains any files outside of ``/home`` with a user or group
1158 ID that matches the user running BitBake. A match usually indicates
1159 that the files are being installed with an incorrect UID/GID, since
1160 target IDs are independent from host IDs. For additional information,
1161 see the section describing the
1162 :ref:`ref-tasks-install` task.
1163
1164- ``incompatible-license:`` Report when packages are excluded from
1165 being created due to being marked with a license that is in
1166 :term:`INCOMPATIBLE_LICENSE`.
1167
1168- ``install-host-path:`` Checks the
1169 :ref:`ref-tasks-install` log for indications that
1170 paths to locations on the build host were used. Using such paths
1171 might result in host contamination of the build output.
1172
1173- ``installed-vs-shipped:`` Reports when files have been installed
Patrick Williams2194f502022-10-16 14:26:09 -05001174 within :ref:`ref-tasks-install` but have not been included in any package by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001175 way of the :term:`FILES` variable. Files that do not
1176 appear in any package cannot be present in an image later on in the
1177 build process. Ideally, all installed files should be packaged or not
1178 installed at all. These files can be deleted at the end of
Patrick Williams2194f502022-10-16 14:26:09 -05001179 :ref:`ref-tasks-install` if the files are not needed in any package.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001180
1181- ``invalid-chars:`` Checks that the recipe metadata variables
1182 :term:`DESCRIPTION`,
1183 :term:`SUMMARY`, :term:`LICENSE`, and
1184 :term:`SECTION` do not contain non-UTF-8 characters.
1185 Some package managers do not support such characters.
1186
1187- ``invalid-packageconfig:`` Checks that no undefined features are
1188 being added to :term:`PACKAGECONFIG`. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05001189 example, any name "foo" for which the following form does not exist::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001190
1191 PACKAGECONFIG[foo] = "..."
1192
Andrew Geissler09036742021-06-25 14:25:14 -05001193- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001194 file containing these paths is incorrect since ``libtool`` adds the
1195 correct sysroot prefix when using the files automatically itself.
1196
1197- ``ldflags:`` Ensures that the binaries were linked with the
1198 :term:`LDFLAGS` options provided by the build system.
Andrew Geissler09036742021-06-25 14:25:14 -05001199 If this test fails, check that the :term:`LDFLAGS` variable is being
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001200 passed to the linker command.
1201
1202- ``libdir:`` Checks for libraries being installed into incorrect
1203 (possibly hardcoded) installation paths. For example, this test will
1204 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
1205 "lib32". Another example is when recipes install
1206 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
1207
1208- ``libexec:`` Checks if a package contains files in
1209 ``/usr/libexec``. This check is not performed if the ``libexecdir``
1210 variable has been set explicitly to ``/usr/libexec``.
1211
1212- ``packages-list:`` Checks for the same package being listed
1213 multiple times through the :term:`PACKAGES` variable
1214 value. Installing the package in this manner can cause errors during
1215 packaging.
1216
1217- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
1218 invalid format.
1219
1220- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
1221 invalid format.
1222
1223- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
1224 'link' where the specified target already exists.
1225
1226- ``perms:`` Currently, this check is unused but reserved.
1227
1228- ``pkgconfig:`` Checks ``.pc`` files for any
1229 :term:`TMPDIR`/:term:`WORKDIR` paths.
1230 Any ``.pc`` file containing these paths is incorrect since
1231 ``pkg-config`` itself adds the correct sysroot prefix when the files
1232 are accessed.
1233
1234- ``pkgname:`` Checks that all packages in
1235 :term:`PACKAGES` have names that do not contain
1236 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1237 -).
1238
Andrew Geissler09036742021-06-25 14:25:14 -05001239- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001240 undefined during :ref:`ref-tasks-package`.
1241
1242- ``pkgvarcheck:`` Checks through the variables
1243 :term:`RDEPENDS`,
1244 :term:`RRECOMMENDS`,
1245 :term:`RSUGGESTS`,
1246 :term:`RCONFLICTS`,
1247 :term:`RPROVIDES`,
1248 :term:`RREPLACES`, :term:`FILES`,
1249 :term:`ALLOW_EMPTY`, ``pkg_preinst``,
1250 ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if
1251 there are variable sets that are not package-specific. Using these
1252 variables without a package suffix is bad practice, and might
1253 unnecessarily complicate dependencies of other packages within the
1254 same recipe or have other unintended consequences.
1255
1256- ``pn-overrides:`` Checks that a recipe does not have a name
1257 (:term:`PN`) value that appears in
1258 :term:`OVERRIDES`. If a recipe is named such that
Andrew Geissler09036742021-06-25 14:25:14 -05001259 its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
1260 :term:`PN` happens to be the same as :term:`MACHINE` or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001261 :term:`DISTRO`), it can have unexpected consequences.
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001262 For example, assignments such as ``FILES:${PN} = "xyz"`` effectively
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001263 turn into ``FILES = "xyz"``.
1264
1265- ``rpaths:`` Checks for rpaths in the binaries that contain build
Andrew Geissler5f350902021-07-23 13:09:54 -04001266 system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001267 options are being passed to the linker commands and your binaries
1268 have potential security issues.
1269
1270- ``split-strip:`` Reports that splitting or stripping debug symbols
1271 from binaries has failed.
1272
1273- ``staticdev:`` Checks for static library files (``*.a``) in
1274 non-``staticdev`` packages.
1275
1276- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
1277 into :term:`TMPDIR` on the host. Such symlinks will
1278 work on the host, but are clearly invalid when running on the target.
1279
1280- ``textrel:`` Checks for ELF binaries that contain relocations in
1281 their ``.text`` sections, which can result in a performance impact at
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001282 runtime. See the explanation for the ``ELF binary`` message in
Andrew Geissler09209ee2020-12-13 08:44:15 -06001283 ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001284 issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001285
1286- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
1287 for a package are also declared on the recipe level (i.e. any license
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001288 in ``LICENSE:*`` should appear in :term:`LICENSE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001289
1290- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
1291 in the binaries that by default on a standard system are searched by
1292 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
1293 not cause any breakage, they do waste space and are unnecessary.
1294
1295- ``var-undefined:`` Reports when variables fundamental to packaging
1296 (i.e. :term:`WORKDIR`,
1297 :term:`DEPLOY_DIR`, :term:`D`,
1298 :term:`PN`, and :term:`PKGD`) are undefined
1299 during :ref:`ref-tasks-package`.
1300
1301- ``version-going-backwards:`` If Build History is enabled, reports
1302 when a package being written out has a lower version than the
1303 previously written package under the same name. If you are placing
1304 output packages into a feed and upgrading packages on a target system
1305 using that feed, the version of a package going backwards can result
1306 in the target system not correctly upgrading to the "new" version of
1307 the package.
1308
1309 .. note::
1310
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001311 This is only relevant when you are using runtime package management
1312 on your target system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001313
1314- ``xorg-driver-abi:`` Checks that all packages containing Xorg
1315 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
1316 driver ABI names. All drivers should depend on the ABI versions that
1317 they have been built against. Driver recipes that include
1318 ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
1319 automatically get these versions. Consequently, you should only need
1320 to explicitly add dependencies to binary driver recipes.
1321
1322.. _ref-classes-insserv:
1323
1324``insserv.bbclass``
1325===================
1326
Patrick Williams2390b1b2022-11-03 13:47:49 -05001327The :ref:`insserv <ref-classes-insserv>` class uses the ``insserv`` utility to update the order
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001328of symbolic links in ``/etc/rc?.d/`` within an image based on
1329dependencies specified by LSB headers in the ``init.d`` scripts
1330themselves.
1331
1332.. _ref-classes-kernel:
1333
1334``kernel.bbclass``
1335==================
1336
Patrick Williams2390b1b2022-11-03 13:47:49 -05001337The :ref:`kernel <ref-classes-kernel>` class handles building Linux kernels. The class contains
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001338code to build all kernel trees. All needed headers are staged into the
Andrew Geissler5f350902021-07-23 13:09:54 -04001339:term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001340using the :ref:`module <ref-classes-module>` class.
1341
1342This means that each built kernel module is packaged separately and
1343inter-module dependencies are created by parsing the ``modinfo`` output.
1344If all modules are required, then installing the ``kernel-modules``
1345package installs all packages with modules and various other kernel
1346packages such as ``kernel-vmlinux``.
1347
Patrick Williams2390b1b2022-11-03 13:47:49 -05001348The :ref:`kernel <ref-classes-kernel>` class contains logic that allows you to embed an initial
Patrick Williams2194f502022-10-16 14:26:09 -05001349RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For
1350information on how to build an :term:`Initramfs`, see the
1351":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001352the Yocto Project Development Tasks Manual.
1353
Patrick Williams2390b1b2022-11-03 13:47:49 -05001354Various other classes are used by the :ref:`kernel <ref-classes-kernel>` and :ref:`module <ref-classes-module>` classes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001355internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`,
1356:ref:`module-base <ref-classes-module-base>`, and
1357:ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes.
1358
1359.. _ref-classes-kernel-arch:
1360
1361``kernel-arch.bbclass``
1362=======================
1363
Patrick Williams2390b1b2022-11-03 13:47:49 -05001364The :ref:`kernel-arch <ref-classes-kernel-arch>` class sets the ``ARCH`` environment variable for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001365Linux kernel compilation (including modules).
1366
1367.. _ref-classes-kernel-devicetree:
1368
1369``kernel-devicetree.bbclass``
1370=============================
1371
Patrick Williams2390b1b2022-11-03 13:47:49 -05001372The :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class, which is inherited by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001373:ref:`kernel <ref-classes-kernel>` class, supports device tree
1374generation.
1375
1376.. _ref-classes-kernel-fitimage:
1377
1378``kernel-fitimage.bbclass``
1379===========================
1380
Patrick Williams2390b1b2022-11-03 13:47:49 -05001381The :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class provides support to pack a kernel image,
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001382device trees, a U-boot script, a Initramfs bundle and a RAM disk
1383into a single FIT image. In theory, a FIT image can support any number
1384of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees.
Patrick Williams2390b1b2022-11-03 13:47:49 -05001385However, :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` currently only supports
Patrick Williams975a06f2022-10-21 14:42:47 -05001386limited usecases: just one kernel image, an optional U-boot script,
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001387an optional Initramfs bundle, an optional RAM disk, and any number of
1388device tree.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001389
1390To create a FIT image, it is required that :term:`KERNEL_CLASSES`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001391is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001392is set to "fitImage".
1393
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001394The options for the device tree compiler passed to ``mkimage -D``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001395when creating the FIT image are specified using the
1396:term:`UBOOT_MKIMAGE_DTCOPTS` variable.
1397
1398Only a single kernel can be added to the FIT image created by
Patrick Williams2390b1b2022-11-03 13:47:49 -05001399:ref:`kernel-fitimage <ref-classes-kernel-fitimage>` and the kernel image in FIT is mandatory. The
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001400address where the kernel image is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001401specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by
1402:term:`UBOOT_ENTRYPOINT`.
1403
1404Multiple device trees can be added to the FIT image created by
Patrick Williams2390b1b2022-11-03 13:47:49 -05001405:ref:`kernel-fitimage <ref-classes-kernel-fitimage>` and the device tree is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001406The address where the device tree is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001407specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001408and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001409
1410Only a single RAM disk can be added to the FIT image created by
Patrick Williams2390b1b2022-11-03 13:47:49 -05001411:ref:`kernel-fitimage <ref-classes-kernel-fitimage>` and the RAM disk in FIT is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001412The address where the RAM disk image is to be loaded by U-Boot
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001413is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
1414:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001415:term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE`
1416is set to 0.
1417
1418Only a single Initramfs bundle can be added to the FIT image created by
Patrick Williams2390b1b2022-11-03 13:47:49 -05001419:ref:`kernel-fitimage <ref-classes-kernel-fitimage>` and the Initramfs bundle in FIT is optional.
Andrew Geissler595f6302022-01-24 19:11:47 +00001420In case of Initramfs, the kernel is configured to be bundled with the root filesystem
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001421in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin).
Andrew Geissler595f6302022-01-24 19:11:47 +00001422When the kernel is copied to RAM and executed, it unpacks the Initramfs root filesystem.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001423The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE`
1424is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1.
1425The address where the Initramfs bundle is to be loaded by U-boot is specified
1426by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`.
1427
1428Only a single U-boot boot script can be added to the FIT image created by
Patrick Williams2390b1b2022-11-03 13:47:49 -05001429:ref:`kernel-fitimage <ref-classes-kernel-fitimage>` and the boot script is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001430The boot script is specified in the ITS file as a text file containing
1431U-boot commands. When using a boot script the user should configure the
Patrick Williams2194f502022-10-16 14:26:09 -05001432U-boot :ref:`ref-tasks-install` task to copy the script to sysroot.
Patrick Williams2390b1b2022-11-03 13:47:49 -05001433So the script can be included in the FIT image by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001434class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
1435load the boot script from the FIT image and executes it.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001436
Patrick Williams2390b1b2022-11-03 13:47:49 -05001437The FIT image generated by :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class is signed when the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001438variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
1439:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
1440appropriately. The default values used for :term:`FIT_HASH_ALG` and
Patrick Williams2390b1b2022-11-03 13:47:49 -05001441:term:`FIT_SIGN_ALG` in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` are "sha256" and
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05001442"rsa2048" respectively. The keys for signing fitImage can be generated using
Patrick Williams2390b1b2022-11-03 13:47:49 -05001443the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class when both :term:`FIT_GENERATE_KEYS` and
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05001444:term:`UBOOT_SIGN_ENABLE` are set to "1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001445
1446
1447.. _ref-classes-kernel-grub:
1448
1449``kernel-grub.bbclass``
1450=======================
1451
Patrick Williams2390b1b2022-11-03 13:47:49 -05001452The :ref:`kernel-grub <ref-classes-kernel-grub>` class updates the boot area and the boot menu with
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001453the kernel as the priority boot mechanism while installing a RPM to
1454update the kernel on a deployed target.
1455
1456.. _ref-classes-kernel-module-split:
1457
1458``kernel-module-split.bbclass``
1459===============================
1460
Patrick Williams2390b1b2022-11-03 13:47:49 -05001461The :ref:`kernel-module-split <ref-classes-kernel-module-split>` class provides common functionality for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001462splitting Linux kernel modules into separate packages.
1463
1464.. _ref-classes-kernel-uboot:
1465
1466``kernel-uboot.bbclass``
1467========================
1468
Patrick Williams2390b1b2022-11-03 13:47:49 -05001469The :ref:`kernel-uboot <ref-classes-kernel-uboot>` class provides support for building from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001470vmlinux-style kernel sources.
1471
1472.. _ref-classes-kernel-uimage:
1473
1474``kernel-uimage.bbclass``
1475=========================
1476
Patrick Williams2390b1b2022-11-03 13:47:49 -05001477The :ref:`kernel-uimage <ref-classes-kernel-uimage>` class provides support to pack uImage.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001478
1479.. _ref-classes-kernel-yocto:
1480
1481``kernel-yocto.bbclass``
1482========================
1483
Patrick Williams2390b1b2022-11-03 13:47:49 -05001484The :ref:`kernel-yocto <ref-classes-kernel-yocto>` class provides common functionality for building
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001485from linux-yocto style kernel source repositories.
1486
1487.. _ref-classes-kernelsrc:
1488
1489``kernelsrc.bbclass``
1490=====================
1491
Patrick Williams2390b1b2022-11-03 13:47:49 -05001492The :ref:`kernelsrc <ref-classes-kernelsrc>` class sets the Linux kernel source and version.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001493
1494.. _ref-classes-lib_package:
1495
1496``lib_package.bbclass``
1497=======================
1498
Patrick Williams2390b1b2022-11-03 13:47:49 -05001499The :ref:`lib_package <ref-classes-lib_package>` class supports recipes that build libraries and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001500produce executable binaries, where those binaries should not be
1501installed by default along with the library. Instead, the binaries are
1502added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to
1503make their installation optional.
1504
1505.. _ref-classes-libc*:
1506
1507``libc*.bbclass``
1508=================
1509
Patrick Williams2390b1b2022-11-03 13:47:49 -05001510The :ref:`libc* <ref-classes-libc*>` classes support recipes that build packages with ``libc``:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001511
Patrick Williams2390b1b2022-11-03 13:47:49 -05001512- The :ref:`libc-common <ref-classes-libc*>` class provides common support for building with
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001513 ``libc``.
1514
Patrick Williams2390b1b2022-11-03 13:47:49 -05001515- The :ref:`libc-package <ref-classes-libc*>` class supports packaging up ``glibc`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001516 ``eglibc``.
1517
1518.. _ref-classes-license:
1519
1520``license.bbclass``
1521===================
1522
Patrick Williams2390b1b2022-11-03 13:47:49 -05001523The :ref:`license <ref-classes-license>` class provides license manifest creation and license
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001524exclusion. This class is enabled by default using the default value for
1525the :term:`INHERIT_DISTRO` variable.
1526
1527.. _ref-classes-linux-kernel-base:
1528
1529``linux-kernel-base.bbclass``
1530=============================
1531
Patrick Williams2390b1b2022-11-03 13:47:49 -05001532The :ref:`linux-kernel-base <ref-classes-linux-kernel-base>` class provides common functionality for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001533recipes that build out of the Linux kernel source tree. These builds
1534goes beyond the kernel itself. For example, the Perf recipe also
1535inherits this class.
1536
1537.. _ref-classes-linuxloader:
1538
1539``linuxloader.bbclass``
1540=======================
1541
1542Provides the function ``linuxloader()``, which gives the value of the
1543dynamic loader/linker provided on the platform. This value is used by a
1544number of other classes.
1545
1546.. _ref-classes-logging:
1547
1548``logging.bbclass``
1549===================
1550
Patrick Williams2390b1b2022-11-03 13:47:49 -05001551The :ref:`logging <ref-classes-logging>` class provides the standard shell functions used to log
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001552messages for various BitBake severity levels (i.e. ``bbplain``,
1553``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``).
1554
Patrick Williams2390b1b2022-11-03 13:47:49 -05001555This class is enabled by default since it is inherited by the :ref:`base <ref-classes-base>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001556class.
1557
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001558.. _ref-classes-metadata_scm:
1559
1560``metadata_scm.bbclass``
1561========================
1562
Patrick Williams2390b1b2022-11-03 13:47:49 -05001563The :ref:`metadata_scm <ref-classes-metadata_scm>` class provides functionality for querying the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001564branch and revision of a Source Code Manager (SCM) repository.
1565
1566The :ref:`base <ref-classes-base>` class uses this class to print the
1567revisions of each layer before starting every build. The
Patrick Williams2390b1b2022-11-03 13:47:49 -05001568:ref:`metadata_scm <ref-classes-metadata_scm>` class is enabled by default because it is inherited by
1569the :ref:`base <ref-classes-base>` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001570
1571.. _ref-classes-migrate_localcount:
1572
1573``migrate_localcount.bbclass``
1574==============================
1575
Patrick Williams2390b1b2022-11-03 13:47:49 -05001576The :ref:`migrate_localcount <ref-classes-migrate_localcount>` class verifies a recipe's localcount data and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001577increments it appropriately.
1578
1579.. _ref-classes-mime:
1580
1581``mime.bbclass``
1582================
1583
Patrick Williams2390b1b2022-11-03 13:47:49 -05001584The :ref:`mime <ref-classes-mime>` class generates the proper post-install and post-remove
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001585(postinst/postrm) scriptlets for packages that install MIME type files.
1586These scriptlets call ``update-mime-database`` to add the MIME types to
1587the shared database.
1588
1589.. _ref-classes-mirrors:
1590
1591``mirrors.bbclass``
1592===================
1593
Patrick Williams2390b1b2022-11-03 13:47:49 -05001594The :ref:`mirrors <ref-classes-mirrors>` class sets up some standard
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001595:term:`MIRRORS` entries for source code mirrors. These
1596mirrors provide a fall-back path in case the upstream source specified
1597in :term:`SRC_URI` within recipes is unavailable.
1598
1599This class is enabled by default since it is inherited by the
1600:ref:`base <ref-classes-base>` class.
1601
1602.. _ref-classes-module:
1603
1604``module.bbclass``
1605==================
1606
Patrick Williams2390b1b2022-11-03 13:47:49 -05001607The :ref:`module <ref-classes-module>` class provides support for building out-of-tree Linux
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001608kernel modules. The class inherits the
1609:ref:`module-base <ref-classes-module-base>` and
1610:ref:`kernel-module-split <ref-classes-kernel-module-split>` classes,
1611and implements the :ref:`ref-tasks-compile` and
1612:ref:`ref-tasks-install` tasks. The class provides
1613everything needed to build and package a kernel module.
1614
1615For general information on out-of-tree Linux kernel modules, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001616":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001617section in the Yocto Project Linux Kernel Development Manual.
1618
1619.. _ref-classes-module-base:
1620
1621``module-base.bbclass``
1622=======================
1623
Patrick Williams2390b1b2022-11-03 13:47:49 -05001624The :ref:`module-base <ref-classes-module-base>` class provides the base functionality for building
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001625Linux kernel modules. Typically, a recipe that builds software that
1626includes one or more kernel modules and has its own means of building
1627the module inherits this class as opposed to inheriting the
1628:ref:`module <ref-classes-module>` class.
1629
1630.. _ref-classes-multilib*:
1631
1632``multilib*.bbclass``
1633=====================
1634
Patrick Williams2390b1b2022-11-03 13:47:49 -05001635The :ref:`multilib* <ref-classes-multilib*>` classes provide support for building libraries with
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001636different target optimizations or target architectures and installing
1637them side-by-side in the same image.
1638
1639For more information on using the Multilib feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001640":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001641section in the Yocto Project Development Tasks Manual.
1642
1643.. _ref-classes-native:
1644
1645``native.bbclass``
1646==================
1647
Patrick Williams2390b1b2022-11-03 13:47:49 -05001648The :ref:`native <ref-classes-native>` class provides common functionality for recipes that
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001649build tools to run on the :term:`Build Host` (i.e. tools that use the compiler
1650or other tools from the build host).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001651
1652You can create a recipe that builds tools that run natively on the host
1653a couple different ways:
1654
Patrick Williams2390b1b2022-11-03 13:47:49 -05001655- Create a ``myrecipe-native.bb`` recipe that inherits the :ref:`native <ref-classes-native>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001656 class. If you use this method, you must order the inherit statement
1657 in the recipe after all other inherit statements so that the
Patrick Williams2390b1b2022-11-03 13:47:49 -05001658 :ref:`native <ref-classes-native>` class is inherited last.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001659
1660 .. note::
1661
1662 When creating a recipe this way, the recipe name must follow this
Andrew Geisslerc926e172021-05-07 16:11:35 -05001663 naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001664
1665 myrecipe-native.bb
1666
1667
1668 Not using this naming convention can lead to subtle problems
1669 caused by existing code that depends on that naming convention.
1670
Andrew Geisslerc926e172021-05-07 16:11:35 -05001671- Create or modify a target recipe that contains the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001672
1673 BBCLASSEXTEND = "native"
1674
1675 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001676 recipe, use ``:class-native`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001677 specify any functionality specific to the respective native or target
1678 case.
1679
Patrick Williams2390b1b2022-11-03 13:47:49 -05001680Although applied differently, the :ref:`native <ref-classes-native>` class is used with both
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001681methods. The advantage of the second method is that you do not need to
1682have two separate recipes (assuming you need both) for native and
1683target. All common parts of the recipe are automatically shared.
1684
1685.. _ref-classes-nativesdk:
1686
1687``nativesdk.bbclass``
1688=====================
1689
Patrick Williams2390b1b2022-11-03 13:47:49 -05001690The :ref:`nativesdk <ref-classes-nativesdk>` class provides common functionality for recipes that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001691wish to build tools to run as part of an SDK (i.e. tools that run on
1692:term:`SDKMACHINE`).
1693
1694You can create a recipe that builds tools that run on the SDK machine a
1695couple different ways:
1696
Andrew Geisslereff27472021-10-29 15:35:00 -05001697- Create a ``nativesdk-myrecipe.bb`` recipe that inherits the
Patrick Williams2390b1b2022-11-03 13:47:49 -05001698 :ref:`nativesdk <ref-classes-nativesdk>` class. If you use this method, you must order the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001699 inherit statement in the recipe after all other inherit statements so
Patrick Williams2390b1b2022-11-03 13:47:49 -05001700 that the :ref:`nativesdk <ref-classes-nativesdk>` class is inherited last.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001701
Patrick Williams2390b1b2022-11-03 13:47:49 -05001702- Create a :ref:`nativesdk <ref-classes-nativesdk>` variant of any recipe by adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001703
1704 BBCLASSEXTEND = "nativesdk"
1705
1706 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001707 recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001708 specify any functionality specific to the respective SDK machine or
1709 target case.
1710
1711.. note::
1712
Andrew Geisslerc926e172021-05-07 16:11:35 -05001713 When creating a recipe, you must follow this naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001714
1715 nativesdk-myrecipe.bb
1716
1717
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001718 Not doing so can lead to subtle problems because there is code that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001719 depends on the naming convention.
1720
Patrick Williams2390b1b2022-11-03 13:47:49 -05001721Although applied differently, the :ref:`nativesdk <ref-classes-nativesdk>` class is used with both
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001722methods. The advantage of the second method is that you do not need to
1723have two separate recipes (assuming you need both) for the SDK machine
1724and the target. All common parts of the recipe are automatically shared.
1725
1726.. _ref-classes-nopackages:
1727
1728``nopackages.bbclass``
1729======================
1730
1731Disables packaging tasks for those recipes and classes where packaging
1732is not needed.
1733
1734.. _ref-classes-npm:
1735
1736``npm.bbclass``
1737===============
1738
1739Provides support for building Node.js software fetched using the `node
1740package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
1741
1742.. note::
1743
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001744 Currently, recipes inheriting this class must use the ``npm://``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001745 fetcher to have dependencies fetched and packaged automatically.
1746
1747For information on how to create NPM packages, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001748":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001749section in the Yocto Project Development Tasks Manual.
1750
1751.. _ref-classes-oelint:
1752
1753``oelint.bbclass``
1754==================
1755
Patrick Williams2390b1b2022-11-03 13:47:49 -05001756The :ref:`oelint <ref-classes-oelint>` class is an obsolete lint checking tool available in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001757``meta/classes`` in the :term:`Source Directory`.
1758
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001759There are some classes that could be generally useful in OE-Core but
Patrick Williams2390b1b2022-11-03 13:47:49 -05001760are never actually used within OE-Core itself. The :ref:`oelint <ref-classes-oelint>` class is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001761one such example. However, being aware of this class can reduce the
1762proliferation of different versions of similar classes across multiple
1763layers.
1764
Andrew Geissler5199d832021-09-24 16:47:35 -05001765.. _ref-classes-overlayfs:
1766
1767``overlayfs.bbclass``
1768=======================
1769
Andrew Geissler595f6302022-01-24 19:11:47 +00001770It's often desired in Embedded System design to have a read-only root filesystem.
Andrew Geissler5199d832021-09-24 16:47:35 -05001771But a lot of different applications might want to have read-write access to
1772some parts of a filesystem. It can be especially useful when your update mechanism
Andrew Geissler595f6302022-01-24 19:11:47 +00001773overwrites the whole root filesystem, but you may want your application data to be preserved
Andrew Geissler5199d832021-09-24 16:47:35 -05001774between updates. The :ref:`overlayfs <ref-classes-overlayfs>` class provides a way
1775to achieve that by means of ``overlayfs`` and at the same time keeping the base
Andrew Geissler595f6302022-01-24 19:11:47 +00001776root filesystem read-only.
Andrew Geissler5199d832021-09-24 16:47:35 -05001777
1778To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper
1779layer in your machine configuration. The underlying file system can be anything that
1780is supported by ``overlayfs``. This has to be done in your machine configuration::
1781
1782 OVERLAYFS_MOUNT_POINT[data] = "/data"
1783
1784.. note::
1785
1786 * QA checks fail to catch file existence if you redefine this variable in your recipe!
1787 * Only the existence of the systemd mount unit file is checked, not its contents.
1788 * To get more details on ``overlayfs``, its internals and supported operations, please refer
Patrick Williams2390b1b2022-11-03 13:47:49 -05001789 to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`__.
Andrew Geissler5199d832021-09-24 16:47:35 -05001790
1791The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
1792(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
1793
1794Then you can specify writable directories on a recipe basis (e.g. in my-application.bb)::
1795
1796 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
1797
1798To support several mount points you can use a different variable flag. Assuming we
1799want to have a writable location on the file system, but do not need that the data
Andrew Geissler595f6302022-01-24 19:11:47 +00001800survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs``
1801file system.
Andrew Geissler5199d832021-09-24 16:47:35 -05001802
1803In your machine configuration::
1804
1805 OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
1806
1807and then in your recipe::
1808
1809 OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
1810
Andrew Geissler595f6302022-01-24 19:11:47 +00001811On a practical note, your application recipe might require multiple
1812overlays to be mounted before running to avoid writing to the underlying
1813file system (which can be forbidden in case of read-only file system)
1814To achieve that :ref:`overlayfs <ref-classes-overlayfs>` provides a ``systemd``
1815helper service for mounting overlays. This helper service is named
1816``${PN}-overlays.service`` and can be depended on in your application recipe
1817(named ``application`` in the following example) ``systemd`` unit by adding
1818to the unit the following::
1819
1820 [Unit]
1821 After=application-overlays.service
1822 Requires=application-overlays.service
1823
Andrew Geissler5199d832021-09-24 16:47:35 -05001824.. note::
1825
1826 The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
Andrew Geissler595f6302022-01-24 19:11:47 +00001827 In order to get ``/etc`` in overlayfs, see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>`.
1828
1829.. _ref-classes-overlayfs-etc:
1830
1831``overlayfs-etc.bbclass``
1832=========================
1833
1834In order to have the ``/etc`` directory in overlayfs a special handling at early
1835boot stage is required. The idea is to supply a custom init script that mounts
1836``/etc`` before launching the actual init program, because the latter already
1837requires ``/etc`` to be mounted.
1838
1839Example usage in image recipe::
1840
1841 IMAGE_FEATURES += "overlayfs-etc"
1842
1843.. note::
1844
1845 This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`
1846
1847Your machine configuration should define at least the device, mount point, and file system type
1848you are going to use for ``overlayfs``::
1849
1850 OVERLAYFS_ETC_MOUNT_POINT = "/data"
1851 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
1852 OVERLAYFS_ETC_FSTYPE ?= "ext4"
1853
1854To control more mount options you should consider setting mount options
1855(``defaults`` is used by default)::
1856
1857 OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
1858
1859The class provides two options for ``/sbin/init`` generation:
1860
1861- The default option is to rename the original ``/sbin/init`` to ``/sbin/init.orig``
1862 and place the generated init under original name, i.e. ``/sbin/init``. It has an advantage
1863 that you won't need to change any kernel parameters in order to make it work,
1864 but it poses a restriction that package-management can't be used, because updating
1865 the init manager would remove the generated script.
1866
1867- If you wish to keep original init as is, you can set::
1868
1869 OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
1870
1871 Then the generated init will be named ``/sbin/preinit`` and you would need to extend your
1872 kernel parameters manually in your bootloader configuration.
Andrew Geissler5199d832021-09-24 16:47:35 -05001873
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001874.. _ref-classes-own-mirrors:
1875
1876``own-mirrors.bbclass``
1877=======================
1878
Patrick Williams2390b1b2022-11-03 13:47:49 -05001879The :ref:`own-mirrors <ref-classes-own-mirrors>` class makes it easier to set up your own
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001880:term:`PREMIRRORS` from which to first fetch source
1881before attempting to fetch it from the upstream specified in
1882:term:`SRC_URI` within each recipe.
1883
1884To use this class, inherit it globally and specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05001885:term:`SOURCE_MIRROR_URL`. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001886
1887 INHERIT += "own-mirrors"
1888 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1889
1890You can specify only a single URL
Andrew Geissler09036742021-06-25 14:25:14 -05001891in :term:`SOURCE_MIRROR_URL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001892
1893.. _ref-classes-package:
1894
1895``package.bbclass``
1896===================
1897
Patrick Williams2390b1b2022-11-03 13:47:49 -05001898The :ref:`package <ref-classes-package>` class supports generating packages from a build's
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001899output. The core generic functionality is in ``package.bbclass``. The
1900code specific to particular package types resides in these
1901package-specific classes:
1902:ref:`package_deb <ref-classes-package_deb>`,
1903:ref:`package_rpm <ref-classes-package_rpm>`,
1904:ref:`package_ipk <ref-classes-package_ipk>`, and
1905:ref:`package_tar <ref-classes-package_tar>`.
1906
1907.. note::
1908
Patrick Williams2390b1b2022-11-03 13:47:49 -05001909 The :ref:`package_tar <ref-classes-package_tar>` class is broken and
1910 not supported. It is recommended that you do not use this class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001911
1912You can control the list of resulting package formats by using the
Andrew Geissler09036742021-06-25 14:25:14 -05001913:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001914configuration file, which is located in the :term:`Build Directory`.
Patrick Williams2390b1b2022-11-03 13:47:49 -05001915When defining the variable, you can specify one or more package types.
1916Since images are generated from packages, a packaging class is needed
1917to enable image generation. The first class listed in this variable is
1918used for image generation.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001919
1920If you take the optional step to set up a repository (package feed) on
1921the development host that can be used by DNF, you can install packages
1922from the feed while you are running the image on the target (i.e.
1923runtime installation of packages). For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001924":ref:`dev-manual/common-tasks:using runtime package management`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001925section in the Yocto Project Development Tasks Manual.
1926
1927The package-specific class you choose can affect build-time performance
1928and has space ramifications. In general, building a package with IPK
1929takes about thirty percent less time as compared to using RPM to build
1930the same or similar package. This comparison takes into account a
1931complete build of the package with all dependencies previously built.
1932The reason for this discrepancy is because the RPM package manager
1933creates and processes more :term:`Metadata` than the IPK package
Andrew Geissler09036742021-06-25 14:25:14 -05001934manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to
Patrick Williams2390b1b2022-11-03 13:47:49 -05001935":ref:`package_ipk <ref-classes-package_ipk>`" if you are building smaller systems.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001936
1937Before making your package manager decision, however, you should
1938consider some further things about using RPM:
1939
1940- RPM starts to provide more abilities than IPK due to the fact that it
1941 processes more Metadata. For example, this information includes
1942 individual file types, file checksum generation and evaluation on
1943 install, sparse file support, conflict detection and resolution for
1944 Multilib systems, ACID style upgrade, and repackaging abilities for
1945 rollbacks.
1946
1947- For smaller systems, the extra space used for the Berkeley Database
1948 and the amount of metadata when using RPM can affect your ability to
1949 perform on-device upgrades.
1950
1951You can find additional information on the effects of the package class
1952at these two Yocto Project mailing list links:
1953
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001954- :yocto_lists:`/pipermail/poky/2011-May/006362.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001955
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001956- :yocto_lists:`/pipermail/poky/2011-May/006363.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001957
1958.. _ref-classes-package_deb:
1959
1960``package_deb.bbclass``
1961=======================
1962
Patrick Williams2390b1b2022-11-03 13:47:49 -05001963The :ref:`package_deb <ref-classes-package_deb>` class provides support for creating packages that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001964use the Debian (i.e. ``.deb``) file format. The class ensures the
1965packages are written out in a ``.deb`` file format to the
1966``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory.
1967
1968This class inherits the :ref:`package <ref-classes-package>` class and
1969is enabled through the :term:`PACKAGE_CLASSES`
1970variable in the ``local.conf`` file.
1971
1972.. _ref-classes-package_ipk:
1973
1974``package_ipk.bbclass``
1975=======================
1976
Patrick Williams2390b1b2022-11-03 13:47:49 -05001977The :ref:`package_ipk <ref-classes-package_ipk>` class provides support for creating packages that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001978use the IPK (i.e. ``.ipk``) file format. The class ensures the packages
1979are written out in a ``.ipk`` file format to the
1980``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory.
1981
1982This class inherits the :ref:`package <ref-classes-package>` class and
1983is enabled through the :term:`PACKAGE_CLASSES`
1984variable in the ``local.conf`` file.
1985
1986.. _ref-classes-package_rpm:
1987
1988``package_rpm.bbclass``
1989=======================
1990
Patrick Williams2390b1b2022-11-03 13:47:49 -05001991The :ref:`package_rpm <ref-classes-package_rpm>` class provides support for creating packages that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001992use the RPM (i.e. ``.rpm``) file format. The class ensures the packages
1993are written out in a ``.rpm`` file format to the
1994``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory.
1995
1996This class inherits the :ref:`package <ref-classes-package>` class and
1997is enabled through the :term:`PACKAGE_CLASSES`
1998variable in the ``local.conf`` file.
1999
2000.. _ref-classes-package_tar:
2001
2002``package_tar.bbclass``
2003=======================
2004
Patrick Williams2390b1b2022-11-03 13:47:49 -05002005The :ref:`package_tar <ref-classes-package_tar>` class provides support for creating tarballs. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002006class ensures the packages are written out in a tarball format to the
2007``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory.
2008
2009This class inherits the :ref:`package <ref-classes-package>` class and
2010is enabled through the :term:`PACKAGE_CLASSES`
2011variable in the ``local.conf`` file.
2012
2013.. note::
2014
Patrick Williams2390b1b2022-11-03 13:47:49 -05002015 You cannot specify the :ref:`package_tar <ref-classes-package_tar>` class first using the
Andrew Geissler09036742021-06-25 14:25:14 -05002016 :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002017 file formats for your image or SDK.
2018
2019.. _ref-classes-packagedata:
2020
2021``packagedata.bbclass``
2022=======================
2023
Patrick Williams2390b1b2022-11-03 13:47:49 -05002024The :ref:`packagedata <ref-classes-packagedata>` class provides common functionality for reading
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002025``pkgdata`` files found in :term:`PKGDATA_DIR`. These
2026files contain information about each output package produced by the
2027OpenEmbedded build system.
2028
2029This class is enabled by default because it is inherited by the
2030:ref:`package <ref-classes-package>` class.
2031
2032.. _ref-classes-packagegroup:
2033
2034``packagegroup.bbclass``
2035========================
2036
Patrick Williams2390b1b2022-11-03 13:47:49 -05002037The :ref:`packagegroup <ref-classes-packagegroup>` class sets default values appropriate for package
Andrew Geissler09036742021-06-25 14:25:14 -05002038group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002039so forth). It is highly recommended that all package group recipes
2040inherit this class.
2041
2042For information on how to use this class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002043":ref:`dev-manual/common-tasks:customizing images using custom package groups`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002044section in the Yocto Project Development Tasks Manual.
2045
2046Previously, this class was called the ``task`` class.
2047
2048.. _ref-classes-patch:
2049
2050``patch.bbclass``
2051=================
2052
Patrick Williams2390b1b2022-11-03 13:47:49 -05002053The :ref:`patch <ref-classes-patch>` class provides all functionality for applying patches
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002054during the :ref:`ref-tasks-patch` task.
2055
2056This class is enabled by default because it is inherited by the
2057:ref:`base <ref-classes-base>` class.
2058
2059.. _ref-classes-perlnative:
2060
2061``perlnative.bbclass``
2062======================
2063
Patrick Williams2390b1b2022-11-03 13:47:49 -05002064When inherited by a recipe, the :ref:`perlnative <ref-classes-perlnative>` class supports using the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002065native version of Perl built by the build system rather than using the
2066version provided by the build host.
2067
Patrick Williams975a06f2022-10-21 14:42:47 -05002068.. _ref-classes-pypi:
2069
2070``pypi.bbclass``
2071================
2072
Patrick Williams2390b1b2022-11-03 13:47:49 -05002073The :ref:`pypi <ref-classes-pypi>` class sets variables appropriately for recipes that build
Patrick Williams975a06f2022-10-21 14:42:47 -05002074Python modules from `PyPI <https://pypi.org/>`__, the Python Package Index.
2075By default it determines the PyPI package name based upon :term:`BPN`
2076(stripping the "python-" or "python3-" prefix off if present), however in
2077some cases you may need to set it manually in the recipe by setting
2078:term:`PYPI_PACKAGE`.
2079
Patrick Williams2390b1b2022-11-03 13:47:49 -05002080Variables set by the :ref:`pypi <ref-classes-pypi>` class include :term:`SRC_URI`, :term:`SECTION`,
Patrick Williams975a06f2022-10-21 14:42:47 -05002081:term:`HOMEPAGE`, :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`
2082and :term:`CVE_PRODUCT`.
2083
Patrick Williams45852732022-04-02 08:58:32 -05002084.. _ref-classes-python_flit_core:
2085
2086``python_flit_core.bbclass``
2087============================
2088
Patrick Williams2390b1b2022-11-03 13:47:49 -05002089The :ref:`python_flit_core <ref-classes-python_flit_core>` class enables building Python modules which declare
Patrick Williams45852732022-04-02 08:58:32 -05002090the `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
2091``flit_core.buildapi`` ``build-backend`` in the ``[build-system]``
2092section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
2093
2094Python modules built with ``flit_core.buildapi`` are pure Python (no
2095``C`` or ``Rust`` extensions).
2096
2097Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
2098
Andrew Geissler9aee5002022-03-30 16:27:02 +00002099.. _ref-classes-python_pep517:
2100
2101``python_pep517.bbclass``
Patrick Williams45852732022-04-02 08:58:32 -05002102=========================
Andrew Geissler9aee5002022-03-30 16:27:02 +00002103
Patrick Williams2390b1b2022-11-03 13:47:49 -05002104The :ref:`python_pep517 <ref-classes-python_pep517>` class builds and installs a Python ``wheel`` binary
Patrick Williams45852732022-04-02 08:58:32 -05002105archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__).
Andrew Geissler9aee5002022-03-30 16:27:02 +00002106
Patrick Williams45852732022-04-02 08:58:32 -05002107Recipes wouldn't inherit this directly, instead typically another class will
Andrew Geissler615f2f12022-07-15 14:00:58 -05002108inherit this and add the relevant native dependencies.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002109
Patrick Williams45852732022-04-02 08:58:32 -05002110Examples of classes which do this are :ref:`python_flit_core
2111<ref-classes-python_flit_core>`, :ref:`python_setuptools_build_meta
2112<ref-classes-python_setuptools_build_meta>`, and :ref:`python_poetry_core
2113<ref-classes-python_poetry_core>`.
2114
2115.. _ref-classes-python_poetry_core:
2116
2117``python_poetry_core.bbclass``
2118==============================
2119
Patrick Williams2390b1b2022-11-03 13:47:49 -05002120The :ref:`python_poetry_core <ref-classes-python_poetry_core>` class enables building Python modules which use the
Patrick Williams45852732022-04-02 08:58:32 -05002121`Poetry Core <https://python-poetry.org>`__ build system.
2122
2123Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002124
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002125.. _ref-classes-pixbufcache:
2126
2127``pixbufcache.bbclass``
2128=======================
2129
Patrick Williams2390b1b2022-11-03 13:47:49 -05002130The :ref:`pixbufcache <ref-classes-pixbufcache>` class generates the proper post-install and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002131post-remove (postinst/postrm) scriptlets for packages that install
2132pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets
2133call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache.
2134Since the cache files are architecture-specific, ``update_pixbuf_cache``
2135is run using QEMU if the postinst scriptlets need to be run on the build
2136host during image creation.
2137
2138If the pixbuf loaders being installed are in packages other than the
2139recipe's main package, set
2140:term:`PIXBUF_PACKAGES` to specify the packages
2141containing the loaders.
2142
2143.. _ref-classes-pkgconfig:
2144
2145``pkgconfig.bbclass``
2146=====================
2147
Patrick Williams2390b1b2022-11-03 13:47:49 -05002148The :ref:`pkgconfig <ref-classes-pkgconfig>` class provides a standard way to get header and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002149library information by using ``pkg-config``. This class aims to smooth
2150integration of ``pkg-config`` into libraries that use it.
2151
2152During staging, BitBake installs ``pkg-config`` data into the
2153``sysroots/`` directory. By making use of sysroot functionality within
Patrick Williams2390b1b2022-11-03 13:47:49 -05002154``pkg-config``, the :ref:`pkgconfig <ref-classes-pkgconfig>` class no longer has to manipulate the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002155files.
2156
2157.. _ref-classes-populate-sdk:
2158
2159``populate_sdk.bbclass``
2160========================
2161
Patrick Williams2390b1b2022-11-03 13:47:49 -05002162The :ref:`populate_sdk <ref-classes-populate-sdk>` class provides support for SDK-only recipes. For
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002163information on advantages gained when building a cross-development
2164toolchain using the :ref:`ref-tasks-populate_sdk`
Andrew Geissler09209ee2020-12-13 08:44:15 -06002165task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002166section in the Yocto Project Application Development and the Extensible
2167Software Development Kit (eSDK) manual.
2168
2169.. _ref-classes-populate-sdk-*:
2170
2171``populate_sdk_*.bbclass``
2172==========================
2173
Patrick Williams2390b1b2022-11-03 13:47:49 -05002174The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` classes support SDK creation and consist of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002175following classes:
2176
Patrick Williams2390b1b2022-11-03 13:47:49 -05002177- :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`: The base class supporting SDK creation under
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002178 all package managers (i.e. DEB, RPM, and opkg).
2179
Patrick Williams2390b1b2022-11-03 13:47:49 -05002180- :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the Debian
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002181 package manager.
2182
Patrick Williams2390b1b2022-11-03 13:47:49 -05002183- :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the RPM
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002184 package manager.
2185
Patrick Williams2390b1b2022-11-03 13:47:49 -05002186- :ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>`: Supports creation of the SDK given the opkg
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002187 (IPK format) package manager.
2188
Patrick Williams2390b1b2022-11-03 13:47:49 -05002189- :ref:`populate_sdk_ext <ref-classes-populate-sdk-*>`: Supports extensible SDK creation under all
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002190 package managers.
2191
Patrick Williams2390b1b2022-11-03 13:47:49 -05002192The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class inherits the appropriate
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002193``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on
2194:term:`IMAGE_PKGTYPE`.
2195
2196The base class ensures all source and destination directories are
2197established and then populates the SDK. After populating the SDK, the
Patrick Williams2390b1b2022-11-03 13:47:49 -05002198:ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class constructs two sysroots:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002199``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which
2200contains the cross-compiler and associated tooling, and the target,
2201which contains a target root filesystem that is configured for the SDK
2202usage. These two images reside in :term:`SDK_OUTPUT`,
Andrew Geisslerc926e172021-05-07 16:11:35 -05002203which consists of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002204
2205 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
2206 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
2207
2208Finally, the base populate SDK class creates the toolchain environment
2209setup script, the tarball of the SDK, and the installer.
2210
Patrick Williams2390b1b2022-11-03 13:47:49 -05002211The respective :ref:`populate_sdk_deb <ref-classes-populate-sdk-*>`, :ref:`populate_sdk_rpm <ref-classes-populate-sdk-*>`, and
2212:ref:`populate_sdk_ipk <ref-classes-populate-sdk-*>` classes each support the specific type of SDK.
2213These classes are inherited by and used with the :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002214class.
2215
2216For more information on the cross-development toolchain generation, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06002217the ":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002218section in the Yocto Project Overview and Concepts Manual. For
2219information on advantages gained when building a cross-development
2220toolchain using the :ref:`ref-tasks-populate_sdk`
2221task, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002222":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002223section in the Yocto Project Application Development and the Extensible
2224Software Development Kit (eSDK) manual.
2225
2226.. _ref-classes-prexport:
2227
2228``prexport.bbclass``
2229====================
2230
Patrick Williams2390b1b2022-11-03 13:47:49 -05002231The :ref:`prexport <ref-classes-prexport>` class provides functionality for exporting
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002232:term:`PR` values.
2233
2234.. note::
2235
2236 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002237 when using "``bitbake-prserv-tool export``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002238
2239.. _ref-classes-primport:
2240
2241``primport.bbclass``
2242====================
2243
Patrick Williams2390b1b2022-11-03 13:47:49 -05002244The :ref:`primport <ref-classes-primport>` class provides functionality for importing
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002245:term:`PR` values.
2246
2247.. note::
2248
2249 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002250 when using "``bitbake-prserv-tool import``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002251
2252.. _ref-classes-prserv:
2253
2254``prserv.bbclass``
2255==================
2256
Patrick Williams2390b1b2022-11-03 13:47:49 -05002257The :ref:`prserv <ref-classes-prserv>` class provides functionality for using a :ref:`PR
Andrew Geissler09209ee2020-12-13 08:44:15 -06002258service <dev-manual/common-tasks:working with a pr service>` in order to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002259automatically manage the incrementing of the :term:`PR`
2260variable for each recipe.
2261
2262This class is enabled by default because it is inherited by the
2263:ref:`package <ref-classes-package>` class. However, the OpenEmbedded
2264build system will not enable the functionality of this class unless
2265:term:`PRSERV_HOST` has been set.
2266
2267.. _ref-classes-ptest:
2268
2269``ptest.bbclass``
2270=================
2271
Patrick Williams2390b1b2022-11-03 13:47:49 -05002272The :ref:`ptest <ref-classes-ptest>` class provides functionality for packaging and installing
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002273runtime tests for recipes that build software that provides these tests.
2274
2275This class is intended to be inherited by individual recipes. However,
2276the class' functionality is largely disabled unless "ptest" appears in
2277:term:`DISTRO_FEATURES`. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002278":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002279section in the Yocto Project Development Tasks Manual for more information
2280on ptest.
2281
2282.. _ref-classes-ptest-gnome:
2283
2284``ptest-gnome.bbclass``
2285=======================
2286
2287Enables package tests (ptests) specifically for GNOME packages, which
2288have tests intended to be executed with ``gnome-desktop-testing``.
2289
2290For information on setting up and running ptests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002291":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002292section in the Yocto Project Development Tasks Manual.
2293
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002294.. _ref-classes-python3-dir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002295
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002296``python3-dir.bbclass``
2297=======================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002298
Patrick Williams2390b1b2022-11-03 13:47:49 -05002299The :ref:`python3-dir <ref-classes-python3-dir>` class provides the base version, location, and site
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002300package location for Python 3.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002301
2302.. _ref-classes-python3native:
2303
2304``python3native.bbclass``
2305=========================
2306
Patrick Williams2390b1b2022-11-03 13:47:49 -05002307The :ref:`python3native <ref-classes-python3native>` class supports using the native version of Python
Andrew Geisslerc9f78652020-09-18 14:11:35 -050023083 built by the build system rather than support of the version provided
2309by the build host.
2310
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002311.. _ref-classes-python3targetconfig:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002312
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002313``python3targetconfig.bbclass``
2314===============================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002315
Patrick Williams2390b1b2022-11-03 13:47:49 -05002316The :ref:`python3targetconfig <ref-classes-python3targetconfig>` class supports using the native version of Python
Andrew Geissler3b8a17c2021-04-15 15:55:55 -050023173 built by the build system rather than support of the version provided
2318by the build host, except that the configuration for the target machine
2319is accessible (such as correct installation directories). This also adds a
2320dependency on target ``python3``, so should only be used where appropriate
2321in order to avoid unnecessarily lengthening builds.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002322
2323.. _ref-classes-qemu:
2324
2325``qemu.bbclass``
2326================
2327
Patrick Williams2390b1b2022-11-03 13:47:49 -05002328The :ref:`qemu <ref-classes-qemu>` class provides functionality for recipes that either need
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002329QEMU or test for the existence of QEMU. Typically, this class is used to
2330run programs for a target system on the build host using QEMU's
2331application emulation mode.
2332
2333.. _ref-classes-recipe_sanity:
2334
2335``recipe_sanity.bbclass``
2336=========================
2337
Patrick Williams2390b1b2022-11-03 13:47:49 -05002338The :ref:`recipe_sanity <ref-classes-recipe_sanity>` class checks for the presence of any host system
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002339recipe prerequisites that might affect the build (e.g. variables that
2340are set or software that is present).
2341
2342.. _ref-classes-relocatable:
2343
2344``relocatable.bbclass``
2345=======================
2346
Patrick Williams2390b1b2022-11-03 13:47:49 -05002347The :ref:`relocatable <ref-classes-relocatable>` class enables relocation of binaries when they are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002348installed into the sysroot.
2349
2350This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class
2351and is used by both the :ref:`cross <ref-classes-cross>` and
2352:ref:`native <ref-classes-native>` classes.
2353
2354.. _ref-classes-remove-libtool:
2355
2356``remove-libtool.bbclass``
2357==========================
2358
Patrick Williams2390b1b2022-11-03 13:47:49 -05002359The :ref:`remove-libtool <ref-classes-remove-libtool>` class adds a post function to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002360:ref:`ref-tasks-install` task to remove all ``.la`` files
2361installed by ``libtool``. Removing these files results in them being
2362absent from both the sysroot and target packages.
2363
2364If a recipe needs the ``.la`` files to be installed, then the recipe can
Andrew Geisslerc926e172021-05-07 16:11:35 -05002365override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002366
2367 REMOVE_LIBTOOL_LA = "0"
2368
2369.. note::
2370
Patrick Williams2390b1b2022-11-03 13:47:49 -05002371 The :ref:`remove-libtool <ref-classes-remove-libtool>` class is not enabled by default.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002372
2373.. _ref-classes-report-error:
2374
2375``report-error.bbclass``
2376========================
2377
Patrick Williams2390b1b2022-11-03 13:47:49 -05002378The :ref:`report-error <ref-classes-report-error>` class supports enabling the :ref:`error reporting
Andrew Geissler09209ee2020-12-13 08:44:15 -06002379tool <dev-manual/common-tasks:using the error reporting tool>`",
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002380which allows you to submit build error information to a central database.
2381
2382The class collects debug information for recipe, recipe version, task,
2383machine, distro, build system, target system, host distro, branch,
2384commit, and log. From the information, report files using a JSON format
2385are created and stored in
2386``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2387
2388.. _ref-classes-rm-work:
2389
2390``rm_work.bbclass``
2391===================
2392
Patrick Williams2390b1b2022-11-03 13:47:49 -05002393The :ref:`rm_work <ref-classes-rm-work>` class supports deletion of temporary workspace, which
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002394can ease your hard drive demands during builds.
2395
2396The OpenEmbedded build system can use a substantial amount of disk space
2397during the build process. A portion of this space is the work files
2398under the ``${TMPDIR}/work`` directory for each recipe. Once the build
2399system generates the packages for a recipe, the work files for that
2400recipe are no longer needed. However, by default, the build system
2401preserves these files for inspection and possible debugging purposes. If
2402you would rather have these files deleted to save disk space as the
Patrick Williams2390b1b2022-11-03 13:47:49 -05002403build progresses, you can enable :ref:`rm_work <ref-classes-rm-work>` by adding the following to
2404your ``local.conf`` file, which is found in the :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002405
2406 INHERIT += "rm_work"
2407
2408If you are
2409modifying and building source code out of the work directory for a
Patrick Williams2390b1b2022-11-03 13:47:49 -05002410recipe, enabling :ref:`rm_work <ref-classes-rm-work>` will potentially result in your changes to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002411the source being lost. To exclude some recipes from having their work
Patrick Williams2390b1b2022-11-03 13:47:49 -05002412directories deleted by :ref:`rm_work <ref-classes-rm-work>`, you can add the names of the recipe
Andrew Geissler09036742021-06-25 14:25:14 -05002413or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which
Andrew Geisslerc926e172021-05-07 16:11:35 -05002414can also be set in your ``local.conf`` file. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002415
2416 RM_WORK_EXCLUDE += "busybox glibc"
2417
2418.. _ref-classes-rootfs*:
2419
2420``rootfs*.bbclass``
2421===================
2422
Patrick Williams2390b1b2022-11-03 13:47:49 -05002423The :ref:`rootfs* <ref-classes-rootfs*>` classes support creating the root filesystem for an
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002424image and consist of the following classes:
2425
Patrick Williams2390b1b2022-11-03 13:47:49 -05002426- The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class, which defines filesystem
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002427 post-processing functions for image recipes.
2428
Patrick Williams2390b1b2022-11-03 13:47:49 -05002429- The :ref:`rootfs_deb <ref-classes-rootfs*>` class, which supports creation of root filesystems
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002430 for images built using ``.deb`` packages.
2431
Patrick Williams2390b1b2022-11-03 13:47:49 -05002432- The :ref:`rootfs_rpm <ref-classes-rootfs*>` class, which supports creation of root filesystems
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002433 for images built using ``.rpm`` packages.
2434
Patrick Williams2390b1b2022-11-03 13:47:49 -05002435- The :ref:`rootfs_ipk <ref-classes-rootfs*>` class, which supports creation of root filesystems
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002436 for images built using ``.ipk`` packages.
2437
Patrick Williams2390b1b2022-11-03 13:47:49 -05002438- The :ref:`rootfsdebugfiles <ref-classes-rootfs*>` class, which installs additional files found
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002439 on the build host directly into the root filesystem.
2440
2441The root filesystem is created from packages using one of the
Patrick Williams2390b1b2022-11-03 13:47:49 -05002442:ref:`rootfs*.bbclass <ref-classes-rootfs*>` files as determined by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002443:term:`PACKAGE_CLASSES` variable.
2444
2445For information on how root filesystem images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002446":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002447section in the Yocto Project Overview and Concepts Manual.
2448
2449.. _ref-classes-sanity:
2450
2451``sanity.bbclass``
2452==================
2453
Patrick Williams2390b1b2022-11-03 13:47:49 -05002454The :ref:`sanity <ref-classes-sanity>` class checks to see if prerequisite software is present
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002455on the host system so that users can be notified of potential problems
2456that might affect their build. The class also performs basic user
2457configuration checks from the ``local.conf`` configuration file to
2458prevent common mistakes that cause build failures. Distribution policy
2459usually determines whether to include this class.
2460
2461.. _ref-classes-scons:
2462
2463``scons.bbclass``
2464=================
2465
Patrick Williams2390b1b2022-11-03 13:47:49 -05002466The :ref:`scons <ref-classes-scons>` class supports recipes that need to build software that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002467uses the SCons build system. You can use the
2468:term:`EXTRA_OESCONS` variable to specify
2469additional configuration options you want to pass SCons command line.
2470
2471.. _ref-classes-sdl:
2472
2473``sdl.bbclass``
2474===============
2475
Patrick Williams2390b1b2022-11-03 13:47:49 -05002476The :ref:`sdl <ref-classes-sdl>` class supports recipes that need to build software that uses
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002477the Simple DirectMedia Layer (SDL) library.
2478
Patrick Williams45852732022-04-02 08:58:32 -05002479.. _ref-classes-python_setuptools_build_meta:
Andrew Geissler9aee5002022-03-30 16:27:02 +00002480
Patrick Williams45852732022-04-02 08:58:32 -05002481``python_setuptools_build_meta.bbclass``
2482========================================
Andrew Geissler9aee5002022-03-30 16:27:02 +00002483
Patrick Williams2390b1b2022-11-03 13:47:49 -05002484The :ref:`python_setuptools_build_meta <ref-classes-python_setuptools_build_meta>` class enables building Python modules which
Andrew Geissler9aee5002022-03-30 16:27:02 +00002485declare the
2486`PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
2487``setuptools.build_meta`` ``build-backend`` in the ``[build-system]``
2488section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
2489
2490Python modules built with ``setuptools.build_meta`` can be pure Python or
2491include ``C`` or ``Rust`` extensions).
2492
Patrick Williams45852732022-04-02 08:58:32 -05002493Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002494
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002495.. _ref-classes-setuptools3:
2496
2497``setuptools3.bbclass``
2498=======================
2499
Patrick Williams2390b1b2022-11-03 13:47:49 -05002500The :ref:`setuptools3 <ref-classes-setuptools3>` class supports Python version 3.x extensions that
Andrew Geissler9aee5002022-03-30 16:27:02 +00002501use build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and
2502have not migrated to the official ``pyproject.toml`` format). If your recipe
Patrick Williams2390b1b2022-11-03 13:47:49 -05002503uses these build systems, the recipe needs to inherit the :ref:`setuptools3 <ref-classes-setuptools3>` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002504
2505 .. note::
2506
Patrick Williams2390b1b2022-11-03 13:47:49 -05002507 The :ref:`setuptools3 <ref-classes-setuptools3>` class :ref:`ref-tasks-compile` task now calls
Andrew Geissler9aee5002022-03-30 16:27:02 +00002508 ``setup.py bdist_wheel`` to build the ``wheel`` binary archive format
2509 (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__).
2510
2511 A consequence of this is that legacy software still using deprecated
2512 ``distutils`` from the Python standard library cannot be packaged as
2513 ``wheels``. A common solution is the replace
2514 ``from distutils.core import setup`` with ``from setuptools import setup``.
2515
2516 .. note::
2517
Patrick Williams2390b1b2022-11-03 13:47:49 -05002518 The :ref:`setuptools3 <ref-classes-setuptools3>` class :ref:`ref-tasks-install` task now installs the ``wheel``
Andrew Geissler9aee5002022-03-30 16:27:02 +00002519 binary archive. In current versions of ``setuptools`` the legacy ``setup.py
2520 install`` method is deprecated. If the ``setup.py`` cannot be used with
2521 wheels, for example it creates files outside of the Python module or
2522 standard entry points, then :ref:`setuptools3_legacy
2523 <ref-classes-setuptools3_legacy>` should be used.
2524
2525.. _ref-classes-setuptools3_legacy:
2526
2527``setuptools3_legacy.bbclass``
2528==============================
2529
Patrick Williams2390b1b2022-11-03 13:47:49 -05002530The :ref:`setuptools3_legacy <ref-classes-setuptools3_legacy>` class supports Python version 3.x extensions that use
Andrew Geissler9aee5002022-03-30 16:27:02 +00002531build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and have
2532not migrated to the official ``pyproject.toml`` format). Unlike
2533``setuptools3.bbclass``, this uses the traditional ``setup.py`` ``build`` and
2534``install`` commands and not wheels. This use of ``setuptools`` like this is
Patrick Williams2390b1b2022-11-03 13:47:49 -05002535`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`__
Andrew Geissler9aee5002022-03-30 16:27:02 +00002536but still relatively common.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002537
Andrew Geissler595f6302022-01-24 19:11:47 +00002538.. _ref-classes-setuptools3-base:
2539
2540``setuptools3-base.bbclass``
2541============================
2542
Patrick Williams2390b1b2022-11-03 13:47:49 -05002543The :ref:`setuptools3-base <ref-classes-setuptools3-base>` class provides a reusable base for other classes
Andrew Geissler595f6302022-01-24 19:11:47 +00002544that support building Python version 3.x extensions. If you need
2545functionality that is not provided by the :ref:`setuptools3 <ref-classes-setuptools3>` class, you may
2546want to ``inherit setuptools3-base``. Some recipes do not need the tasks
2547in the :ref:`setuptools3 <ref-classes-setuptools3>` class and inherit this class instead.
2548
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002549.. _ref-classes-sign_rpm:
2550
2551``sign_rpm.bbclass``
2552====================
2553
Patrick Williams2390b1b2022-11-03 13:47:49 -05002554The :ref:`sign_rpm <ref-classes-sign_rpm>` class supports generating signed RPM packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002555
2556.. _ref-classes-sip:
2557
2558``sip.bbclass``
2559===============
2560
Patrick Williams2390b1b2022-11-03 13:47:49 -05002561The :ref:`sip <ref-classes-sip>` class supports recipes that build or package SIP-based
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002562Python bindings.
2563
2564.. _ref-classes-siteconfig:
2565
2566``siteconfig.bbclass``
2567======================
2568
Patrick Williams2390b1b2022-11-03 13:47:49 -05002569The :ref:`siteconfig <ref-classes-siteconfig>` class provides functionality for handling site
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002570configuration. The class is used by the
2571:ref:`autotools <ref-classes-autotools>` class to accelerate the
2572:ref:`ref-tasks-configure` task.
2573
2574.. _ref-classes-siteinfo:
2575
2576``siteinfo.bbclass``
2577====================
2578
Patrick Williams2390b1b2022-11-03 13:47:49 -05002579The :ref:`siteinfo <ref-classes-siteinfo>` class provides information about the targets that might
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002580be needed by other classes or recipes.
2581
2582As an example, consider Autotools, which can require tests that must
2583execute on the target hardware. Since this is not possible in general
2584when cross compiling, site information is used to provide cached test
2585results so these tests can be skipped over but still make the correct
2586values available. The ``meta/site directory`` contains test results
2587sorted into different categories such as architecture, endianness, and
2588the ``libc`` used. Site information provides a list of files containing
Andrew Geissler09036742021-06-25 14:25:14 -05002589data relevant to the current build in the :term:`CONFIG_SITE` variable that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002590Autotools automatically picks up.
2591
Andrew Geissler09036742021-06-25 14:25:14 -05002592The class also provides variables like :term:`SITEINFO_ENDIANNESS` and
2593:term:`SITEINFO_BITS` that can be used elsewhere in the metadata.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002594
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002595.. _ref-classes-sstate:
2596
2597``sstate.bbclass``
2598==================
2599
Patrick Williams2390b1b2022-11-03 13:47:49 -05002600The :ref:`sstate <ref-classes-sstate>` class provides support for Shared State (sstate). By
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002601default, the class is enabled through the
2602:term:`INHERIT_DISTRO` variable's default value.
2603
2604For more information on sstate, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002605":ref:`overview-manual/concepts:shared state cache`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002606section in the Yocto Project Overview and Concepts Manual.
2607
2608.. _ref-classes-staging:
2609
2610``staging.bbclass``
2611===================
2612
Patrick Williams2390b1b2022-11-03 13:47:49 -05002613The :ref:`staging <ref-classes-staging>` class installs files into individual recipe work
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002614directories for sysroots. The class contains the following key tasks:
2615
2616- The :ref:`ref-tasks-populate_sysroot` task,
2617 which is responsible for handing the files that end up in the recipe
2618 sysroots.
2619
2620- The
2621 :ref:`ref-tasks-prepare_recipe_sysroot`
2622 task (a "partner" task to the ``populate_sysroot`` task), which
2623 installs the files into the individual recipe work directories (i.e.
2624 :term:`WORKDIR`).
2625
Patrick Williams2390b1b2022-11-03 13:47:49 -05002626The code in the :ref:`staging <ref-classes-staging>` class is complex and basically works in two
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002627stages:
2628
2629- *Stage One:* The first stage addresses recipes that have files they
2630 want to share with other recipes that have dependencies on the
2631 originating recipe. Normally these dependencies are installed through
2632 the :ref:`ref-tasks-install` task into
Patrick Williams2194f502022-10-16 14:26:09 -05002633 ``${``\ :term:`D`\ ``}``. The :ref:`ref-tasks-populate_sysroot` task
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002634 copies a subset of these files into ``${SYSROOT_DESTDIR}``. This
2635 subset of files is controlled by the
2636 :term:`SYSROOT_DIRS`,
2637 :term:`SYSROOT_DIRS_NATIVE`, and
Andrew Geissler9aee5002022-03-30 16:27:02 +00002638 :term:`SYSROOT_DIRS_IGNORE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002639 variables.
2640
2641 .. note::
2642
2643 Additionally, a recipe can customize the files further by
Andrew Geissler09036742021-06-25 14:25:14 -05002644 declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002645 variable.
2646
2647 A shared state (sstate) object is built from these files and the
2648 files are placed into a subdirectory of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002649 :ref:`structure-build-tmp-sysroots-components`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002650 The files are scanned for hardcoded paths to the original
2651 installation location. If the location is found in text files, the
2652 hardcoded locations are replaced by tokens and a list of the files
2653 needing such replacements is created. These adjustments are referred
2654 to as "FIXMEs". The list of files that are scanned for paths is
2655 controlled by the :term:`SSTATE_SCAN_FILES`
2656 variable.
2657
2658- *Stage Two:* The second stage addresses recipes that want to use
2659 something from another recipe and declare a dependency on that recipe
2660 through the :term:`DEPENDS` variable. The recipe will
2661 have a
2662 :ref:`ref-tasks-prepare_recipe_sysroot`
2663 task and when this task executes, it creates the ``recipe-sysroot``
2664 and ``recipe-sysroot-native`` in the recipe work directory (i.e.
2665 :term:`WORKDIR`). The OpenEmbedded build system
2666 creates hard links to copies of the relevant files from
2667 ``sysroots-components`` into the recipe work directory.
2668
2669 .. note::
2670
2671 If hard links are not possible, the build system uses actual
2672 copies.
2673
2674 The build system then addresses any "FIXMEs" to paths as defined from
2675 the list created in the first stage.
2676
2677 Finally, any files in ``${bindir}`` within the sysroot that have the
2678 prefix "``postinst-``" are executed.
2679
2680 .. note::
2681
2682 Although such sysroot post installation scripts are not
2683 recommended for general use, the files do allow some issues such
2684 as user creation and module indexes to be addressed.
2685
Andrew Geissler09036742021-06-25 14:25:14 -05002686 Because recipes can have other dependencies outside of :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002687 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
2688 the sysroot creation function ``extend_recipe_sysroot`` is also added
2689 as a pre-function for those tasks whose dependencies are not through
Andrew Geissler09036742021-06-25 14:25:14 -05002690 :term:`DEPENDS` but operate similarly.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002691
2692 When installing dependencies into the sysroot, the code traverses the
2693 dependency graph and processes dependencies in exactly the same way
2694 as the dependencies would or would not be when installed from sstate.
2695 This processing means, for example, a native tool would have its
2696 native dependencies added but a target library would not have its
2697 dependencies traversed or installed. The same sstate dependency code
2698 is used so that builds should be identical regardless of whether
2699 sstate was used or not. For a closer look, see the
2700 ``setscene_depvalid()`` function in the
2701 :ref:`sstate <ref-classes-sstate>` class.
2702
2703 The build system is careful to maintain manifests of the files it
2704 installs so that any given dependency can be installed as needed. The
2705 sstate hash of the installed item is also stored so that if it
2706 changes, the build system can reinstall it.
2707
2708.. _ref-classes-syslinux:
2709
2710``syslinux.bbclass``
2711====================
2712
Patrick Williams2390b1b2022-11-03 13:47:49 -05002713The :ref:`syslinux <ref-classes-syslinux>` class provides syslinux-specific functions for building
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002714bootable images.
2715
2716The class supports the following variables:
2717
2718- :term:`INITRD`: Indicates list of filesystem images to
2719 concatenate and use as an initial RAM disk (initrd). This variable is
2720 optional.
2721
2722- :term:`ROOTFS`: Indicates a filesystem image to include
2723 as the root filesystem. This variable is optional.
2724
2725- :term:`AUTO_SYSLINUXMENU`: Enables creating
2726 an automatic menu when set to "1".
2727
2728- :term:`LABELS`: Lists targets for automatic
2729 configuration.
2730
2731- :term:`APPEND`: Lists append string overrides for each
2732 label.
2733
2734- :term:`SYSLINUX_OPTS`: Lists additional options
2735 to add to the syslinux file. Semicolon characters separate multiple
2736 options.
2737
2738- :term:`SYSLINUX_SPLASH`: Lists a background
2739 for the VGA boot menu when you are using the boot menu.
2740
2741- :term:`SYSLINUX_DEFAULT_CONSOLE`: Set
2742 to "console=ttyX" to change kernel boot default console.
2743
2744- :term:`SYSLINUX_SERIAL`: Sets an alternate
2745 serial port. Or, turns off serial when the variable is set with an
2746 empty string.
2747
2748- :term:`SYSLINUX_SERIAL_TTY`: Sets an
2749 alternate "console=tty..." kernel boot argument.
2750
2751.. _ref-classes-systemd:
2752
2753``systemd.bbclass``
2754===================
2755
Patrick Williams2390b1b2022-11-03 13:47:49 -05002756The :ref:`systemd <ref-classes-systemd>` class provides support for recipes that install systemd
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002757unit files.
2758
2759The functionality for this class is disabled unless you have "systemd"
2760in :term:`DISTRO_FEATURES`.
2761
2762Under this class, the recipe or Makefile (i.e. whatever the recipe is
2763calling during the :ref:`ref-tasks-install` task)
2764installs unit files into
2765``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit
2766files being installed go into packages other than the main package, you
2767need to set :term:`SYSTEMD_PACKAGES` in your
2768recipe to identify the packages in which the files will be installed.
2769
2770You should set :term:`SYSTEMD_SERVICE` to the
2771name of the service file. You should also use a package name override to
2772indicate the package to which the value applies. If the value applies to
2773the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
Andrew Geisslerc926e172021-05-07 16:11:35 -05002774is an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002775
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002776 SYSTEMD_SERVICE:${PN} = "connman.service"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002777
2778Services are set up to start on boot automatically
2779unless you have set
2780:term:`SYSTEMD_AUTO_ENABLE` to "disable".
2781
Patrick Williams2390b1b2022-11-03 13:47:49 -05002782For more information on :ref:`systemd <ref-classes-systemd>`, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002783":ref:`dev-manual/common-tasks:selecting an initialization manager`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002784section in the Yocto Project Development Tasks Manual.
2785
2786.. _ref-classes-systemd-boot:
2787
2788``systemd-boot.bbclass``
2789========================
2790
Patrick Williams2390b1b2022-11-03 13:47:49 -05002791The :ref:`systemd-boot <ref-classes-systemd-boot>` class provides functions specific to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002792systemd-boot bootloader for building bootable images. This is an
2793internal class and is not intended to be used directly.
2794
2795.. note::
2796
Patrick Williams2390b1b2022-11-03 13:47:49 -05002797 The :ref:`systemd-boot <ref-classes-systemd-boot>` class is a result from merging the ``gummiboot`` class
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002798 used in previous Yocto Project releases with the ``systemd`` project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002799
2800Set the :term:`EFI_PROVIDER` variable to
Patrick Williams2390b1b2022-11-03 13:47:49 -05002801":ref:`systemd-boot <ref-classes-systemd-boot>`" to use this class. Doing so creates a standalone EFI
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002802bootloader that is not dependent on systemd.
2803
2804For information on more variables used and supported in this class, see
2805the :term:`SYSTEMD_BOOT_CFG`,
2806:term:`SYSTEMD_BOOT_ENTRIES`, and
2807:term:`SYSTEMD_BOOT_TIMEOUT` variables.
2808
2809You can also see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002810documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002811for more information.
2812
2813.. _ref-classes-terminal:
2814
2815``terminal.bbclass``
2816====================
2817
Patrick Williams2390b1b2022-11-03 13:47:49 -05002818The :ref:`terminal <ref-classes-terminal>` class provides support for starting a terminal session.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002819The :term:`OE_TERMINAL` variable controls which
2820terminal emulator is used for the session.
2821
Patrick Williams2390b1b2022-11-03 13:47:49 -05002822Other classes use the :ref:`terminal <ref-classes-terminal>` class anywhere a separate terminal
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002823session needs to be started. For example, the
2824:ref:`patch <ref-classes-patch>` class assuming
2825:term:`PATCHRESOLVE` is set to "user", the
2826:ref:`cml1 <ref-classes-cml1>` class, and the
Patrick Williams2390b1b2022-11-03 13:47:49 -05002827:ref:`devshell <ref-classes-devshell>` class all use the :ref:`terminal <ref-classes-terminal>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002828class.
2829
Patrick Williams975a06f2022-10-21 14:42:47 -05002830.. _ref-classes-testimage:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002831
Patrick Williams975a06f2022-10-21 14:42:47 -05002832``testimage.bbclass``
2833=====================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002834
Patrick Williams2390b1b2022-11-03 13:47:49 -05002835The :ref:`testimage <ref-classes-testimage>` class supports running automated tests against
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002836images using QEMU and on actual hardware. The classes handle loading the
2837tests and starting the image. To use the classes, you need to perform
2838steps to set up the environment.
2839
Patrick Williams975a06f2022-10-21 14:42:47 -05002840To enable this class, add the following to your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002841
Patrick Williams975a06f2022-10-21 14:42:47 -05002842 IMAGE_CLASSES += "testimage"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002843
2844The tests are commands that run on the target system over ``ssh``. Each
2845test is written in Python and makes use of the ``unittest`` module.
2846
Patrick Williams2390b1b2022-11-03 13:47:49 -05002847The :ref:`testimage <ref-classes-testimage>` class runs tests on an image when called using the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002848following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002849
2850 $ bitbake -c testimage image
2851
Patrick Williams975a06f2022-10-21 14:42:47 -05002852Alternatively, if you wish to have tests automatically run for each image
2853after it is built, you can set :term:`TESTIMAGE_AUTO`::
2854
2855 TESTIMAGE_AUTO = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002856
2857For information on how to enable, run, and create new tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002858":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002859section in the Yocto Project Development Tasks Manual.
2860
2861.. _ref-classes-testsdk:
2862
2863``testsdk.bbclass``
2864===================
2865
2866This class supports running automated tests against software development
Patrick Williams2390b1b2022-11-03 13:47:49 -05002867kits (SDKs). The :ref:`testsdk <ref-classes-testsdk>` class runs tests on an SDK when called
Andrew Geisslerc926e172021-05-07 16:11:35 -05002868using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002869
2870 $ bitbake -c testsdk image
2871
2872.. note::
2873
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002874 Best practices include using :term:`IMAGE_CLASSES` rather than
Patrick Williams2390b1b2022-11-03 13:47:49 -05002875 :term:`INHERIT` to inherit the :ref:`testsdk <ref-classes-testsdk>` class for automated SDK
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002876 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002877
2878.. _ref-classes-texinfo:
2879
2880``texinfo.bbclass``
2881===================
2882
2883This class should be inherited by recipes whose upstream packages invoke
2884the ``texinfo`` utilities at build-time. Native and cross recipes are
2885made to use the dummy scripts provided by ``texinfo-dummy-native``, for
2886improved performance. Target architecture recipes use the genuine
2887Texinfo utilities. By default, they use the Texinfo utilities on the
2888host system.
2889
2890.. note::
2891
2892 If you want to use the Texinfo recipe shipped with the build system,
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002893 you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo
2894 from :term:`SANITY_REQUIRED_UTILITIES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002895
2896.. _ref-classes-toaster:
2897
2898``toaster.bbclass``
2899===================
2900
Patrick Williams2390b1b2022-11-03 13:47:49 -05002901The :ref:`toaster <ref-classes-toaster>` class collects information about packages and images and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002902sends them as events that the BitBake user interface can receive. The
2903class is enabled when the Toaster user interface is running.
2904
2905This class is not intended to be used directly.
2906
2907.. _ref-classes-toolchain-scripts:
2908
2909``toolchain-scripts.bbclass``
2910=============================
2911
Patrick Williams2390b1b2022-11-03 13:47:49 -05002912The :ref:`toolchain-scripts <ref-classes-toolchain-scripts>` class provides the scripts used for setting up
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002913the environment for installed SDKs.
2914
2915.. _ref-classes-typecheck:
2916
2917``typecheck.bbclass``
2918=====================
2919
Patrick Williams2390b1b2022-11-03 13:47:49 -05002920The :ref:`typecheck <ref-classes-typecheck>` class provides support for validating the values of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002921variables set at the configuration level against their defined types.
2922The OpenEmbedded build system allows you to define the type of a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002923variable using the "type" varflag. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002924
2925 IMAGE_FEATURES[type] = "list"
2926
2927.. _ref-classes-uboot-config:
2928
2929``uboot-config.bbclass``
2930========================
2931
Patrick Williams2390b1b2022-11-03 13:47:49 -05002932The :ref:`uboot-config <ref-classes-uboot-config>` class provides support for U-Boot configuration for
Andrew Geisslerc926e172021-05-07 16:11:35 -05002933a machine. Specify the machine in your recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002934
2935 UBOOT_CONFIG ??= <default>
2936 UBOOT_CONFIG[foo] = "config,images"
2937
Andrew Geisslerc926e172021-05-07 16:11:35 -05002938You can also specify the machine using this method::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002939
2940 UBOOT_MACHINE = "config"
2941
2942See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
2943information.
2944
2945.. _ref-classes-uninative:
2946
2947``uninative.bbclass``
2948=====================
2949
2950Attempts to isolate the build system from the host distribution's C
2951library in order to make re-use of native shared state artifacts across
2952different host distributions practical. With this class enabled, a
2953tarball containing a pre-built C library is downloaded at the start of
2954the build. In the Poky reference distribution this is enabled by default
2955through ``meta/conf/distro/include/yocto-uninative.inc``. Other
2956distributions that do not derive from poky can also
2957"``require conf/distro/include/yocto-uninative.inc``" to use this.
2958Alternatively if you prefer, you can build the uninative-tarball recipe
2959yourself, publish the resulting tarball (e.g. via HTTP) and set
2960``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an
2961example, see the ``meta/conf/distro/include/yocto-uninative.inc``.
2962
Patrick Williams2390b1b2022-11-03 13:47:49 -05002963The :ref:`uninative <ref-classes-uninative>` class is also used unconditionally by the extensible
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002964SDK. When building the extensible SDK, ``uninative-tarball`` is built
2965and the resulting tarball is included within the SDK.
2966
2967.. _ref-classes-update-alternatives:
2968
2969``update-alternatives.bbclass``
2970===============================
2971
Patrick Williams2390b1b2022-11-03 13:47:49 -05002972The :ref:`update-alternatives <ref-classes-update-alternatives>` class helps the alternatives system when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002973multiple sources provide the same command. This situation occurs when
2974several programs that have the same or similar function are installed
2975with the same name. For example, the ``ar`` command is available from
2976the ``busybox``, ``binutils`` and ``elfutils`` packages. The
Patrick Williams2390b1b2022-11-03 13:47:49 -05002977:ref:`update-alternatives <ref-classes-update-alternatives>` class handles renaming the binaries so that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002978multiple packages can be installed without conflicts. The ``ar`` command
2979still works regardless of which packages are installed or subsequently
2980removed. The class renames the conflicting binary in each package and
2981symlinks the highest priority binary during installation or removal of
2982packages.
2983
2984To use this class, you need to define a number of variables:
2985
2986- :term:`ALTERNATIVE`
2987
2988- :term:`ALTERNATIVE_LINK_NAME`
2989
2990- :term:`ALTERNATIVE_TARGET`
2991
2992- :term:`ALTERNATIVE_PRIORITY`
2993
2994These variables list alternative commands needed by a package, provide
2995pathnames for links, default links for targets, and so forth. For
2996details on how to use this class, see the comments in the
Patrick Williams975a06f2022-10-21 14:42:47 -05002997:yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes-recipe/update-alternatives.bbclass>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002998file.
2999
3000.. note::
3001
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003002 You can use the ``update-alternatives`` command directly in your recipes.
3003 However, this class simplifies things in most cases.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003004
3005.. _ref-classes-update-rc.d:
3006
3007``update-rc.d.bbclass``
3008=======================
3009
Patrick Williams2390b1b2022-11-03 13:47:49 -05003010The :ref:`update-rc.d <ref-classes-update-rc.d>` class uses ``update-rc.d`` to safely install an
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003011initialization script on behalf of the package. The OpenEmbedded build
3012system takes care of details such as making sure the script is stopped
3013before a package is removed and started when the package is installed.
3014
Andrew Geissler09036742021-06-25 14:25:14 -05003015Three variables control this class: :term:`INITSCRIPT_PACKAGES`,
3016:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003017for details.
3018
3019.. _ref-classes-useradd:
3020
3021``useradd*.bbclass``
3022====================
3023
Patrick Williams2390b1b2022-11-03 13:47:49 -05003024The :ref:`useradd* <ref-classes-useradd>` classes support the addition of users or groups for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003025usage by the package on the target. For example, if you have packages
3026that contain system services that should be run under their own user or
3027group, you can use these classes to enable creation of the user or
Andrew Geissler595f6302022-01-24 19:11:47 +00003028group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb
3029</openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003030recipe in the :term:`Source Directory` provides a simple
3031example that shows how to add three users and groups to two packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003032
Patrick Williams2390b1b2022-11-03 13:47:49 -05003033The :ref:`useradd_base <ref-classes-useradd>` class provides basic functionality for user or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003034groups settings.
3035
Patrick Williams2390b1b2022-11-03 13:47:49 -05003036The :ref:`useradd* <ref-classes-useradd>` classes support the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003037:term:`USERADD_PACKAGES`,
3038:term:`USERADD_PARAM`,
3039:term:`GROUPADD_PARAM`, and
3040:term:`GROUPMEMS_PARAM` variables.
3041
Patrick Williams2390b1b2022-11-03 13:47:49 -05003042The :ref:`useradd-staticids <ref-classes-useradd>` class supports the addition of users or groups
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003043that have static user identification (``uid``) and group identification
3044(``gid``) values.
3045
3046The default behavior of the OpenEmbedded build system for assigning
3047``uid`` and ``gid`` values when packages add users and groups during
3048package install time is to add them dynamically. This works fine for
3049programs that do not care what the values of the resulting users and
3050groups become. In these cases, the order of the installation determines
3051the final ``uid`` and ``gid`` values. However, if non-deterministic
3052``uid`` and ``gid`` values are a problem, you can override the default,
3053dynamic application of these values by setting static values. When you
3054set static values, the OpenEmbedded build system looks in
3055:term:`BBPATH` for ``files/passwd`` and ``files/group``
3056files for the values.
3057
3058To use static ``uid`` and ``gid`` values, you need to set some
3059variables. See the :term:`USERADDEXTENSION`,
3060:term:`USERADD_UID_TABLES`,
3061:term:`USERADD_GID_TABLES`, and
3062:term:`USERADD_ERROR_DYNAMIC` variables.
3063You can also see the :ref:`useradd <ref-classes-useradd>` class for
3064additional information.
3065
3066.. note::
3067
Patrick Williams2390b1b2022-11-03 13:47:49 -05003068 You do not use the :ref:`useradd-staticids <ref-classes-useradd>` class directly. You either enable
Andrew Geissler09036742021-06-25 14:25:14 -05003069 or disable the class by setting the :term:`USERADDEXTENSION` variable. If you
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003070 enable or disable the class in a configured system, :term:`TMPDIR` might
Andrew Geissler09036742021-06-25 14:25:14 -05003071 contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003072 directory will correct this condition.
3073
3074.. _ref-classes-utility-tasks:
3075
3076``utility-tasks.bbclass``
3077=========================
3078
Patrick Williams2390b1b2022-11-03 13:47:49 -05003079The :ref:`utility-tasks <ref-classes-utility-tasks>` class provides support for various "utility" type
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003080tasks that are applicable to all recipes, such as
3081:ref:`ref-tasks-clean` and
3082:ref:`ref-tasks-listtasks`.
3083
3084This class is enabled by default because it is inherited by the
3085:ref:`base <ref-classes-base>` class.
3086
3087.. _ref-classes-utils:
3088
3089``utils.bbclass``
3090=================
3091
Patrick Williams2390b1b2022-11-03 13:47:49 -05003092The :ref:`utils <ref-classes-utils>` class provides some useful Python functions that are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003093typically used in inline Python expressions (e.g. ``${@...}``). One
3094example use is for ``bb.utils.contains()``.
3095
3096This class is enabled by default because it is inherited by the
3097:ref:`base <ref-classes-base>` class.
3098
3099.. _ref-classes-vala:
3100
3101``vala.bbclass``
3102================
3103
Patrick Williams2390b1b2022-11-03 13:47:49 -05003104The :ref:`vala <ref-classes-vala>` class supports recipes that need to build software written
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003105using the Vala programming language.
3106
3107.. _ref-classes-waf:
3108
3109``waf.bbclass``
3110===============
3111
Patrick Williams2390b1b2022-11-03 13:47:49 -05003112The :ref:`waf <ref-classes-waf>` class supports recipes that need to build software that uses
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003113the Waf build system. You can use the
3114:term:`EXTRA_OECONF` or
3115:term:`PACKAGECONFIG_CONFARGS` variables
3116to specify additional configuration options to be passed on the Waf
3117command line.