blob: cd5a51695bab1719584a2702e053c0e2ca5225ee [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
40The ``allarch`` class is inherited by recipes that do not produce
41architecture-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
52 configured for all architectures using ``allarch``. This is the case
53 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
66inherit the ``allarch`` class.
67
68.. _ref-classes-archiver:
69
70``archiver.bbclass``
71====================
72
73The ``archiver`` class supports releasing source code and other
74materials with the binaries.
75
76For more details on the source 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 Williams03907ee2022-05-01 06:28:52 -050087The ``autotools*`` classes support packages built with the
88`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
99By default, the ``autotools*`` classes use out-of-tree builds (i.e.
100``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
104``autotools-brokensep`` class. The ``autotools-brokensep`` class behaves
105the same as the ``autotools`` class but builds with :term:`B`
106== :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
115``autotools*`` classes work and what they do behind the scenes.
116
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
136The ``base`` class is special in that every ``.bb`` file implicitly
137inherits 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
163The ``bin_package`` class is a helper class for recipes that extract the
164contents 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
190The ``binconfig`` class helps to correct paths in shell scripts.
191
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
222The ``buildhistory`` class records a history of build output metadata,
223which 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
234The ``buildstats`` class records performance statistics about each task
235executed 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
Andrew Geissler09036742021-06-25 14:25:14 -0500248remove "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
264The ``ccache`` class enables the C/C++ Compiler Cache for the build.
265This 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
281The ``chrpath`` class is a wrapper around the "chrpath" utility, which
282is used during the build process for ``nativesdk``, ``cross``, and
283``cross-canadian`` recipes to change ``RPATH`` records within binaries
284in order to make them relocatable.
285
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500286.. _ref-classes-cmake:
287
288``cmake.bbclass``
289=================
290
291The ``cmake`` class allows for recipes that need to build software using
292the `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
308The ``cml1`` class provides basic support for the Linux kernel style
309build 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
326The ``copyleft_compliance`` class preserves source code for the purposes
327of license compliance. This class is an alternative to the ``archiver``
328class 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
346The ``core-image`` class provides common definitions for the
347``core-image-*`` image recipes, such as support for additional
348:term:`IMAGE_FEATURES`.
349
350.. _ref-classes-cpan:
351
352``cpan*.bbclass``
353=================
354
355The ``cpan*`` classes support Perl modules.
356
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
368Both build methods inherit the ``cpan-base`` class for basic Perl
369support.
370
Patrick Williams975a06f2022-10-21 14:42:47 -0500371.. _ref-classes-create-spdx:
372
373``create-spdx.bbclass``
374=======================
375
376The ``create-spdx`` class provides support for automatically creating
377SPDX 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
384The ``cross`` class provides support for the recipes that build the
385cross-compilation tools.
386
387.. _ref-classes-cross-canadian:
388
389``cross-canadian.bbclass``
390==========================
391
392The ``cross-canadian`` class provides support for the recipes that build
393the 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
403The ``crosssdk`` class provides support for the recipes that build the
404cross-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
414The ``cve-check`` class looks for known CVEs (Common Vulnerabilities
415and Exposures) while building an image. This class is meant to be
416inherited globally from a configuration file::
417
418 INHERIT += "cve-check"
419
420You can also look for vulnerabilities in specific packages by passing
421``-c cve_check`` to BitBake. You will find details in the
422":ref:`dev-manual/common-tasks:checking for vulnerabilities`"
423section in the Development Tasks Manual.
424
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500425.. _ref-classes-debian:
426
427``debian.bbclass``
428==================
429
430The ``debian`` class renames output packages so that they follow the
431Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and
432``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library
433name and version as part of the package name.
434
435If a recipe creates packages for multiple libraries (shared object files
436of ``.so`` type), use the :term:`LEAD_SONAME`
437variable in the recipe to specify the library on which to apply the
438naming scheme.
439
440.. _ref-classes-deploy:
441
442``deploy.bbclass``
443==================
444
445The ``deploy`` class handles deploying files to the
446:term:`DEPLOY_DIR_IMAGE` directory. The main
447function of this class is to allow the deploy step to be accelerated by
448shared state. Recipes that inherit this class should define their own
449:ref:`ref-tasks-deploy` function to copy the files to be
450deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
451add the task at the appropriate place, which is usually after
452:ref:`ref-tasks-compile` or
453:ref:`ref-tasks-install`. The class then takes care of
Andrew Geissler09036742021-06-25 14:25:14 -0500454staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500455
456.. _ref-classes-devshell:
457
458``devshell.bbclass``
459====================
460
Patrick Williams2194f502022-10-16 14:26:09 -0500461The ``devshell`` class adds the :ref:`ref-tasks-devshell` task. Distribution
Andrew Geissler09209ee2020-12-13 08:44:15 -0600462policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500463section in the Yocto Project Development Tasks Manual for more
464information about using ``devshell``.
465
466.. _ref-classes-devupstream:
467
468``devupstream.bbclass``
469=======================
470
471The ``devupstream`` class uses
472:term:`BBCLASSEXTEND` to add a variant of the
473recipe that fetches from an alternative URI (e.g. Git) instead of a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500474tarball. Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500475
476 BBCLASSEXTEND = "devupstream:target"
Andrew Geissler9aee5002022-03-30 16:27:02 +0000477 SRC_URI:class-devupstream = "git://git.example.com/example;branch=main"
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500478 SRCREV:class-devupstream = "abcd1234"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500479
480Adding the above statements to your recipe creates a variant that has
481:term:`DEFAULT_PREFERENCE` set to "-1".
482Consequently, you need to select the variant of the recipe to use it.
483Any development-specific adjustments can be done by using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500484``class-devupstream`` override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500485
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500486 DEPENDS:append:class-devupstream = " gperf-native"
487 do_configure:prepend:class-devupstream() {
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500488 touch ${S}/README
489 }
490
491The class
492currently only supports creating a development variant of the target
493recipe, not ``native`` or ``nativesdk`` variants.
494
Andrew Geissler09036742021-06-25 14:25:14 -0500495The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500496support for ``native`` and ``nativesdk`` variants. Consequently, this
497functionality can be added in a future release.
498
499Support for other version control systems such as Subversion is limited
500due to BitBake's automatic fetch dependencies (e.g.
501``subversion-native``).
502
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503.. _ref-classes-externalsrc:
504
505``externalsrc.bbclass``
506=======================
507
508The ``externalsrc`` class supports building software from source code
509that is external to the OpenEmbedded build system. Building software
510from an external source tree means that the build system's normal fetch,
511unpack, and patch process is not used.
512
513By default, the OpenEmbedded build system uses the :term:`S`
514and :term:`B` variables to locate unpacked recipe source code
515and to build it, respectively. When your recipe inherits the
516``externalsrc`` class, you use the
517:term:`EXTERNALSRC` and
518:term:`EXTERNALSRC_BUILD` variables to
Andrew Geissler09036742021-06-25 14:25:14 -0500519ultimately define :term:`S` and :term:`B`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500520
521By default, this class expects the source code to support recipe builds
522that use the :term:`B` variable to point to the directory in
523which the OpenEmbedded build system places the generated objects built
Andrew Geissler09036742021-06-25 14:25:14 -0500524from the recipes. By default, the :term:`B` directory is set to the
525following, which is separate from the source directory (:term:`S`)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500526
Andrew Geissler5199d832021-09-24 16:47:35 -0500527 ${WORKDIR}/${BPN}-{PV}/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500528
529See these variables for more information:
530:term:`WORKDIR`, :term:`BPN`, and
531:term:`PV`,
532
533For more information on the ``externalsrc`` class, see the comments in
534``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
535For information on how to use the
536``externalsrc`` class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600537":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500538section in the Yocto Project Development Tasks Manual.
539
540.. _ref-classes-extrausers:
541
542``extrausers.bbclass``
543======================
544
545The ``extrausers`` class allows additional user and group configuration
546to be applied at the image level. Inheriting this class either globally
547or from an image recipe allows additional user and group operations to
548be performed using the
549:term:`EXTRA_USERS_PARAMS` variable.
550
551.. note::
552
553 The user and group operations added using the
Andrew Geissler595f6302022-01-24 19:11:47 +0000554 :ref:`extrausers <ref-classes-extrausers>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500555 class are not tied to a specific recipe outside of the recipe for the
556 image. Thus, the operations can be performed across the image as a
557 whole. Use the
Andrew Geissler595f6302022-01-24 19:11:47 +0000558 :ref:`useradd <ref-classes-useradd>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559 class to add user and group configuration to a specific recipe.
560
Andrew Geisslerc926e172021-05-07 16:11:35 -0500561Here is an example that uses this class in an image recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500562
563 inherit extrausers
564 EXTRA_USERS_PARAMS = "\
565 useradd -p '' tester; \
566 groupadd developers; \
567 userdel nobody; \
568 groupdel -g video; \
569 groupmod -g 1020 developers; \
570 usermod -s /bin/sh tester; \
571 "
572
573Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
Andrew Geissler9aee5002022-03-30 16:27:02 +0000574passwords. First on host, create the (escaped) password hash::
Andrew Geisslereff27472021-10-29 15:35:00 -0500575
Andrew Geissler9aee5002022-03-30 16:27:02 +0000576 printf "%q" $(mkpasswd -m sha256crypt tester01)
Andrew Geisslereff27472021-10-29 15:35:00 -0500577
Andrew Geissler9aee5002022-03-30 16:27:02 +0000578The resulting hash is set to a variable and used in ``useradd`` command parameters::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500579
580 inherit extrausers
Andrew Geisslereff27472021-10-29 15:35:00 -0500581 PASSWD = "\$X\$ABC123\$A-Long-Hash"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500582 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500583 useradd -p '${PASSWD}' tester-jim; \
584 useradd -p '${PASSWD}' tester-sue; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500585 "
586
Andrew Geisslereff27472021-10-29 15:35:00 -0500587Finally, here is an example that sets the root password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500588
589 inherit extrausers
590 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500591 usermod -p '${PASSWD}' root; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500592 "
593
Patrick Williams03907ee2022-05-01 06:28:52 -0500594.. note::
595
596 From a security perspective, hardcoding a default password is not
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500597 generally a good idea or even legal in some jurisdictions. It is
598 recommended that you do not do this if you are building a production
Patrick Williams03907ee2022-05-01 06:28:52 -0500599 image.
600
601
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600602.. _ref-classes-features_check:
603
604``features_check.bbclass``
605=================================
606
607The ``features_check`` class allows individual recipes to check
608for required and conflicting
609:term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`.
610
611This class provides support for the following variables:
612
613- :term:`REQUIRED_DISTRO_FEATURES`
614- :term:`CONFLICT_DISTRO_FEATURES`
615- :term:`ANY_OF_DISTRO_FEATURES`
616- ``REQUIRED_MACHINE_FEATURES``
617- ``CONFLICT_MACHINE_FEATURES``
618- ``ANY_OF_MACHINE_FEATURES``
619- ``REQUIRED_COMBINED_FEATURES``
620- ``CONFLICT_COMBINED_FEATURES``
621- ``ANY_OF_COMBINED_FEATURES``
622
623If any conditions specified in the recipe using the above
624variables are not met, the recipe will be skipped, and if the
625build system attempts to build the recipe then an error will be
626triggered.
627
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500628.. _ref-classes-fontcache:
629
630``fontcache.bbclass``
631=====================
632
633The ``fontcache`` class generates the proper post-install and
634post-remove (postinst and postrm) scriptlets for font packages. These
635scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts
636to the font information cache. Since the cache files are
637architecture-specific, ``fc-cache`` runs using QEMU if the postinst
638scriptlets need to be run on the build host during image creation.
639
640If the fonts being installed are in packages other than the main
641package, set :term:`FONT_PACKAGES` to specify the
642packages containing the fonts.
643
644.. _ref-classes-fs-uuid:
645
646``fs-uuid.bbclass``
647===================
648
649The ``fs-uuid`` class extracts UUID from
650``${``\ :term:`ROOTFS`\ ``}``, which must have been built
651by the time that this function gets called. The ``fs-uuid`` class only
652works on ``ext`` file systems and depends on ``tune2fs``.
653
654.. _ref-classes-gconf:
655
656``gconf.bbclass``
657=================
658
659The ``gconf`` class provides common functionality for recipes that need
660to install GConf schemas. The schemas will be put into a separate
661package (``${``\ :term:`PN`\ ``}-gconf``) that is created
662automatically when this class is inherited. This package uses the
663appropriate post-install and post-remove (postinst/postrm) scriptlets to
664register and unregister the schemas in the target image.
665
666.. _ref-classes-gettext:
667
668``gettext.bbclass``
669===================
670
671The ``gettext`` class provides support for building software that uses
672the GNU ``gettext`` internationalization and localization system. All
673recipes building software that use ``gettext`` should inherit this
674class.
675
Patrick Williams975a06f2022-10-21 14:42:47 -0500676.. _ref-classes-github-releases:
677
678``github-releases``
679===================
680
681For recipes that fetch release tarballs from github, the ``github-releases``
682class sets up a standard way for checking available upstream versions
683(to support ``devtool upgrade`` and the Automated Upgrade Helper (AUH)).
684
685To use it, add ``github-releases`` to the inherit line in the recipe,
686and if the default value of :term:`GITHUB_BASE_URI` is not suitable,
687then set your own value in the recipe. You should then use ``${GITHUB_BASE_URI}``
688in the value you set for :term:`SRC_URI` within the recipe.
689
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500690.. _ref-classes-gnomebase:
691
692``gnomebase.bbclass``
693=====================
694
695The ``gnomebase`` class is the base class for recipes that build
696software from the GNOME stack. This class sets
697:term:`SRC_URI` to download the source from the GNOME
698mirrors as well as extending :term:`FILES` with the typical
699GNOME installation paths.
700
701.. _ref-classes-gobject-introspection:
702
703``gobject-introspection.bbclass``
704=================================
705
706Provides support for recipes building software that supports GObject
707introspection. This functionality is only enabled if the
708"gobject-introspection-data" feature is in
709:term:`DISTRO_FEATURES` as well as
710"qemu-usermode" being in
711:term:`MACHINE_FEATURES`.
712
713.. note::
714
715 This functionality is backfilled by default and, if not applicable,
Andrew Geissler09036742021-06-25 14:25:14 -0500716 should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
717 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500718
719.. _ref-classes-grub-efi:
720
721``grub-efi.bbclass``
722====================
723
724The ``grub-efi`` class provides ``grub-efi``-specific functions for
725building bootable images.
726
727This class supports several variables:
728
729- :term:`INITRD`: Indicates list of filesystem images to
730 concatenate and use as an initial RAM disk (initrd) (optional).
731
732- :term:`ROOTFS`: Indicates a filesystem image to include
733 as the root filesystem (optional).
734
735- :term:`GRUB_GFXSERIAL`: Set this to "1" to have
736 graphics and serial in the boot menu.
737
738- :term:`LABELS`: A list of targets for the automatic
739 configuration.
740
741- :term:`APPEND`: An override list of append strings for
742 each ``LABEL``.
743
744- :term:`GRUB_OPTS`: Additional options to add to the
745 configuration (optional). Options are delimited using semi-colon
746 characters (``;``).
747
748- :term:`GRUB_TIMEOUT`: Timeout before executing
749 the default ``LABEL`` (optional).
750
751.. _ref-classes-gsettings:
752
753``gsettings.bbclass``
754=====================
755
756The ``gsettings`` class provides common functionality for recipes that
757need to install GSettings (glib) schemas. The schemas are assumed to be
758part of the main package. Appropriate post-install and post-remove
759(postinst/postrm) scriptlets are added to register and unregister the
760schemas in the target image.
761
762.. _ref-classes-gtk-doc:
763
764``gtk-doc.bbclass``
765===================
766
767The ``gtk-doc`` class is a helper class to pull in the appropriate
768``gtk-doc`` dependencies and disable ``gtk-doc``.
769
770.. _ref-classes-gtk-icon-cache:
771
772``gtk-icon-cache.bbclass``
773==========================
774
775The ``gtk-icon-cache`` class generates the proper post-install and
776post-remove (postinst/postrm) scriptlets for packages that use GTK+ and
777install icons. These scriptlets call ``gtk-update-icon-cache`` to add
778the fonts to GTK+'s icon cache. Since the cache files are
779architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if
780the postinst scriptlets need to be run on the build host during image
781creation.
782
783.. _ref-classes-gtk-immodules-cache:
784
785``gtk-immodules-cache.bbclass``
786===============================
787
788The ``gtk-immodules-cache`` class generates the proper post-install and
789post-remove (postinst/postrm) scriptlets for packages that install GTK+
790input method modules for virtual keyboards. These scriptlets call
791``gtk-update-icon-cache`` to add the input method modules to the cache.
792Since the cache files are architecture-specific,
793``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets
794need to be run on the build host during image creation.
795
796If the input method modules being installed are in packages other than
797the main package, set
798:term:`GTKIMMODULES_PACKAGES` to specify
799the packages containing the modules.
800
801.. _ref-classes-gzipnative:
802
803``gzipnative.bbclass``
804======================
805
806The ``gzipnative`` class enables the use of different native versions of
807``gzip`` and ``pigz`` rather than the versions of these tools from the
808build host.
809
810.. _ref-classes-icecc:
811
812``icecc.bbclass``
813=================
814
815The ``icecc`` class supports
816`Icecream <https://github.com/icecc/icecream>`__, which facilitates
817taking compile jobs and distributing them among remote machines.
818
819The class stages directories with symlinks from ``gcc`` and ``g++`` to
820``icecc``, for both native and cross compilers. Depending on each
821configure or compile, the OpenEmbedded build system adds the directories
822at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500823``ICECC_CC`` variables, which are the paths to the ``g++`` and ``gcc``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500824compilers, respectively.
825
826For the cross compiler, the class creates a ``tar.gz`` file that
827contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which
828is the version of the cross-compiler used in the cross-development
829toolchain, accordingly.
830
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500831The class handles all three different compile stages (i.e native,
832cross-kernel and target) and creates the necessary environment
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500833``tar.gz`` file to be used by the remote machines. The class also
834supports SDK generation.
835
836If :term:`ICECC_PATH` is not set in your
837``local.conf`` file, then the class tries to locate the ``icecc`` binary
838using ``which``. If :term:`ICECC_ENV_EXEC` is set
839in your ``local.conf`` file, the variable should point to the
840``icecc-create-env`` script provided by the user. If you do not point to
841a user-provided script, the build system uses the default script
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500842provided by the recipe :oe_git:`icecc-create-env_0.1.bb
843</openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500844
845.. note::
846
847 This script is a modified version and not the one that comes with
Andrew Geissler87f5cff2022-09-30 13:13:31 -0500848 ``icecream``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500849
850If you do not want the Icecream distributed compile support to apply to
Andrew Geissler595f6302022-01-24 19:11:47 +0000851specific recipes or classes, you can ask them to be ignored by Icecream
852by listing the recipes and classes using the
Andrew Geissler9aee5002022-03-30 16:27:02 +0000853:term:`ICECC_RECIPE_DISABLE` and
854:term:`ICECC_CLASS_DISABLE` variables,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500855respectively, in your ``local.conf`` file. Doing so causes the
856OpenEmbedded build system to handle these compilations locally.
857
858Additionally, you can list recipes using the
Andrew Geissler9aee5002022-03-30 16:27:02 +0000859:term:`ICECC_RECIPE_ENABLE` variable in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500860your ``local.conf`` file to force ``icecc`` to be enabled for recipes
861using an empty :term:`PARALLEL_MAKE` variable.
862
863Inheriting the ``icecc`` class changes all sstate signatures.
864Consequently, if a development team has a dedicated build system that
865populates :term:`SSTATE_MIRRORS` and they want to
Andrew Geissler09036742021-06-25 14:25:14 -0500866reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500867system need to either inherit the ``icecc`` class or nobody should.
868
869At the distribution level, you can inherit the ``icecc`` class to be
870sure that all builders start with the same sstate signatures. After
871inheriting the class, you can then disable the feature by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500872:term:`ICECC_DISABLED` variable to "1" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500873
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500874 INHERIT_DISTRO:append = " icecc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500875 ICECC_DISABLED ??= "1"
876
877This practice
878makes sure everyone is using the same signatures but also requires
879individuals that do want to use Icecream to enable the feature
Andrew Geisslerc926e172021-05-07 16:11:35 -0500880individually as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500881
882 ICECC_DISABLED = ""
883
884.. _ref-classes-image:
885
886``image.bbclass``
887=================
888
889The ``image`` class helps support creating images in different formats.
890First, the root filesystem is created from packages using one of the
891``rootfs*.bbclass`` files (depending on the package format used) and
892then one or more image files are created.
893
Andrew Geissler09036742021-06-25 14:25:14 -0500894- The :term:`IMAGE_FSTYPES` variable controls the types of images to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500895 generate.
896
Andrew Geissler09036742021-06-25 14:25:14 -0500897- The :term:`IMAGE_INSTALL` variable controls the list of packages to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500898 install into the image.
899
900For information on customizing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600901":ref:`dev-manual/common-tasks:customizing images`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500902in the Yocto Project Development Tasks Manual. For information on how
903images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600904":ref:`overview-manual/concepts:images`" section in the
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600905Yocto Project Overview and Concepts Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500906
907.. _ref-classes-image-buildinfo:
908
909``image-buildinfo.bbclass``
910===========================
911
Patrick Williams975a06f2022-10-21 14:42:47 -0500912The ``image-buildinfo`` class writes a plain text file containing
913build information to the target filesystem at ``${sysconfdir}/buildinfo``
914by default (as specified by :term:`IMAGE_BUILDINFO_FILE`.
915This can be useful for manually determining the origin of any given
916image. It writes out two sections:
917
9181. `Build Configuration`: a list of variables and their values (specified
919 by :term:`IMAGE_BUILDINFO_VARS`, which defaults to :term:`DISTRO` and
920 :term:`DISTRO_VERSION`)
921
9222. `Layer Revisions`: the revisions of all of the layers used in the
923 build.
924
925Additionally, when building an SDK it will write the same contents
926to ``/buildinfo`` by default (as specified by
927:term:`SDK_BUILDINFO_FILE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500928
929.. _ref-classes-image_types:
930
931``image_types.bbclass``
932=======================
933
934The ``image_types`` class defines all of the standard image output types
935that you can enable through the
936:term:`IMAGE_FSTYPES` variable. You can use this
937class as a reference on how to add support for custom image output
938types.
939
940By default, the :ref:`image <ref-classes-image>` class automatically
941enables the ``image_types`` class. The ``image`` class uses the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500942``IMGCLASSES`` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500943
944 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
945 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
946 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
947 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
948 IMGCLASSES += "image_types_wic"
949 IMGCLASSES += "rootfs-postcommands"
950 IMGCLASSES += "image-postinst-intercepts"
951 inherit ${IMGCLASSES}
952
953The ``image_types`` class also handles conversion and compression of images.
954
955.. note::
956
957 To build a VMware VMDK image, you need to add "wic.vmdk" to
Andrew Geissler09036742021-06-25 14:25:14 -0500958 :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500959 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500960
961.. _ref-classes-image-live:
962
963``image-live.bbclass``
964======================
965
966This class controls building "live" (i.e. HDDIMG and ISO) images. Live
967images contain syslinux for legacy booting, as well as the bootloader
968specified by :term:`EFI_PROVIDER` if
969:term:`MACHINE_FEATURES` contains "efi".
970
971Normally, you do not use this class directly. Instead, you add "live" to
972:term:`IMAGE_FSTYPES`.
973
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500974.. _ref-classes-insane:
975
976``insane.bbclass``
977==================
978
979The ``insane`` class adds a step to the package generation process so
980that output quality assurance checks are generated by the OpenEmbedded
981build system. A range of checks are performed that check the build's
982output for common problems that show up during runtime. Distribution
983policy usually dictates whether to include this class.
984
985You can configure the sanity checks so that specific test failures
986either raise a warning or an error message. Typically, failures for new
987tests generate a warning. Subsequent failures for the same test would
988then generate an error message once the metadata is in a known and good
Andrew Geissler09209ee2020-12-13 08:44:15 -0600989condition. See the ":doc:`/ref-manual/qa-checks`" Chapter for a list of all the warning
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500990and error messages you might encounter using a default configuration.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500991
992Use the :term:`WARN_QA` and
993:term:`ERROR_QA` variables to control the behavior of
994these checks at the global level (i.e. in your custom distro
995configuration). However, to skip one or more checks in recipes, you
996should use :term:`INSANE_SKIP`. For example, to skip
997the check for symbolic link ``.so`` files in the main package of a
998recipe, add the following to the recipe. You need to realize that the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500999package name override, in this example ``${PN}``, must be used::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001000
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001001 INSANE_SKIP:${PN} += "dev-so"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001002
1003Please keep in mind that the QA checks
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001004are meant to detect real or potential problems in the packaged
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001005output. So exercise caution when disabling these checks.
1006
Andrew Geissler09036742021-06-25 14:25:14 -05001007Here are the tests you can list with the :term:`WARN_QA` and
Andrew Geissler5f350902021-07-23 13:09:54 -04001008:term:`ERROR_QA` variables:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001009
1010- ``already-stripped:`` Checks that produced binaries have not
1011 already been stripped prior to the build system extracting debug
1012 symbols. It is common for upstream software projects to default to
1013 stripping debug symbols for output binaries. In order for debugging
1014 to work on the target using ``-dbg`` packages, this stripping must be
1015 disabled.
1016
1017- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit
1018 size, and endianness of any binaries to ensure they match the target
1019 architecture. This test fails if any binaries do not match the type
1020 since there would be an incompatibility. The test could indicate that
1021 the wrong compiler or compiler options have been used. Sometimes
1022 software, like bootloaders, might need to bypass this check.
1023
1024- ``buildpaths:`` Checks for paths to locations on the build host
Patrick Williams975a06f2022-10-21 14:42:47 -05001025 inside the output files. Not only can these leak information about
1026 the build environment, they also hinder binary reproducibility.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001027
1028- ``build-deps:`` Determines if a build-time dependency that is
1029 specified through :term:`DEPENDS`, explicit
1030 :term:`RDEPENDS`, or task-level dependencies exists
1031 to match any runtime dependency. This determination is particularly
1032 useful to discover where runtime dependencies are detected and added
1033 during packaging. If no explicit dependency has been specified within
1034 the metadata, at the packaging stage it is too late to ensure that
1035 the dependency is built, and thus you can end up with an error when
1036 the package is installed into the image during the
1037 :ref:`ref-tasks-rootfs` task because the auto-detected
1038 dependency was not satisfied. An example of this would be where the
1039 :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically
1040 adds a dependency on the ``initscripts-functions`` package to
1041 packages that install an initscript that refers to
1042 ``/etc/init.d/functions``. The recipe should really have an explicit
Andrew Geissler5f350902021-07-23 13:09:54 -04001043 :term:`RDEPENDS` for the package in question on ``initscripts-functions``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001044 so that the OpenEmbedded build system is able to ensure that the
1045 ``initscripts`` recipe is actually built and thus the
1046 ``initscripts-functions`` package is made available.
1047
1048- ``compile-host-path:`` Checks the
1049 :ref:`ref-tasks-compile` log for indications that
1050 paths to locations on the build host were used. Using such paths
1051 might result in host contamination of the build output.
1052
1053- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
1054 do not depend on ``-dbg`` packages, which would cause a packaging
1055 bug.
1056
1057- ``debug-files:`` Checks for ``.debug`` directories in anything but
1058 the ``-dbg`` package. The debug files should all be in the ``-dbg``
1059 package. Thus, anything packaged elsewhere is incorrect packaging.
1060
1061- ``dep-cmp:`` Checks for invalid version comparison statements in
1062 runtime dependency relationships between packages (i.e. in
1063 :term:`RDEPENDS`,
1064 :term:`RRECOMMENDS`,
1065 :term:`RSUGGESTS`,
1066 :term:`RPROVIDES`,
1067 :term:`RREPLACES`, and
1068 :term:`RCONFLICTS` variable values). Any invalid
1069 comparisons might trigger failures or undesirable behavior when
1070 passed to the package manager.
1071
1072- ``desktop:`` Runs the ``desktop-file-validate`` program against any
1073 ``.desktop`` files to validate their contents against the
1074 specification for ``.desktop`` files.
1075
1076- ``dev-deps:`` Checks that all packages except ``-dev`` or
1077 ``-staticdev`` packages do not depend on ``-dev`` packages, which
1078 would be a packaging bug.
1079
1080- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
1081 ``-dev`` package and not in any of the other packages. In general,
1082 these symlinks are only useful for development purposes. Thus, the
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001083 ``-dev`` package is the correct location for them. In very rare
1084 cases, such as dynamically loaded modules, these symlinks
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001085 are needed instead in the main package.
1086
Patrick Williams03907ee2022-05-01 06:28:52 -05001087- ``empty-dirs:`` Checks that packages are not installing files to
1088 directories that are normally expected to be empty (such as ``/tmp``)
1089 The list of directories that are checked is specified by the
1090 :term:`QA_EMPTY_DIRS` variable.
1091
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001092- ``file-rdeps:`` Checks that file-level dependencies identified by
1093 the OpenEmbedded build system at packaging time are satisfied. For
1094 example, a shell script might start with the line ``#!/bin/bash``.
1095 This line would translate to a file dependency on ``/bin/bash``. Of
1096 the three package managers that the OpenEmbedded build system
1097 supports, only RPM directly handles file-level dependencies,
1098 resolving them automatically to packages providing the files.
1099 However, the lack of that functionality in the other two package
1100 managers does not mean the dependencies do not still need resolving.
1101 This QA check attempts to ensure that explicitly declared
1102 :term:`RDEPENDS` exist to handle any file-level
1103 dependency detected in packaged files.
1104
1105- ``files-invalid:`` Checks for :term:`FILES` variable
1106 values that contain "//", which is invalid.
1107
1108- ``host-user-contaminated:`` Checks that no package produced by the
1109 recipe contains any files outside of ``/home`` with a user or group
1110 ID that matches the user running BitBake. A match usually indicates
1111 that the files are being installed with an incorrect UID/GID, since
1112 target IDs are independent from host IDs. For additional information,
1113 see the section describing the
1114 :ref:`ref-tasks-install` task.
1115
1116- ``incompatible-license:`` Report when packages are excluded from
1117 being created due to being marked with a license that is in
1118 :term:`INCOMPATIBLE_LICENSE`.
1119
1120- ``install-host-path:`` Checks the
1121 :ref:`ref-tasks-install` log for indications that
1122 paths to locations on the build host were used. Using such paths
1123 might result in host contamination of the build output.
1124
1125- ``installed-vs-shipped:`` Reports when files have been installed
Patrick Williams2194f502022-10-16 14:26:09 -05001126 within :ref:`ref-tasks-install` but have not been included in any package by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001127 way of the :term:`FILES` variable. Files that do not
1128 appear in any package cannot be present in an image later on in the
1129 build process. Ideally, all installed files should be packaged or not
1130 installed at all. These files can be deleted at the end of
Patrick Williams2194f502022-10-16 14:26:09 -05001131 :ref:`ref-tasks-install` if the files are not needed in any package.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001132
1133- ``invalid-chars:`` Checks that the recipe metadata variables
1134 :term:`DESCRIPTION`,
1135 :term:`SUMMARY`, :term:`LICENSE`, and
1136 :term:`SECTION` do not contain non-UTF-8 characters.
1137 Some package managers do not support such characters.
1138
1139- ``invalid-packageconfig:`` Checks that no undefined features are
1140 being added to :term:`PACKAGECONFIG`. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05001141 example, any name "foo" for which the following form does not exist::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001142
1143 PACKAGECONFIG[foo] = "..."
1144
Andrew Geissler09036742021-06-25 14:25:14 -05001145- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001146 file containing these paths is incorrect since ``libtool`` adds the
1147 correct sysroot prefix when using the files automatically itself.
1148
1149- ``ldflags:`` Ensures that the binaries were linked with the
1150 :term:`LDFLAGS` options provided by the build system.
Andrew Geissler09036742021-06-25 14:25:14 -05001151 If this test fails, check that the :term:`LDFLAGS` variable is being
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001152 passed to the linker command.
1153
1154- ``libdir:`` Checks for libraries being installed into incorrect
1155 (possibly hardcoded) installation paths. For example, this test will
1156 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
1157 "lib32". Another example is when recipes install
1158 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
1159
1160- ``libexec:`` Checks if a package contains files in
1161 ``/usr/libexec``. This check is not performed if the ``libexecdir``
1162 variable has been set explicitly to ``/usr/libexec``.
1163
1164- ``packages-list:`` Checks for the same package being listed
1165 multiple times through the :term:`PACKAGES` variable
1166 value. Installing the package in this manner can cause errors during
1167 packaging.
1168
1169- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
1170 invalid format.
1171
1172- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
1173 invalid format.
1174
1175- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
1176 'link' where the specified target already exists.
1177
1178- ``perms:`` Currently, this check is unused but reserved.
1179
1180- ``pkgconfig:`` Checks ``.pc`` files for any
1181 :term:`TMPDIR`/:term:`WORKDIR` paths.
1182 Any ``.pc`` file containing these paths is incorrect since
1183 ``pkg-config`` itself adds the correct sysroot prefix when the files
1184 are accessed.
1185
1186- ``pkgname:`` Checks that all packages in
1187 :term:`PACKAGES` have names that do not contain
1188 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1189 -).
1190
Andrew Geissler09036742021-06-25 14:25:14 -05001191- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001192 undefined during :ref:`ref-tasks-package`.
1193
1194- ``pkgvarcheck:`` Checks through the variables
1195 :term:`RDEPENDS`,
1196 :term:`RRECOMMENDS`,
1197 :term:`RSUGGESTS`,
1198 :term:`RCONFLICTS`,
1199 :term:`RPROVIDES`,
1200 :term:`RREPLACES`, :term:`FILES`,
1201 :term:`ALLOW_EMPTY`, ``pkg_preinst``,
1202 ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if
1203 there are variable sets that are not package-specific. Using these
1204 variables without a package suffix is bad practice, and might
1205 unnecessarily complicate dependencies of other packages within the
1206 same recipe or have other unintended consequences.
1207
1208- ``pn-overrides:`` Checks that a recipe does not have a name
1209 (:term:`PN`) value that appears in
1210 :term:`OVERRIDES`. If a recipe is named such that
Andrew Geissler09036742021-06-25 14:25:14 -05001211 its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
1212 :term:`PN` happens to be the same as :term:`MACHINE` or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001213 :term:`DISTRO`), it can have unexpected consequences.
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001214 For example, assignments such as ``FILES:${PN} = "xyz"`` effectively
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001215 turn into ``FILES = "xyz"``.
1216
1217- ``rpaths:`` Checks for rpaths in the binaries that contain build
Andrew Geissler5f350902021-07-23 13:09:54 -04001218 system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001219 options are being passed to the linker commands and your binaries
1220 have potential security issues.
1221
1222- ``split-strip:`` Reports that splitting or stripping debug symbols
1223 from binaries has failed.
1224
1225- ``staticdev:`` Checks for static library files (``*.a``) in
1226 non-``staticdev`` packages.
1227
1228- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
1229 into :term:`TMPDIR` on the host. Such symlinks will
1230 work on the host, but are clearly invalid when running on the target.
1231
1232- ``textrel:`` Checks for ELF binaries that contain relocations in
1233 their ``.text`` sections, which can result in a performance impact at
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001234 runtime. See the explanation for the ``ELF binary`` message in
Andrew Geissler09209ee2020-12-13 08:44:15 -06001235 ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001236 issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001237
1238- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
1239 for a package are also declared on the recipe level (i.e. any license
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001240 in ``LICENSE:*`` should appear in :term:`LICENSE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001241
1242- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
1243 in the binaries that by default on a standard system are searched by
1244 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
1245 not cause any breakage, they do waste space and are unnecessary.
1246
1247- ``var-undefined:`` Reports when variables fundamental to packaging
1248 (i.e. :term:`WORKDIR`,
1249 :term:`DEPLOY_DIR`, :term:`D`,
1250 :term:`PN`, and :term:`PKGD`) are undefined
1251 during :ref:`ref-tasks-package`.
1252
1253- ``version-going-backwards:`` If Build History is enabled, reports
1254 when a package being written out has a lower version than the
1255 previously written package under the same name. If you are placing
1256 output packages into a feed and upgrading packages on a target system
1257 using that feed, the version of a package going backwards can result
1258 in the target system not correctly upgrading to the "new" version of
1259 the package.
1260
1261 .. note::
1262
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001263 This is only relevant when you are using runtime package management
1264 on your target system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001265
1266- ``xorg-driver-abi:`` Checks that all packages containing Xorg
1267 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
1268 driver ABI names. All drivers should depend on the ABI versions that
1269 they have been built against. Driver recipes that include
1270 ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
1271 automatically get these versions. Consequently, you should only need
1272 to explicitly add dependencies to binary driver recipes.
1273
1274.. _ref-classes-insserv:
1275
1276``insserv.bbclass``
1277===================
1278
1279The ``insserv`` class uses the ``insserv`` utility to update the order
1280of symbolic links in ``/etc/rc?.d/`` within an image based on
1281dependencies specified by LSB headers in the ``init.d`` scripts
1282themselves.
1283
1284.. _ref-classes-kernel:
1285
1286``kernel.bbclass``
1287==================
1288
1289The ``kernel`` class handles building Linux kernels. The class contains
1290code to build all kernel trees. All needed headers are staged into the
Andrew Geissler5f350902021-07-23 13:09:54 -04001291:term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001292using the :ref:`module <ref-classes-module>` class.
1293
1294This means that each built kernel module is packaged separately and
1295inter-module dependencies are created by parsing the ``modinfo`` output.
1296If all modules are required, then installing the ``kernel-modules``
1297package installs all packages with modules and various other kernel
1298packages such as ``kernel-vmlinux``.
1299
1300The ``kernel`` class contains logic that allows you to embed an initial
Patrick Williams2194f502022-10-16 14:26:09 -05001301RAM filesystem (:term:`Initramfs`) image when you build the kernel image. For
1302information on how to build an :term:`Initramfs`, see the
1303":ref:`dev-manual/common-tasks:building an initial ram filesystem (Initramfs) image`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001304the Yocto Project Development Tasks Manual.
1305
1306Various other classes are used by the ``kernel`` and ``module`` classes
1307internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`,
1308:ref:`module-base <ref-classes-module-base>`, and
1309:ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes.
1310
1311.. _ref-classes-kernel-arch:
1312
1313``kernel-arch.bbclass``
1314=======================
1315
1316The ``kernel-arch`` class sets the ``ARCH`` environment variable for
1317Linux kernel compilation (including modules).
1318
1319.. _ref-classes-kernel-devicetree:
1320
1321``kernel-devicetree.bbclass``
1322=============================
1323
1324The ``kernel-devicetree`` class, which is inherited by the
1325:ref:`kernel <ref-classes-kernel>` class, supports device tree
1326generation.
1327
1328.. _ref-classes-kernel-fitimage:
1329
1330``kernel-fitimage.bbclass``
1331===========================
1332
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001333The ``kernel-fitimage`` class provides support to pack a kernel image,
1334device trees, a U-boot script, a Initramfs bundle and a RAM disk
1335into a single FIT image. In theory, a FIT image can support any number
1336of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001337However, ``kernel-fitimage`` currently only supports
Patrick Williams975a06f2022-10-21 14:42:47 -05001338limited usecases: just one kernel image, an optional U-boot script,
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001339an optional Initramfs bundle, an optional RAM disk, and any number of
1340device tree.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001341
1342To create a FIT image, it is required that :term:`KERNEL_CLASSES`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001343is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001344is set to "fitImage".
1345
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001346The options for the device tree compiler passed to ``mkimage -D``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001347when creating the FIT image are specified using the
1348:term:`UBOOT_MKIMAGE_DTCOPTS` variable.
1349
1350Only a single kernel can be added to the FIT image created by
1351``kernel-fitimage`` and the kernel image in FIT is mandatory. The
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001352address where the kernel image is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001353specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by
1354:term:`UBOOT_ENTRYPOINT`.
1355
1356Multiple device trees can be added to the FIT image created by
1357``kernel-fitimage`` and the device tree is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001358The address where the device tree is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001359specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001360and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001361
1362Only a single RAM disk can be added to the FIT image created by
1363``kernel-fitimage`` and the RAM disk in FIT is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001364The address where the RAM disk image is to be loaded by U-Boot
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001365is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
1366:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001367:term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE`
1368is set to 0.
1369
1370Only a single Initramfs bundle can be added to the FIT image created by
1371``kernel-fitimage`` and the Initramfs bundle in FIT is optional.
Andrew Geissler595f6302022-01-24 19:11:47 +00001372In case of Initramfs, the kernel is configured to be bundled with the root filesystem
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001373in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin).
Andrew Geissler595f6302022-01-24 19:11:47 +00001374When the kernel is copied to RAM and executed, it unpacks the Initramfs root filesystem.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001375The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE`
1376is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1.
1377The address where the Initramfs bundle is to be loaded by U-boot is specified
1378by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`.
1379
1380Only a single U-boot boot script can be added to the FIT image created by
1381``kernel-fitimage`` and the boot script is optional.
1382The boot script is specified in the ITS file as a text file containing
1383U-boot commands. When using a boot script the user should configure the
Patrick Williams2194f502022-10-16 14:26:09 -05001384U-boot :ref:`ref-tasks-install` task to copy the script to sysroot.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001385So the script can be included in the FIT image by the ``kernel-fitimage``
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001386class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
1387load the boot script from the FIT image and executes it.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001388
1389The FIT image generated by ``kernel-fitimage`` class is signed when the
1390variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
1391:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
1392appropriately. The default values used for :term:`FIT_HASH_ALG` and
1393:term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05001394"rsa2048" respectively. The keys for signing fitImage can be generated using
1395the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and
1396:term:`UBOOT_SIGN_ENABLE` are set to "1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001397
1398
1399.. _ref-classes-kernel-grub:
1400
1401``kernel-grub.bbclass``
1402=======================
1403
1404The ``kernel-grub`` class updates the boot area and the boot menu with
1405the kernel as the priority boot mechanism while installing a RPM to
1406update the kernel on a deployed target.
1407
1408.. _ref-classes-kernel-module-split:
1409
1410``kernel-module-split.bbclass``
1411===============================
1412
1413The ``kernel-module-split`` class provides common functionality for
1414splitting Linux kernel modules into separate packages.
1415
1416.. _ref-classes-kernel-uboot:
1417
1418``kernel-uboot.bbclass``
1419========================
1420
1421The ``kernel-uboot`` class provides support for building from
1422vmlinux-style kernel sources.
1423
1424.. _ref-classes-kernel-uimage:
1425
1426``kernel-uimage.bbclass``
1427=========================
1428
1429The ``kernel-uimage`` class provides support to pack uImage.
1430
1431.. _ref-classes-kernel-yocto:
1432
1433``kernel-yocto.bbclass``
1434========================
1435
1436The ``kernel-yocto`` class provides common functionality for building
1437from linux-yocto style kernel source repositories.
1438
1439.. _ref-classes-kernelsrc:
1440
1441``kernelsrc.bbclass``
1442=====================
1443
1444The ``kernelsrc`` class sets the Linux kernel source and version.
1445
1446.. _ref-classes-lib_package:
1447
1448``lib_package.bbclass``
1449=======================
1450
1451The ``lib_package`` class supports recipes that build libraries and
1452produce executable binaries, where those binaries should not be
1453installed by default along with the library. Instead, the binaries are
1454added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to
1455make their installation optional.
1456
1457.. _ref-classes-libc*:
1458
1459``libc*.bbclass``
1460=================
1461
1462The ``libc*`` classes support recipes that build packages with ``libc``:
1463
1464- The ``libc-common`` class provides common support for building with
1465 ``libc``.
1466
1467- The ``libc-package`` class supports packaging up ``glibc`` and
1468 ``eglibc``.
1469
1470.. _ref-classes-license:
1471
1472``license.bbclass``
1473===================
1474
1475The ``license`` class provides license manifest creation and license
1476exclusion. This class is enabled by default using the default value for
1477the :term:`INHERIT_DISTRO` variable.
1478
1479.. _ref-classes-linux-kernel-base:
1480
1481``linux-kernel-base.bbclass``
1482=============================
1483
1484The ``linux-kernel-base`` class provides common functionality for
1485recipes that build out of the Linux kernel source tree. These builds
1486goes beyond the kernel itself. For example, the Perf recipe also
1487inherits this class.
1488
1489.. _ref-classes-linuxloader:
1490
1491``linuxloader.bbclass``
1492=======================
1493
1494Provides the function ``linuxloader()``, which gives the value of the
1495dynamic loader/linker provided on the platform. This value is used by a
1496number of other classes.
1497
1498.. _ref-classes-logging:
1499
1500``logging.bbclass``
1501===================
1502
1503The ``logging`` class provides the standard shell functions used to log
1504messages for various BitBake severity levels (i.e. ``bbplain``,
1505``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``).
1506
1507This class is enabled by default since it is inherited by the ``base``
1508class.
1509
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001510.. _ref-classes-metadata_scm:
1511
1512``metadata_scm.bbclass``
1513========================
1514
1515The ``metadata_scm`` class provides functionality for querying the
1516branch and revision of a Source Code Manager (SCM) repository.
1517
1518The :ref:`base <ref-classes-base>` class uses this class to print the
1519revisions of each layer before starting every build. The
1520``metadata_scm`` class is enabled by default because it is inherited by
1521the ``base`` class.
1522
1523.. _ref-classes-migrate_localcount:
1524
1525``migrate_localcount.bbclass``
1526==============================
1527
1528The ``migrate_localcount`` class verifies a recipe's localcount data and
1529increments it appropriately.
1530
1531.. _ref-classes-mime:
1532
1533``mime.bbclass``
1534================
1535
1536The ``mime`` class generates the proper post-install and post-remove
1537(postinst/postrm) scriptlets for packages that install MIME type files.
1538These scriptlets call ``update-mime-database`` to add the MIME types to
1539the shared database.
1540
1541.. _ref-classes-mirrors:
1542
1543``mirrors.bbclass``
1544===================
1545
1546The ``mirrors`` class sets up some standard
1547:term:`MIRRORS` entries for source code mirrors. These
1548mirrors provide a fall-back path in case the upstream source specified
1549in :term:`SRC_URI` within recipes is unavailable.
1550
1551This class is enabled by default since it is inherited by the
1552:ref:`base <ref-classes-base>` class.
1553
1554.. _ref-classes-module:
1555
1556``module.bbclass``
1557==================
1558
1559The ``module`` class provides support for building out-of-tree Linux
1560kernel modules. The class inherits the
1561:ref:`module-base <ref-classes-module-base>` and
1562:ref:`kernel-module-split <ref-classes-kernel-module-split>` classes,
1563and implements the :ref:`ref-tasks-compile` and
1564:ref:`ref-tasks-install` tasks. The class provides
1565everything needed to build and package a kernel module.
1566
1567For general information on out-of-tree Linux kernel modules, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001568":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001569section in the Yocto Project Linux Kernel Development Manual.
1570
1571.. _ref-classes-module-base:
1572
1573``module-base.bbclass``
1574=======================
1575
1576The ``module-base`` class provides the base functionality for building
1577Linux kernel modules. Typically, a recipe that builds software that
1578includes one or more kernel modules and has its own means of building
1579the module inherits this class as opposed to inheriting the
1580:ref:`module <ref-classes-module>` class.
1581
1582.. _ref-classes-multilib*:
1583
1584``multilib*.bbclass``
1585=====================
1586
1587The ``multilib*`` classes provide support for building libraries with
1588different target optimizations or target architectures and installing
1589them side-by-side in the same image.
1590
1591For more information on using the Multilib feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001592":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001593section in the Yocto Project Development Tasks Manual.
1594
1595.. _ref-classes-native:
1596
1597``native.bbclass``
1598==================
1599
1600The ``native`` class provides common functionality for recipes that
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001601build tools to run on the :term:`Build Host` (i.e. tools that use the compiler
1602or other tools from the build host).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001603
1604You can create a recipe that builds tools that run natively on the host
1605a couple different ways:
1606
Andrew Geisslereff27472021-10-29 15:35:00 -05001607- Create a ``myrecipe-native.bb`` recipe that inherits the ``native``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001608 class. If you use this method, you must order the inherit statement
1609 in the recipe after all other inherit statements so that the
1610 ``native`` class is inherited last.
1611
1612 .. note::
1613
1614 When creating a recipe this way, the recipe name must follow this
Andrew Geisslerc926e172021-05-07 16:11:35 -05001615 naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001616
1617 myrecipe-native.bb
1618
1619
1620 Not using this naming convention can lead to subtle problems
1621 caused by existing code that depends on that naming convention.
1622
Andrew Geisslerc926e172021-05-07 16:11:35 -05001623- Create or modify a target recipe that contains the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001624
1625 BBCLASSEXTEND = "native"
1626
1627 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001628 recipe, use ``:class-native`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001629 specify any functionality specific to the respective native or target
1630 case.
1631
1632Although applied differently, the ``native`` class is used with both
1633methods. The advantage of the second method is that you do not need to
1634have two separate recipes (assuming you need both) for native and
1635target. All common parts of the recipe are automatically shared.
1636
1637.. _ref-classes-nativesdk:
1638
1639``nativesdk.bbclass``
1640=====================
1641
1642The ``nativesdk`` class provides common functionality for recipes that
1643wish to build tools to run as part of an SDK (i.e. tools that run on
1644:term:`SDKMACHINE`).
1645
1646You can create a recipe that builds tools that run on the SDK machine a
1647couple different ways:
1648
Andrew Geisslereff27472021-10-29 15:35:00 -05001649- Create a ``nativesdk-myrecipe.bb`` recipe that inherits the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001650 ``nativesdk`` class. If you use this method, you must order the
1651 inherit statement in the recipe after all other inherit statements so
1652 that the ``nativesdk`` class is inherited last.
1653
Andrew Geisslerc926e172021-05-07 16:11:35 -05001654- Create a ``nativesdk`` variant of any recipe by adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001655
1656 BBCLASSEXTEND = "nativesdk"
1657
1658 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001659 recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001660 specify any functionality specific to the respective SDK machine or
1661 target case.
1662
1663.. note::
1664
Andrew Geisslerc926e172021-05-07 16:11:35 -05001665 When creating a recipe, you must follow this naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001666
1667 nativesdk-myrecipe.bb
1668
1669
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001670 Not doing so can lead to subtle problems because there is code that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001671 depends on the naming convention.
1672
1673Although applied differently, the ``nativesdk`` class is used with both
1674methods. The advantage of the second method is that you do not need to
1675have two separate recipes (assuming you need both) for the SDK machine
1676and the target. All common parts of the recipe are automatically shared.
1677
1678.. _ref-classes-nopackages:
1679
1680``nopackages.bbclass``
1681======================
1682
1683Disables packaging tasks for those recipes and classes where packaging
1684is not needed.
1685
1686.. _ref-classes-npm:
1687
1688``npm.bbclass``
1689===============
1690
1691Provides support for building Node.js software fetched using the `node
1692package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
1693
1694.. note::
1695
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001696 Currently, recipes inheriting this class must use the ``npm://``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001697 fetcher to have dependencies fetched and packaged automatically.
1698
1699For information on how to create NPM packages, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001700":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001701section in the Yocto Project Development Tasks Manual.
1702
1703.. _ref-classes-oelint:
1704
1705``oelint.bbclass``
1706==================
1707
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001708The ``oelint`` class is an obsolete lint checking tool available in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001709``meta/classes`` in the :term:`Source Directory`.
1710
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001711There are some classes that could be generally useful in OE-Core but
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001712are never actually used within OE-Core itself. The ``oelint`` class is
1713one such example. However, being aware of this class can reduce the
1714proliferation of different versions of similar classes across multiple
1715layers.
1716
Andrew Geissler5199d832021-09-24 16:47:35 -05001717.. _ref-classes-overlayfs:
1718
1719``overlayfs.bbclass``
1720=======================
1721
Andrew Geissler595f6302022-01-24 19:11:47 +00001722It's often desired in Embedded System design to have a read-only root filesystem.
Andrew Geissler5199d832021-09-24 16:47:35 -05001723But a lot of different applications might want to have read-write access to
1724some parts of a filesystem. It can be especially useful when your update mechanism
Andrew Geissler595f6302022-01-24 19:11:47 +00001725overwrites the whole root filesystem, but you may want your application data to be preserved
Andrew Geissler5199d832021-09-24 16:47:35 -05001726between updates. The :ref:`overlayfs <ref-classes-overlayfs>` class provides a way
1727to achieve that by means of ``overlayfs`` and at the same time keeping the base
Andrew Geissler595f6302022-01-24 19:11:47 +00001728root filesystem read-only.
Andrew Geissler5199d832021-09-24 16:47:35 -05001729
1730To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper
1731layer in your machine configuration. The underlying file system can be anything that
1732is supported by ``overlayfs``. This has to be done in your machine configuration::
1733
1734 OVERLAYFS_MOUNT_POINT[data] = "/data"
1735
1736.. note::
1737
1738 * QA checks fail to catch file existence if you redefine this variable in your recipe!
1739 * Only the existence of the systemd mount unit file is checked, not its contents.
1740 * To get more details on ``overlayfs``, its internals and supported operations, please refer
1741 to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_.
1742
1743The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
1744(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
1745
1746Then you can specify writable directories on a recipe basis (e.g. in my-application.bb)::
1747
1748 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
1749
1750To support several mount points you can use a different variable flag. Assuming we
1751want to have a writable location on the file system, but do not need that the data
Andrew Geissler595f6302022-01-24 19:11:47 +00001752survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs``
1753file system.
Andrew Geissler5199d832021-09-24 16:47:35 -05001754
1755In your machine configuration::
1756
1757 OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
1758
1759and then in your recipe::
1760
1761 OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
1762
Andrew Geissler595f6302022-01-24 19:11:47 +00001763On a practical note, your application recipe might require multiple
1764overlays to be mounted before running to avoid writing to the underlying
1765file system (which can be forbidden in case of read-only file system)
1766To achieve that :ref:`overlayfs <ref-classes-overlayfs>` provides a ``systemd``
1767helper service for mounting overlays. This helper service is named
1768``${PN}-overlays.service`` and can be depended on in your application recipe
1769(named ``application`` in the following example) ``systemd`` unit by adding
1770to the unit the following::
1771
1772 [Unit]
1773 After=application-overlays.service
1774 Requires=application-overlays.service
1775
Andrew Geissler5199d832021-09-24 16:47:35 -05001776.. note::
1777
1778 The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
Andrew Geissler595f6302022-01-24 19:11:47 +00001779 In order to get ``/etc`` in overlayfs, see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>`.
1780
1781.. _ref-classes-overlayfs-etc:
1782
1783``overlayfs-etc.bbclass``
1784=========================
1785
1786In order to have the ``/etc`` directory in overlayfs a special handling at early
1787boot stage is required. The idea is to supply a custom init script that mounts
1788``/etc`` before launching the actual init program, because the latter already
1789requires ``/etc`` to be mounted.
1790
1791Example usage in image recipe::
1792
1793 IMAGE_FEATURES += "overlayfs-etc"
1794
1795.. note::
1796
1797 This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`
1798
1799Your machine configuration should define at least the device, mount point, and file system type
1800you are going to use for ``overlayfs``::
1801
1802 OVERLAYFS_ETC_MOUNT_POINT = "/data"
1803 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
1804 OVERLAYFS_ETC_FSTYPE ?= "ext4"
1805
1806To control more mount options you should consider setting mount options
1807(``defaults`` is used by default)::
1808
1809 OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
1810
1811The class provides two options for ``/sbin/init`` generation:
1812
1813- The default option is to rename the original ``/sbin/init`` to ``/sbin/init.orig``
1814 and place the generated init under original name, i.e. ``/sbin/init``. It has an advantage
1815 that you won't need to change any kernel parameters in order to make it work,
1816 but it poses a restriction that package-management can't be used, because updating
1817 the init manager would remove the generated script.
1818
1819- If you wish to keep original init as is, you can set::
1820
1821 OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
1822
1823 Then the generated init will be named ``/sbin/preinit`` and you would need to extend your
1824 kernel parameters manually in your bootloader configuration.
Andrew Geissler5199d832021-09-24 16:47:35 -05001825
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001826.. _ref-classes-own-mirrors:
1827
1828``own-mirrors.bbclass``
1829=======================
1830
1831The ``own-mirrors`` class makes it easier to set up your own
1832:term:`PREMIRRORS` from which to first fetch source
1833before attempting to fetch it from the upstream specified in
1834:term:`SRC_URI` within each recipe.
1835
1836To use this class, inherit it globally and specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05001837:term:`SOURCE_MIRROR_URL`. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001838
1839 INHERIT += "own-mirrors"
1840 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1841
1842You can specify only a single URL
Andrew Geissler09036742021-06-25 14:25:14 -05001843in :term:`SOURCE_MIRROR_URL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001844
1845.. _ref-classes-package:
1846
1847``package.bbclass``
1848===================
1849
1850The ``package`` class supports generating packages from a build's
1851output. The core generic functionality is in ``package.bbclass``. The
1852code specific to particular package types resides in these
1853package-specific classes:
1854:ref:`package_deb <ref-classes-package_deb>`,
1855:ref:`package_rpm <ref-classes-package_rpm>`,
1856:ref:`package_ipk <ref-classes-package_ipk>`, and
1857:ref:`package_tar <ref-classes-package_tar>`.
1858
1859.. note::
1860
1861 The
1862 package_tar
1863 class is broken and not supported. It is recommended that you do not
1864 use this class.
1865
1866You can control the list of resulting package formats by using the
Andrew Geissler09036742021-06-25 14:25:14 -05001867:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001868configuration file, which is located in the :term:`Build Directory`.
1869When defining the variable, you can
1870specify one or more package types. Since images are generated from
1871packages, a packaging class is needed to enable image generation. The
1872first class listed in this variable is used for image generation.
1873
1874If you take the optional step to set up a repository (package feed) on
1875the development host that can be used by DNF, you can install packages
1876from the feed while you are running the image on the target (i.e.
1877runtime installation of packages). For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001878":ref:`dev-manual/common-tasks:using runtime package management`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001879section in the Yocto Project Development Tasks Manual.
1880
1881The package-specific class you choose can affect build-time performance
1882and has space ramifications. In general, building a package with IPK
1883takes about thirty percent less time as compared to using RPM to build
1884the same or similar package. This comparison takes into account a
1885complete build of the package with all dependencies previously built.
1886The reason for this discrepancy is because the RPM package manager
1887creates and processes more :term:`Metadata` than the IPK package
Andrew Geissler09036742021-06-25 14:25:14 -05001888manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001889"package_ipk" if you are building smaller systems.
1890
1891Before making your package manager decision, however, you should
1892consider some further things about using RPM:
1893
1894- RPM starts to provide more abilities than IPK due to the fact that it
1895 processes more Metadata. For example, this information includes
1896 individual file types, file checksum generation and evaluation on
1897 install, sparse file support, conflict detection and resolution for
1898 Multilib systems, ACID style upgrade, and repackaging abilities for
1899 rollbacks.
1900
1901- For smaller systems, the extra space used for the Berkeley Database
1902 and the amount of metadata when using RPM can affect your ability to
1903 perform on-device upgrades.
1904
1905You can find additional information on the effects of the package class
1906at these two Yocto Project mailing list links:
1907
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001908- :yocto_lists:`/pipermail/poky/2011-May/006362.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001909
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001910- :yocto_lists:`/pipermail/poky/2011-May/006363.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001911
1912.. _ref-classes-package_deb:
1913
1914``package_deb.bbclass``
1915=======================
1916
1917The ``package_deb`` class provides support for creating packages that
1918use the Debian (i.e. ``.deb``) file format. The class ensures the
1919packages are written out in a ``.deb`` file format to the
1920``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory.
1921
1922This class inherits the :ref:`package <ref-classes-package>` class and
1923is enabled through the :term:`PACKAGE_CLASSES`
1924variable in the ``local.conf`` file.
1925
1926.. _ref-classes-package_ipk:
1927
1928``package_ipk.bbclass``
1929=======================
1930
1931The ``package_ipk`` class provides support for creating packages that
1932use the IPK (i.e. ``.ipk``) file format. The class ensures the packages
1933are written out in a ``.ipk`` file format to the
1934``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory.
1935
1936This class inherits the :ref:`package <ref-classes-package>` class and
1937is enabled through the :term:`PACKAGE_CLASSES`
1938variable in the ``local.conf`` file.
1939
1940.. _ref-classes-package_rpm:
1941
1942``package_rpm.bbclass``
1943=======================
1944
1945The ``package_rpm`` class provides support for creating packages that
1946use the RPM (i.e. ``.rpm``) file format. The class ensures the packages
1947are written out in a ``.rpm`` file format to the
1948``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory.
1949
1950This class inherits the :ref:`package <ref-classes-package>` class and
1951is enabled through the :term:`PACKAGE_CLASSES`
1952variable in the ``local.conf`` file.
1953
1954.. _ref-classes-package_tar:
1955
1956``package_tar.bbclass``
1957=======================
1958
1959The ``package_tar`` class provides support for creating tarballs. The
1960class ensures the packages are written out in a tarball format to the
1961``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory.
1962
1963This class inherits the :ref:`package <ref-classes-package>` class and
1964is enabled through the :term:`PACKAGE_CLASSES`
1965variable in the ``local.conf`` file.
1966
1967.. note::
1968
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001969 You cannot specify the ``package_tar`` class first using the
Andrew Geissler09036742021-06-25 14:25:14 -05001970 :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001971 file formats for your image or SDK.
1972
1973.. _ref-classes-packagedata:
1974
1975``packagedata.bbclass``
1976=======================
1977
1978The ``packagedata`` class provides common functionality for reading
1979``pkgdata`` files found in :term:`PKGDATA_DIR`. These
1980files contain information about each output package produced by the
1981OpenEmbedded build system.
1982
1983This class is enabled by default because it is inherited by the
1984:ref:`package <ref-classes-package>` class.
1985
1986.. _ref-classes-packagegroup:
1987
1988``packagegroup.bbclass``
1989========================
1990
1991The ``packagegroup`` class sets default values appropriate for package
Andrew Geissler09036742021-06-25 14:25:14 -05001992group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001993so forth). It is highly recommended that all package group recipes
1994inherit this class.
1995
1996For information on how to use this class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001997":ref:`dev-manual/common-tasks:customizing images using custom package groups`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001998section in the Yocto Project Development Tasks Manual.
1999
2000Previously, this class was called the ``task`` class.
2001
2002.. _ref-classes-patch:
2003
2004``patch.bbclass``
2005=================
2006
2007The ``patch`` class provides all functionality for applying patches
2008during the :ref:`ref-tasks-patch` task.
2009
2010This class is enabled by default because it is inherited by the
2011:ref:`base <ref-classes-base>` class.
2012
2013.. _ref-classes-perlnative:
2014
2015``perlnative.bbclass``
2016======================
2017
2018When inherited by a recipe, the ``perlnative`` class supports using the
2019native version of Perl built by the build system rather than using the
2020version provided by the build host.
2021
Patrick Williams975a06f2022-10-21 14:42:47 -05002022.. _ref-classes-pypi:
2023
2024``pypi.bbclass``
2025================
2026
2027The ``pypi`` class sets variables appropriately for recipes that build
2028Python modules from `PyPI <https://pypi.org/>`__, the Python Package Index.
2029By default it determines the PyPI package name based upon :term:`BPN`
2030(stripping the "python-" or "python3-" prefix off if present), however in
2031some cases you may need to set it manually in the recipe by setting
2032:term:`PYPI_PACKAGE`.
2033
2034Variables set by the ``pypi`` class include :term:`SRC_URI`, :term:`SECTION`,
2035:term:`HOMEPAGE`, :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`
2036and :term:`CVE_PRODUCT`.
2037
Patrick Williams45852732022-04-02 08:58:32 -05002038.. _ref-classes-python_flit_core:
2039
2040``python_flit_core.bbclass``
2041============================
2042
2043The ``python_flit_core`` class enables building Python modules which declare
2044the `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
2045``flit_core.buildapi`` ``build-backend`` in the ``[build-system]``
2046section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
2047
2048Python modules built with ``flit_core.buildapi`` are pure Python (no
2049``C`` or ``Rust`` extensions).
2050
2051Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
2052
Andrew Geissler9aee5002022-03-30 16:27:02 +00002053.. _ref-classes-python_pep517:
2054
2055``python_pep517.bbclass``
Patrick Williams45852732022-04-02 08:58:32 -05002056=========================
Andrew Geissler9aee5002022-03-30 16:27:02 +00002057
Patrick Williams45852732022-04-02 08:58:32 -05002058The ``python_pep517`` class builds and installs a Python ``wheel`` binary
2059archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__).
Andrew Geissler9aee5002022-03-30 16:27:02 +00002060
Patrick Williams45852732022-04-02 08:58:32 -05002061Recipes wouldn't inherit this directly, instead typically another class will
Andrew Geissler615f2f12022-07-15 14:00:58 -05002062inherit this and add the relevant native dependencies.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002063
Patrick Williams45852732022-04-02 08:58:32 -05002064Examples of classes which do this are :ref:`python_flit_core
2065<ref-classes-python_flit_core>`, :ref:`python_setuptools_build_meta
2066<ref-classes-python_setuptools_build_meta>`, and :ref:`python_poetry_core
2067<ref-classes-python_poetry_core>`.
2068
2069.. _ref-classes-python_poetry_core:
2070
2071``python_poetry_core.bbclass``
2072==============================
2073
2074The ``python_poetry_core`` class enables building Python modules which use the
2075`Poetry Core <https://python-poetry.org>`__ build system.
2076
2077Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002078
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002079.. _ref-classes-pixbufcache:
2080
2081``pixbufcache.bbclass``
2082=======================
2083
2084The ``pixbufcache`` class generates the proper post-install and
2085post-remove (postinst/postrm) scriptlets for packages that install
2086pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets
2087call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache.
2088Since the cache files are architecture-specific, ``update_pixbuf_cache``
2089is run using QEMU if the postinst scriptlets need to be run on the build
2090host during image creation.
2091
2092If the pixbuf loaders being installed are in packages other than the
2093recipe's main package, set
2094:term:`PIXBUF_PACKAGES` to specify the packages
2095containing the loaders.
2096
2097.. _ref-classes-pkgconfig:
2098
2099``pkgconfig.bbclass``
2100=====================
2101
2102The ``pkgconfig`` class provides a standard way to get header and
2103library information by using ``pkg-config``. This class aims to smooth
2104integration of ``pkg-config`` into libraries that use it.
2105
2106During staging, BitBake installs ``pkg-config`` data into the
2107``sysroots/`` directory. By making use of sysroot functionality within
2108``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the
2109files.
2110
2111.. _ref-classes-populate-sdk:
2112
2113``populate_sdk.bbclass``
2114========================
2115
2116The ``populate_sdk`` class provides support for SDK-only recipes. For
2117information on advantages gained when building a cross-development
2118toolchain using the :ref:`ref-tasks-populate_sdk`
Andrew Geissler09209ee2020-12-13 08:44:15 -06002119task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002120section in the Yocto Project Application Development and the Extensible
2121Software Development Kit (eSDK) manual.
2122
2123.. _ref-classes-populate-sdk-*:
2124
2125``populate_sdk_*.bbclass``
2126==========================
2127
2128The ``populate_sdk_*`` classes support SDK creation and consist of the
2129following classes:
2130
2131- ``populate_sdk_base``: The base class supporting SDK creation under
2132 all package managers (i.e. DEB, RPM, and opkg).
2133
2134- ``populate_sdk_deb``: Supports creation of the SDK given the Debian
2135 package manager.
2136
2137- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM
2138 package manager.
2139
2140- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg
2141 (IPK format) package manager.
2142
2143- ``populate_sdk_ext``: Supports extensible SDK creation under all
2144 package managers.
2145
2146The ``populate_sdk_base`` class inherits the appropriate
2147``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on
2148:term:`IMAGE_PKGTYPE`.
2149
2150The base class ensures all source and destination directories are
2151established and then populates the SDK. After populating the SDK, the
2152``populate_sdk_base`` class constructs two sysroots:
2153``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which
2154contains the cross-compiler and associated tooling, and the target,
2155which contains a target root filesystem that is configured for the SDK
2156usage. These two images reside in :term:`SDK_OUTPUT`,
Andrew Geisslerc926e172021-05-07 16:11:35 -05002157which consists of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002158
2159 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
2160 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
2161
2162Finally, the base populate SDK class creates the toolchain environment
2163setup script, the tarball of the SDK, and the installer.
2164
2165The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and
2166``populate_sdk_ipk`` classes each support the specific type of SDK.
2167These classes are inherited by and used with the ``populate_sdk_base``
2168class.
2169
2170For more information on the cross-development toolchain generation, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06002171the ":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002172section in the Yocto Project Overview and Concepts Manual. For
2173information on advantages gained when building a cross-development
2174toolchain using the :ref:`ref-tasks-populate_sdk`
2175task, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002176":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002177section in the Yocto Project Application Development and the Extensible
2178Software Development Kit (eSDK) manual.
2179
2180.. _ref-classes-prexport:
2181
2182``prexport.bbclass``
2183====================
2184
2185The ``prexport`` class provides functionality for exporting
2186:term:`PR` values.
2187
2188.. note::
2189
2190 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002191 when using "``bitbake-prserv-tool export``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002192
2193.. _ref-classes-primport:
2194
2195``primport.bbclass``
2196====================
2197
2198The ``primport`` class provides functionality for importing
2199:term:`PR` values.
2200
2201.. note::
2202
2203 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002204 when using "``bitbake-prserv-tool import``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002205
2206.. _ref-classes-prserv:
2207
2208``prserv.bbclass``
2209==================
2210
2211The ``prserv`` class provides functionality for using a :ref:`PR
Andrew Geissler09209ee2020-12-13 08:44:15 -06002212service <dev-manual/common-tasks:working with a pr service>` in order to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002213automatically manage the incrementing of the :term:`PR`
2214variable for each recipe.
2215
2216This class is enabled by default because it is inherited by the
2217:ref:`package <ref-classes-package>` class. However, the OpenEmbedded
2218build system will not enable the functionality of this class unless
2219:term:`PRSERV_HOST` has been set.
2220
2221.. _ref-classes-ptest:
2222
2223``ptest.bbclass``
2224=================
2225
2226The ``ptest`` class provides functionality for packaging and installing
2227runtime tests for recipes that build software that provides these tests.
2228
2229This class is intended to be inherited by individual recipes. However,
2230the class' functionality is largely disabled unless "ptest" appears in
2231:term:`DISTRO_FEATURES`. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002232":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002233section in the Yocto Project Development Tasks Manual for more information
2234on ptest.
2235
2236.. _ref-classes-ptest-gnome:
2237
2238``ptest-gnome.bbclass``
2239=======================
2240
2241Enables package tests (ptests) specifically for GNOME packages, which
2242have tests intended to be executed with ``gnome-desktop-testing``.
2243
2244For information on setting up and running ptests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002245":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002246section in the Yocto Project Development Tasks Manual.
2247
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002248.. _ref-classes-python3-dir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002249
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002250``python3-dir.bbclass``
2251=======================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002252
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002253The ``python3-dir`` class provides the base version, location, and site
2254package location for Python 3.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002255
2256.. _ref-classes-python3native:
2257
2258``python3native.bbclass``
2259=========================
2260
2261The ``python3native`` class supports using the native version of Python
22623 built by the build system rather than support of the version provided
2263by the build host.
2264
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002265.. _ref-classes-python3targetconfig:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002266
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002267``python3targetconfig.bbclass``
2268===============================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002269
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002270The ``python3targetconfig`` class supports using the native version of Python
22713 built by the build system rather than support of the version provided
2272by the build host, except that the configuration for the target machine
2273is accessible (such as correct installation directories). This also adds a
2274dependency on target ``python3``, so should only be used where appropriate
2275in order to avoid unnecessarily lengthening builds.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002276
2277.. _ref-classes-qemu:
2278
2279``qemu.bbclass``
2280================
2281
2282The ``qemu`` class provides functionality for recipes that either need
2283QEMU or test for the existence of QEMU. Typically, this class is used to
2284run programs for a target system on the build host using QEMU's
2285application emulation mode.
2286
2287.. _ref-classes-recipe_sanity:
2288
2289``recipe_sanity.bbclass``
2290=========================
2291
2292The ``recipe_sanity`` class checks for the presence of any host system
2293recipe prerequisites that might affect the build (e.g. variables that
2294are set or software that is present).
2295
2296.. _ref-classes-relocatable:
2297
2298``relocatable.bbclass``
2299=======================
2300
2301The ``relocatable`` class enables relocation of binaries when they are
2302installed into the sysroot.
2303
2304This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class
2305and is used by both the :ref:`cross <ref-classes-cross>` and
2306:ref:`native <ref-classes-native>` classes.
2307
2308.. _ref-classes-remove-libtool:
2309
2310``remove-libtool.bbclass``
2311==========================
2312
2313The ``remove-libtool`` class adds a post function to the
2314:ref:`ref-tasks-install` task to remove all ``.la`` files
2315installed by ``libtool``. Removing these files results in them being
2316absent from both the sysroot and target packages.
2317
2318If a recipe needs the ``.la`` files to be installed, then the recipe can
Andrew Geisslerc926e172021-05-07 16:11:35 -05002319override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002320
2321 REMOVE_LIBTOOL_LA = "0"
2322
2323.. note::
2324
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002325 The ``remove-libtool`` class is not enabled by default.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002326
2327.. _ref-classes-report-error:
2328
2329``report-error.bbclass``
2330========================
2331
2332The ``report-error`` class supports enabling the :ref:`error reporting
Andrew Geissler09209ee2020-12-13 08:44:15 -06002333tool <dev-manual/common-tasks:using the error reporting tool>`",
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002334which allows you to submit build error information to a central database.
2335
2336The class collects debug information for recipe, recipe version, task,
2337machine, distro, build system, target system, host distro, branch,
2338commit, and log. From the information, report files using a JSON format
2339are created and stored in
2340``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2341
2342.. _ref-classes-rm-work:
2343
2344``rm_work.bbclass``
2345===================
2346
2347The ``rm_work`` class supports deletion of temporary workspace, which
2348can ease your hard drive demands during builds.
2349
2350The OpenEmbedded build system can use a substantial amount of disk space
2351during the build process. A portion of this space is the work files
2352under the ``${TMPDIR}/work`` directory for each recipe. Once the build
2353system generates the packages for a recipe, the work files for that
2354recipe are no longer needed. However, by default, the build system
2355preserves these files for inspection and possible debugging purposes. If
2356you would rather have these files deleted to save disk space as the
2357build progresses, you can enable ``rm_work`` by adding the following to
2358your ``local.conf`` file, which is found in the :term:`Build Directory`.
2359::
2360
2361 INHERIT += "rm_work"
2362
2363If you are
2364modifying and building source code out of the work directory for a
2365recipe, enabling ``rm_work`` will potentially result in your changes to
2366the source being lost. To exclude some recipes from having their work
2367directories deleted by ``rm_work``, you can add the names of the recipe
Andrew Geissler09036742021-06-25 14:25:14 -05002368or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which
Andrew Geisslerc926e172021-05-07 16:11:35 -05002369can also be set in your ``local.conf`` file. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002370
2371 RM_WORK_EXCLUDE += "busybox glibc"
2372
2373.. _ref-classes-rootfs*:
2374
2375``rootfs*.bbclass``
2376===================
2377
2378The ``rootfs*`` classes support creating the root filesystem for an
2379image and consist of the following classes:
2380
2381- The ``rootfs-postcommands`` class, which defines filesystem
2382 post-processing functions for image recipes.
2383
2384- The ``rootfs_deb`` class, which supports creation of root filesystems
2385 for images built using ``.deb`` packages.
2386
2387- The ``rootfs_rpm`` class, which supports creation of root filesystems
2388 for images built using ``.rpm`` packages.
2389
2390- The ``rootfs_ipk`` class, which supports creation of root filesystems
2391 for images built using ``.ipk`` packages.
2392
2393- The ``rootfsdebugfiles`` class, which installs additional files found
2394 on the build host directly into the root filesystem.
2395
2396The root filesystem is created from packages using one of the
2397``rootfs*.bbclass`` files as determined by the
2398:term:`PACKAGE_CLASSES` variable.
2399
2400For information on how root filesystem images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002401":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002402section in the Yocto Project Overview and Concepts Manual.
2403
2404.. _ref-classes-sanity:
2405
2406``sanity.bbclass``
2407==================
2408
2409The ``sanity`` class checks to see if prerequisite software is present
2410on the host system so that users can be notified of potential problems
2411that might affect their build. The class also performs basic user
2412configuration checks from the ``local.conf`` configuration file to
2413prevent common mistakes that cause build failures. Distribution policy
2414usually determines whether to include this class.
2415
2416.. _ref-classes-scons:
2417
2418``scons.bbclass``
2419=================
2420
2421The ``scons`` class supports recipes that need to build software that
2422uses the SCons build system. You can use the
2423:term:`EXTRA_OESCONS` variable to specify
2424additional configuration options you want to pass SCons command line.
2425
2426.. _ref-classes-sdl:
2427
2428``sdl.bbclass``
2429===============
2430
2431The ``sdl`` class supports recipes that need to build software that uses
2432the Simple DirectMedia Layer (SDL) library.
2433
Patrick Williams45852732022-04-02 08:58:32 -05002434.. _ref-classes-python_setuptools_build_meta:
Andrew Geissler9aee5002022-03-30 16:27:02 +00002435
Patrick Williams45852732022-04-02 08:58:32 -05002436``python_setuptools_build_meta.bbclass``
2437========================================
Andrew Geissler9aee5002022-03-30 16:27:02 +00002438
Patrick Williams45852732022-04-02 08:58:32 -05002439The ``python_setuptools_build_meta`` class enables building Python modules which
Andrew Geissler9aee5002022-03-30 16:27:02 +00002440declare the
2441`PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
2442``setuptools.build_meta`` ``build-backend`` in the ``[build-system]``
2443section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
2444
2445Python modules built with ``setuptools.build_meta`` can be pure Python or
2446include ``C`` or ``Rust`` extensions).
2447
Patrick Williams45852732022-04-02 08:58:32 -05002448Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002449
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002450.. _ref-classes-setuptools3:
2451
2452``setuptools3.bbclass``
2453=======================
2454
2455The ``setuptools3`` class supports Python version 3.x extensions that
Andrew Geissler9aee5002022-03-30 16:27:02 +00002456use build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and
2457have not migrated to the official ``pyproject.toml`` format). If your recipe
2458uses these build systems, the recipe needs to inherit the ``setuptools3`` class.
2459
2460 .. note::
2461
Patrick Williams2194f502022-10-16 14:26:09 -05002462 The ``setuptools3`` class :ref:`ref-tasks-compile` task now calls
Andrew Geissler9aee5002022-03-30 16:27:02 +00002463 ``setup.py bdist_wheel`` to build the ``wheel`` binary archive format
2464 (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__).
2465
2466 A consequence of this is that legacy software still using deprecated
2467 ``distutils`` from the Python standard library cannot be packaged as
2468 ``wheels``. A common solution is the replace
2469 ``from distutils.core import setup`` with ``from setuptools import setup``.
2470
2471 .. note::
2472
Patrick Williams2194f502022-10-16 14:26:09 -05002473 The ``setuptools3`` class :ref:`ref-tasks-install` task now installs the ``wheel``
Andrew Geissler9aee5002022-03-30 16:27:02 +00002474 binary archive. In current versions of ``setuptools`` the legacy ``setup.py
2475 install`` method is deprecated. If the ``setup.py`` cannot be used with
2476 wheels, for example it creates files outside of the Python module or
2477 standard entry points, then :ref:`setuptools3_legacy
2478 <ref-classes-setuptools3_legacy>` should be used.
2479
2480.. _ref-classes-setuptools3_legacy:
2481
2482``setuptools3_legacy.bbclass``
2483==============================
2484
2485The ``setuptools3_legacy`` class supports Python version 3.x extensions that use
2486build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and have
2487not migrated to the official ``pyproject.toml`` format). Unlike
2488``setuptools3.bbclass``, this uses the traditional ``setup.py`` ``build`` and
2489``install`` commands and not wheels. This use of ``setuptools`` like this is
2490`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`_
2491but still relatively common.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002492
Andrew Geissler595f6302022-01-24 19:11:47 +00002493.. _ref-classes-setuptools3-base:
2494
2495``setuptools3-base.bbclass``
2496============================
2497
2498The ``setuptools3-base`` class provides a reusable base for other classes
2499that support building Python version 3.x extensions. If you need
2500functionality that is not provided by the :ref:`setuptools3 <ref-classes-setuptools3>` class, you may
2501want to ``inherit setuptools3-base``. Some recipes do not need the tasks
2502in the :ref:`setuptools3 <ref-classes-setuptools3>` class and inherit this class instead.
2503
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002504.. _ref-classes-sign_rpm:
2505
2506``sign_rpm.bbclass``
2507====================
2508
2509The ``sign_rpm`` class supports generating signed RPM packages.
2510
2511.. _ref-classes-sip:
2512
2513``sip.bbclass``
2514===============
2515
2516The ``sip`` class supports recipes that build or package SIP-based
2517Python bindings.
2518
2519.. _ref-classes-siteconfig:
2520
2521``siteconfig.bbclass``
2522======================
2523
2524The ``siteconfig`` class provides functionality for handling site
2525configuration. The class is used by the
2526:ref:`autotools <ref-classes-autotools>` class to accelerate the
2527:ref:`ref-tasks-configure` task.
2528
2529.. _ref-classes-siteinfo:
2530
2531``siteinfo.bbclass``
2532====================
2533
2534The ``siteinfo`` class provides information about the targets that might
2535be needed by other classes or recipes.
2536
2537As an example, consider Autotools, which can require tests that must
2538execute on the target hardware. Since this is not possible in general
2539when cross compiling, site information is used to provide cached test
2540results so these tests can be skipped over but still make the correct
2541values available. The ``meta/site directory`` contains test results
2542sorted into different categories such as architecture, endianness, and
2543the ``libc`` used. Site information provides a list of files containing
Andrew Geissler09036742021-06-25 14:25:14 -05002544data relevant to the current build in the :term:`CONFIG_SITE` variable that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002545Autotools automatically picks up.
2546
Andrew Geissler09036742021-06-25 14:25:14 -05002547The class also provides variables like :term:`SITEINFO_ENDIANNESS` and
2548:term:`SITEINFO_BITS` that can be used elsewhere in the metadata.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002549
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002550.. _ref-classes-sstate:
2551
2552``sstate.bbclass``
2553==================
2554
2555The ``sstate`` class provides support for Shared State (sstate). By
2556default, the class is enabled through the
2557:term:`INHERIT_DISTRO` variable's default value.
2558
2559For more information on sstate, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002560":ref:`overview-manual/concepts:shared state cache`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002561section in the Yocto Project Overview and Concepts Manual.
2562
2563.. _ref-classes-staging:
2564
2565``staging.bbclass``
2566===================
2567
2568The ``staging`` class installs files into individual recipe work
2569directories for sysroots. The class contains the following key tasks:
2570
2571- The :ref:`ref-tasks-populate_sysroot` task,
2572 which is responsible for handing the files that end up in the recipe
2573 sysroots.
2574
2575- The
2576 :ref:`ref-tasks-prepare_recipe_sysroot`
2577 task (a "partner" task to the ``populate_sysroot`` task), which
2578 installs the files into the individual recipe work directories (i.e.
2579 :term:`WORKDIR`).
2580
2581The code in the ``staging`` class is complex and basically works in two
2582stages:
2583
2584- *Stage One:* The first stage addresses recipes that have files they
2585 want to share with other recipes that have dependencies on the
2586 originating recipe. Normally these dependencies are installed through
2587 the :ref:`ref-tasks-install` task into
Patrick Williams2194f502022-10-16 14:26:09 -05002588 ``${``\ :term:`D`\ ``}``. The :ref:`ref-tasks-populate_sysroot` task
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002589 copies a subset of these files into ``${SYSROOT_DESTDIR}``. This
2590 subset of files is controlled by the
2591 :term:`SYSROOT_DIRS`,
2592 :term:`SYSROOT_DIRS_NATIVE`, and
Andrew Geissler9aee5002022-03-30 16:27:02 +00002593 :term:`SYSROOT_DIRS_IGNORE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002594 variables.
2595
2596 .. note::
2597
2598 Additionally, a recipe can customize the files further by
Andrew Geissler09036742021-06-25 14:25:14 -05002599 declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002600 variable.
2601
2602 A shared state (sstate) object is built from these files and the
2603 files are placed into a subdirectory of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002604 :ref:`structure-build-tmp-sysroots-components`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002605 The files are scanned for hardcoded paths to the original
2606 installation location. If the location is found in text files, the
2607 hardcoded locations are replaced by tokens and a list of the files
2608 needing such replacements is created. These adjustments are referred
2609 to as "FIXMEs". The list of files that are scanned for paths is
2610 controlled by the :term:`SSTATE_SCAN_FILES`
2611 variable.
2612
2613- *Stage Two:* The second stage addresses recipes that want to use
2614 something from another recipe and declare a dependency on that recipe
2615 through the :term:`DEPENDS` variable. The recipe will
2616 have a
2617 :ref:`ref-tasks-prepare_recipe_sysroot`
2618 task and when this task executes, it creates the ``recipe-sysroot``
2619 and ``recipe-sysroot-native`` in the recipe work directory (i.e.
2620 :term:`WORKDIR`). The OpenEmbedded build system
2621 creates hard links to copies of the relevant files from
2622 ``sysroots-components`` into the recipe work directory.
2623
2624 .. note::
2625
2626 If hard links are not possible, the build system uses actual
2627 copies.
2628
2629 The build system then addresses any "FIXMEs" to paths as defined from
2630 the list created in the first stage.
2631
2632 Finally, any files in ``${bindir}`` within the sysroot that have the
2633 prefix "``postinst-``" are executed.
2634
2635 .. note::
2636
2637 Although such sysroot post installation scripts are not
2638 recommended for general use, the files do allow some issues such
2639 as user creation and module indexes to be addressed.
2640
Andrew Geissler09036742021-06-25 14:25:14 -05002641 Because recipes can have other dependencies outside of :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002642 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
2643 the sysroot creation function ``extend_recipe_sysroot`` is also added
2644 as a pre-function for those tasks whose dependencies are not through
Andrew Geissler09036742021-06-25 14:25:14 -05002645 :term:`DEPENDS` but operate similarly.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002646
2647 When installing dependencies into the sysroot, the code traverses the
2648 dependency graph and processes dependencies in exactly the same way
2649 as the dependencies would or would not be when installed from sstate.
2650 This processing means, for example, a native tool would have its
2651 native dependencies added but a target library would not have its
2652 dependencies traversed or installed. The same sstate dependency code
2653 is used so that builds should be identical regardless of whether
2654 sstate was used or not. For a closer look, see the
2655 ``setscene_depvalid()`` function in the
2656 :ref:`sstate <ref-classes-sstate>` class.
2657
2658 The build system is careful to maintain manifests of the files it
2659 installs so that any given dependency can be installed as needed. The
2660 sstate hash of the installed item is also stored so that if it
2661 changes, the build system can reinstall it.
2662
2663.. _ref-classes-syslinux:
2664
2665``syslinux.bbclass``
2666====================
2667
2668The ``syslinux`` class provides syslinux-specific functions for building
2669bootable images.
2670
2671The class supports the following variables:
2672
2673- :term:`INITRD`: Indicates list of filesystem images to
2674 concatenate and use as an initial RAM disk (initrd). This variable is
2675 optional.
2676
2677- :term:`ROOTFS`: Indicates a filesystem image to include
2678 as the root filesystem. This variable is optional.
2679
2680- :term:`AUTO_SYSLINUXMENU`: Enables creating
2681 an automatic menu when set to "1".
2682
2683- :term:`LABELS`: Lists targets for automatic
2684 configuration.
2685
2686- :term:`APPEND`: Lists append string overrides for each
2687 label.
2688
2689- :term:`SYSLINUX_OPTS`: Lists additional options
2690 to add to the syslinux file. Semicolon characters separate multiple
2691 options.
2692
2693- :term:`SYSLINUX_SPLASH`: Lists a background
2694 for the VGA boot menu when you are using the boot menu.
2695
2696- :term:`SYSLINUX_DEFAULT_CONSOLE`: Set
2697 to "console=ttyX" to change kernel boot default console.
2698
2699- :term:`SYSLINUX_SERIAL`: Sets an alternate
2700 serial port. Or, turns off serial when the variable is set with an
2701 empty string.
2702
2703- :term:`SYSLINUX_SERIAL_TTY`: Sets an
2704 alternate "console=tty..." kernel boot argument.
2705
2706.. _ref-classes-systemd:
2707
2708``systemd.bbclass``
2709===================
2710
2711The ``systemd`` class provides support for recipes that install systemd
2712unit files.
2713
2714The functionality for this class is disabled unless you have "systemd"
2715in :term:`DISTRO_FEATURES`.
2716
2717Under this class, the recipe or Makefile (i.e. whatever the recipe is
2718calling during the :ref:`ref-tasks-install` task)
2719installs unit files into
2720``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit
2721files being installed go into packages other than the main package, you
2722need to set :term:`SYSTEMD_PACKAGES` in your
2723recipe to identify the packages in which the files will be installed.
2724
2725You should set :term:`SYSTEMD_SERVICE` to the
2726name of the service file. You should also use a package name override to
2727indicate the package to which the value applies. If the value applies to
2728the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
Andrew Geisslerc926e172021-05-07 16:11:35 -05002729is an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002730
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002731 SYSTEMD_SERVICE:${PN} = "connman.service"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002732
2733Services are set up to start on boot automatically
2734unless you have set
2735:term:`SYSTEMD_AUTO_ENABLE` to "disable".
2736
2737For more information on ``systemd``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002738":ref:`dev-manual/common-tasks:selecting an initialization manager`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002739section in the Yocto Project Development Tasks Manual.
2740
2741.. _ref-classes-systemd-boot:
2742
2743``systemd-boot.bbclass``
2744========================
2745
2746The ``systemd-boot`` class provides functions specific to the
2747systemd-boot bootloader for building bootable images. This is an
2748internal class and is not intended to be used directly.
2749
2750.. note::
2751
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002752 The ``systemd-boot`` class is a result from merging the ``gummiboot`` class
2753 used in previous Yocto Project releases with the ``systemd`` project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002754
2755Set the :term:`EFI_PROVIDER` variable to
2756"systemd-boot" to use this class. Doing so creates a standalone EFI
2757bootloader that is not dependent on systemd.
2758
2759For information on more variables used and supported in this class, see
2760the :term:`SYSTEMD_BOOT_CFG`,
2761:term:`SYSTEMD_BOOT_ENTRIES`, and
2762:term:`SYSTEMD_BOOT_TIMEOUT` variables.
2763
2764You can also see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002765documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002766for more information.
2767
2768.. _ref-classes-terminal:
2769
2770``terminal.bbclass``
2771====================
2772
2773The ``terminal`` class provides support for starting a terminal session.
2774The :term:`OE_TERMINAL` variable controls which
2775terminal emulator is used for the session.
2776
2777Other classes use the ``terminal`` class anywhere a separate terminal
2778session needs to be started. For example, the
2779:ref:`patch <ref-classes-patch>` class assuming
2780:term:`PATCHRESOLVE` is set to "user", the
2781:ref:`cml1 <ref-classes-cml1>` class, and the
2782:ref:`devshell <ref-classes-devshell>` class all use the ``terminal``
2783class.
2784
Patrick Williams975a06f2022-10-21 14:42:47 -05002785.. _ref-classes-testimage:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002786
Patrick Williams975a06f2022-10-21 14:42:47 -05002787``testimage.bbclass``
2788=====================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002789
Patrick Williams975a06f2022-10-21 14:42:47 -05002790The ``testimage`` class supports running automated tests against
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002791images using QEMU and on actual hardware. The classes handle loading the
2792tests and starting the image. To use the classes, you need to perform
2793steps to set up the environment.
2794
Patrick Williams975a06f2022-10-21 14:42:47 -05002795To enable this class, add the following to your configuration::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002796
Patrick Williams975a06f2022-10-21 14:42:47 -05002797 IMAGE_CLASSES += "testimage"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002798
2799The tests are commands that run on the target system over ``ssh``. Each
2800test is written in Python and makes use of the ``unittest`` module.
2801
Patrick Williams975a06f2022-10-21 14:42:47 -05002802The ``testimage`` class runs tests on an image when called using the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002803following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002804
2805 $ bitbake -c testimage image
2806
Patrick Williams975a06f2022-10-21 14:42:47 -05002807Alternatively, if you wish to have tests automatically run for each image
2808after it is built, you can set :term:`TESTIMAGE_AUTO`::
2809
2810 TESTIMAGE_AUTO = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002811
2812For information on how to enable, run, and create new tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002813":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002814section in the Yocto Project Development Tasks Manual.
2815
2816.. _ref-classes-testsdk:
2817
2818``testsdk.bbclass``
2819===================
2820
2821This class supports running automated tests against software development
2822kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
Andrew Geisslerc926e172021-05-07 16:11:35 -05002823using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002824
2825 $ bitbake -c testsdk image
2826
2827.. note::
2828
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002829 Best practices include using :term:`IMAGE_CLASSES` rather than
2830 :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK
2831 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002832
2833.. _ref-classes-texinfo:
2834
2835``texinfo.bbclass``
2836===================
2837
2838This class should be inherited by recipes whose upstream packages invoke
2839the ``texinfo`` utilities at build-time. Native and cross recipes are
2840made to use the dummy scripts provided by ``texinfo-dummy-native``, for
2841improved performance. Target architecture recipes use the genuine
2842Texinfo utilities. By default, they use the Texinfo utilities on the
2843host system.
2844
2845.. note::
2846
2847 If you want to use the Texinfo recipe shipped with the build system,
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002848 you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo
2849 from :term:`SANITY_REQUIRED_UTILITIES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002850
2851.. _ref-classes-toaster:
2852
2853``toaster.bbclass``
2854===================
2855
2856The ``toaster`` class collects information about packages and images and
2857sends them as events that the BitBake user interface can receive. The
2858class is enabled when the Toaster user interface is running.
2859
2860This class is not intended to be used directly.
2861
2862.. _ref-classes-toolchain-scripts:
2863
2864``toolchain-scripts.bbclass``
2865=============================
2866
2867The ``toolchain-scripts`` class provides the scripts used for setting up
2868the environment for installed SDKs.
2869
2870.. _ref-classes-typecheck:
2871
2872``typecheck.bbclass``
2873=====================
2874
2875The ``typecheck`` class provides support for validating the values of
2876variables set at the configuration level against their defined types.
2877The OpenEmbedded build system allows you to define the type of a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002878variable using the "type" varflag. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002879
2880 IMAGE_FEATURES[type] = "list"
2881
2882.. _ref-classes-uboot-config:
2883
2884``uboot-config.bbclass``
2885========================
2886
2887The ``uboot-config`` class provides support for U-Boot configuration for
Andrew Geisslerc926e172021-05-07 16:11:35 -05002888a machine. Specify the machine in your recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002889
2890 UBOOT_CONFIG ??= <default>
2891 UBOOT_CONFIG[foo] = "config,images"
2892
Andrew Geisslerc926e172021-05-07 16:11:35 -05002893You can also specify the machine using this method::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002894
2895 UBOOT_MACHINE = "config"
2896
2897See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
2898information.
2899
2900.. _ref-classes-uninative:
2901
2902``uninative.bbclass``
2903=====================
2904
2905Attempts to isolate the build system from the host distribution's C
2906library in order to make re-use of native shared state artifacts across
2907different host distributions practical. With this class enabled, a
2908tarball containing a pre-built C library is downloaded at the start of
2909the build. In the Poky reference distribution this is enabled by default
2910through ``meta/conf/distro/include/yocto-uninative.inc``. Other
2911distributions that do not derive from poky can also
2912"``require conf/distro/include/yocto-uninative.inc``" to use this.
2913Alternatively if you prefer, you can build the uninative-tarball recipe
2914yourself, publish the resulting tarball (e.g. via HTTP) and set
2915``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an
2916example, see the ``meta/conf/distro/include/yocto-uninative.inc``.
2917
2918The ``uninative`` class is also used unconditionally by the extensible
2919SDK. When building the extensible SDK, ``uninative-tarball`` is built
2920and the resulting tarball is included within the SDK.
2921
2922.. _ref-classes-update-alternatives:
2923
2924``update-alternatives.bbclass``
2925===============================
2926
2927The ``update-alternatives`` class helps the alternatives system when
2928multiple sources provide the same command. This situation occurs when
2929several programs that have the same or similar function are installed
2930with the same name. For example, the ``ar`` command is available from
2931the ``busybox``, ``binutils`` and ``elfutils`` packages. The
2932``update-alternatives`` class handles renaming the binaries so that
2933multiple packages can be installed without conflicts. The ``ar`` command
2934still works regardless of which packages are installed or subsequently
2935removed. The class renames the conflicting binary in each package and
2936symlinks the highest priority binary during installation or removal of
2937packages.
2938
2939To use this class, you need to define a number of variables:
2940
2941- :term:`ALTERNATIVE`
2942
2943- :term:`ALTERNATIVE_LINK_NAME`
2944
2945- :term:`ALTERNATIVE_TARGET`
2946
2947- :term:`ALTERNATIVE_PRIORITY`
2948
2949These variables list alternative commands needed by a package, provide
2950pathnames for links, default links for targets, and so forth. For
2951details on how to use this class, see the comments in the
Patrick Williams975a06f2022-10-21 14:42:47 -05002952:yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes-recipe/update-alternatives.bbclass>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002953file.
2954
2955.. note::
2956
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002957 You can use the ``update-alternatives`` command directly in your recipes.
2958 However, this class simplifies things in most cases.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002959
2960.. _ref-classes-update-rc.d:
2961
2962``update-rc.d.bbclass``
2963=======================
2964
2965The ``update-rc.d`` class uses ``update-rc.d`` to safely install an
2966initialization script on behalf of the package. The OpenEmbedded build
2967system takes care of details such as making sure the script is stopped
2968before a package is removed and started when the package is installed.
2969
Andrew Geissler09036742021-06-25 14:25:14 -05002970Three variables control this class: :term:`INITSCRIPT_PACKAGES`,
2971:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002972for details.
2973
2974.. _ref-classes-useradd:
2975
2976``useradd*.bbclass``
2977====================
2978
2979The ``useradd*`` classes support the addition of users or groups for
2980usage by the package on the target. For example, if you have packages
2981that contain system services that should be run under their own user or
2982group, you can use these classes to enable creation of the user or
Andrew Geissler595f6302022-01-24 19:11:47 +00002983group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb
2984</openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002985recipe in the :term:`Source Directory` provides a simple
2986example that shows how to add three users and groups to two packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002987
2988The ``useradd_base`` class provides basic functionality for user or
2989groups settings.
2990
2991The ``useradd*`` classes support the
2992:term:`USERADD_PACKAGES`,
2993:term:`USERADD_PARAM`,
2994:term:`GROUPADD_PARAM`, and
2995:term:`GROUPMEMS_PARAM` variables.
2996
2997The ``useradd-staticids`` class supports the addition of users or groups
2998that have static user identification (``uid``) and group identification
2999(``gid``) values.
3000
3001The default behavior of the OpenEmbedded build system for assigning
3002``uid`` and ``gid`` values when packages add users and groups during
3003package install time is to add them dynamically. This works fine for
3004programs that do not care what the values of the resulting users and
3005groups become. In these cases, the order of the installation determines
3006the final ``uid`` and ``gid`` values. However, if non-deterministic
3007``uid`` and ``gid`` values are a problem, you can override the default,
3008dynamic application of these values by setting static values. When you
3009set static values, the OpenEmbedded build system looks in
3010:term:`BBPATH` for ``files/passwd`` and ``files/group``
3011files for the values.
3012
3013To use static ``uid`` and ``gid`` values, you need to set some
3014variables. See the :term:`USERADDEXTENSION`,
3015:term:`USERADD_UID_TABLES`,
3016:term:`USERADD_GID_TABLES`, and
3017:term:`USERADD_ERROR_DYNAMIC` variables.
3018You can also see the :ref:`useradd <ref-classes-useradd>` class for
3019additional information.
3020
3021.. note::
3022
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003023 You do not use the ``useradd-staticids`` class directly. You either enable
Andrew Geissler09036742021-06-25 14:25:14 -05003024 or disable the class by setting the :term:`USERADDEXTENSION` variable. If you
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003025 enable or disable the class in a configured system, :term:`TMPDIR` might
Andrew Geissler09036742021-06-25 14:25:14 -05003026 contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003027 directory will correct this condition.
3028
3029.. _ref-classes-utility-tasks:
3030
3031``utility-tasks.bbclass``
3032=========================
3033
3034The ``utility-tasks`` class provides support for various "utility" type
3035tasks that are applicable to all recipes, such as
3036:ref:`ref-tasks-clean` and
3037:ref:`ref-tasks-listtasks`.
3038
3039This class is enabled by default because it is inherited by the
3040:ref:`base <ref-classes-base>` class.
3041
3042.. _ref-classes-utils:
3043
3044``utils.bbclass``
3045=================
3046
3047The ``utils`` class provides some useful Python functions that are
3048typically used in inline Python expressions (e.g. ``${@...}``). One
3049example use is for ``bb.utils.contains()``.
3050
3051This class is enabled by default because it is inherited by the
3052:ref:`base <ref-classes-base>` class.
3053
3054.. _ref-classes-vala:
3055
3056``vala.bbclass``
3057================
3058
3059The ``vala`` class supports recipes that need to build software written
3060using the Vala programming language.
3061
3062.. _ref-classes-waf:
3063
3064``waf.bbclass``
3065===============
3066
3067The ``waf`` class supports recipes that need to build software that uses
3068the Waf build system. You can use the
3069:term:`EXTRA_OECONF` or
3070:term:`PACKAGECONFIG_CONFARGS` variables
3071to specify additional configuration options to be passed on the Waf
3072command line.