blob: 729aa259e02b4ce7a6750408e5c07d1bb5017adc [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3*******
4Classes
5*******
6
7Class files are used to abstract common functionality and share it
8amongst multiple recipe (``.bb``) files. To use a class file, you simply
9make sure the recipe inherits the class. In most cases, when a recipe
10inherits a class it is enough to enable its features. There are cases,
11however, where in the recipe you might need to set variables or override
12some default behavior.
13
14Any :term:`Metadata` usually found in a recipe can also be
15placed in a class file. Class files are identified by the extension
16``.bbclass`` and are usually placed in a ``classes/`` directory beneath
17the ``meta*/`` directory found in the :term:`Source Directory`.
18Class files can also be pointed to by
19:term:`BUILDDIR` (e.g. ``build/``) in the same way as
20``.conf`` files in the ``conf`` directory. Class files are searched for
21in :term:`BBPATH` using the same method by which ``.conf``
22files are searched.
23
24This chapter discusses only the most useful and important classes. Other
25classes do exist within the ``meta/classes`` directory in the Source
26Directory. You can reference the ``.bbclass`` files directly for more
27information.
28
29.. _ref-classes-allarch:
30
31``allarch.bbclass``
32===================
33
34The ``allarch`` class is inherited by recipes that do not produce
35architecture-specific output. The class disables functionality that is
36normally needed for recipes that produce executable binaries (such as
37building the cross-compiler and a C library as pre-requisites, and
38splitting out of debug symbols during packaging).
39
40.. note::
41
42 Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes that
43 produce packages that depend on tunings through use of the
44 :term:`RDEPENDS` and
45 :term:`TUNE_PKGARCH` variables, should never be
46 configured for all architectures using ``allarch``. This is the case
47 even if the recipes do not produce architecture-specific output.
48
49 Configuring such recipes for all architectures causes the
Andrew Geissler4c19ea12020-10-27 13:52:24 -050050 ``do_package_write_*`` tasks to
Andrew Geisslerc9f78652020-09-18 14:11:35 -050051 have different signatures for the machines with different tunings.
52 Additionally, unnecessary rebuilds occur every time an image for a
Andrew Geissler09036742021-06-25 14:25:14 -050053 different :term:`MACHINE` is built even when the recipe never changes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050054
55By default, all recipes inherit the :ref:`base <ref-classes-base>` and
56:ref:`package <ref-classes-package>` classes, which enable
57functionality needed for recipes that produce executable output. If your
58recipe, for example, only produces packages that contain configuration
59files, media files, or scripts (e.g. Python and Perl), then it should
60inherit the ``allarch`` class.
61
62.. _ref-classes-archiver:
63
64``archiver.bbclass``
65====================
66
67The ``archiver`` class supports releasing source code and other
68materials with the binaries.
69
70For more details on the source archiver, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060071":ref:`dev-manual/common-tasks:maintaining open source license compliance during your product's lifecycle`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072section in the Yocto Project Development Tasks Manual. You can also see
73the :term:`ARCHIVER_MODE` variable for information
74about the variable flags (varflags) that help control archive creation.
75
76.. _ref-classes-autotools:
77
78``autotools*.bbclass``
79======================
80
Patrick Williams03907ee2022-05-01 06:28:52 -050081The ``autotools*`` classes support packages built with the
82`GNU Autotools <https://en.wikipedia.org/wiki/GNU_Autotools>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050083
84The ``autoconf``, ``automake``, and ``libtool`` packages bring
85standardization. This class defines a set of tasks (e.g. ``configure``,
86``compile`` and so forth) that work for all Autotooled packages. It
87should usually be enough to define a few standard variables and then
88simply ``inherit autotools``. These classes can also work with software
89that emulates Autotools. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -060090":ref:`dev-manual/common-tasks:autotooled package`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -050091in the Yocto Project Development Tasks Manual.
92
93By default, the ``autotools*`` classes use out-of-tree builds (i.e.
94``autotools.bbclass`` building with ``B != S``).
95
96If the software being built by a recipe does not support using
97out-of-tree builds, you should have the recipe inherit the
98``autotools-brokensep`` class. The ``autotools-brokensep`` class behaves
99the same as the ``autotools`` class but builds with :term:`B`
100== :term:`S`. This method is useful when out-of-tree build
101support is either not present or is broken.
102
103.. note::
104
105 It is recommended that out-of-tree support be fixed and used if at
106 all possible.
107
108It's useful to have some idea of how the tasks defined by the
109``autotools*`` classes work and what they do behind the scenes.
110
111- :ref:`ref-tasks-configure` - Regenerates the
112 configure script (using ``autoreconf``) and then launches it with a
113 standard set of arguments used during cross-compilation. You can pass
Andrew Geissler09036742021-06-25 14:25:14 -0500114 additional parameters to ``configure`` through the :term:`EXTRA_OECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500115 or :term:`PACKAGECONFIG_CONFARGS`
116 variables.
117
118- :ref:`ref-tasks-compile` - Runs ``make`` with
119 arguments that specify the compiler and linker. You can pass
Andrew Geissler5f350902021-07-23 13:09:54 -0400120 additional arguments through the :term:`EXTRA_OEMAKE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500121
122- :ref:`ref-tasks-install` - Runs ``make install`` and
123 passes in ``${``\ :term:`D`\ ``}`` as ``DESTDIR``.
124
125.. _ref-classes-base:
126
127``base.bbclass``
128================
129
130The ``base`` class is special in that every ``.bb`` file implicitly
131inherits the class. This class contains definitions for standard basic
132tasks such as fetching, unpacking, configuring (empty by default),
133compiling (runs any ``Makefile`` present), installing (empty by default)
134and packaging (empty by default). These classes are often overridden or
135extended by other classes such as the
136:ref:`autotools <ref-classes-autotools>` class or the
137:ref:`package <ref-classes-package>` class.
138
139The class also contains some commonly used functions such as
140``oe_runmake``, which runs ``make`` with the arguments specified in
141:term:`EXTRA_OEMAKE` variable as well as the
142arguments passed directly to ``oe_runmake``.
143
144.. _ref-classes-bash-completion:
145
146``bash-completion.bbclass``
147===========================
148
149Sets up packaging and dependencies appropriate for recipes that build
150software that includes bash-completion data.
151
152.. _ref-classes-bin-package:
153
154``bin_package.bbclass``
155=======================
156
157The ``bin_package`` class is a helper class for recipes that extract the
158contents of a binary package (e.g. an RPM) and install those contents
159rather than building the binary from source. The binary package is
160extracted and new packages in the configured output package format are
161created. Extraction and installation of proprietary binaries is a good
162example use for this class.
163
164.. note::
165
166 For RPMs and other packages that do not contain a subdirectory, you
167 should specify an appropriate fetcher parameter to point to the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500168 subdirectory. For example, if BitBake is using the Git fetcher (``git://``),
169 the "subpath" parameter limits the checkout to a specific subpath
170 of the tree. Here is an example where ``${BP}`` is used so that the files
171 are extracted into the subdirectory expected by the default value of
Andrew Geissler09036742021-06-25 14:25:14 -0500172 :term:`S`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173
Andrew Geissler9aee5002022-03-30 16:27:02 +0000174 SRC_URI = "git://example.com/downloads/somepackage.rpm;branch=main;subpath=${BP}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500175
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500176 See the ":ref:`bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the BitBake User Manual for
177 more information on supported BitBake Fetchers.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500178
179.. _ref-classes-binconfig:
180
181``binconfig.bbclass``
182=====================
183
184The ``binconfig`` class helps to correct paths in shell scripts.
185
186Before ``pkg-config`` had become widespread, libraries shipped shell
187scripts to give information about the libraries and include paths needed
188to build software (usually named ``LIBNAME-config``). This class assists
189any recipe using such scripts.
190
191During staging, the OpenEmbedded build system installs such scripts into
192the ``sysroots/`` directory. Inheriting this class results in all paths
193in these scripts being changed to point into the ``sysroots/`` directory
194so that all builds that use the script use the correct directories for
195the cross compiling layout. See the
196:term:`BINCONFIG_GLOB` variable for more
197information.
198
199.. _ref-classes-binconfig-disabled:
200
201``binconfig-disabled.bbclass``
202==============================
203
204An alternative version of the :ref:`binconfig <ref-classes-binconfig>`
205class, which disables binary configuration scripts by making them return
206an error in favor of using ``pkg-config`` to query the information. The
207scripts to be disabled should be specified using the
208:term:`BINCONFIG` variable within the recipe inheriting
209the class.
210
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500211.. _ref-classes-buildhistory:
212
213``buildhistory.bbclass``
214========================
215
216The ``buildhistory`` class records a history of build output metadata,
217which can be used to detect possible regressions as well as used for
218analysis of the build output. For more information on using Build
219History, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600220":ref:`dev-manual/common-tasks:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500221section in the Yocto Project Development Tasks Manual.
222
223.. _ref-classes-buildstats:
224
225``buildstats.bbclass``
226======================
227
228The ``buildstats`` class records performance statistics about each task
229executed during the build (e.g. elapsed time, CPU usage, and I/O usage).
230
231When you use this class, the output goes into the
232:term:`BUILDSTATS_BASE` directory, which defaults
233to ``${TMPDIR}/buildstats/``. You can analyze the elapsed time using
234``scripts/pybootchartgui/pybootchartgui.py``, which produces a cascading
235chart of the entire build process and can be useful for highlighting
236bottlenecks.
237
238Collecting build statistics is enabled by default through the
239:term:`USER_CLASSES` variable from your
240``local.conf`` file. Consequently, you do not have to do anything to
241enable the class. However, if you want to disable the class, simply
Andrew Geissler09036742021-06-25 14:25:14 -0500242remove "buildstats" from the :term:`USER_CLASSES` list.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500243
244.. _ref-classes-buildstats-summary:
245
246``buildstats-summary.bbclass``
247==============================
248
249When inherited globally, prints statistics at the end of the build on
250sstate re-use. In order to function, this class requires the
251:ref:`buildstats <ref-classes-buildstats>` class be enabled.
252
253.. _ref-classes-ccache:
254
255``ccache.bbclass``
256==================
257
258The ``ccache`` class enables the C/C++ Compiler Cache for the build.
259This class is used to give a minor performance boost during the build.
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000260
261See https://ccache.samba.org/ for information on the C/C++ Compiler
262Cache, and the :oe_git:`ccache.bbclass </openembedded-core/tree/meta/classes/ccache.bbclass>`
263file for details about how to enable this mechanism in your configuration
264file, how to disable it for specific recipes, and how to share ``ccache``
265files between builds.
266
267However, using the class can lead to unexpected side-effects. Thus, using
268this class is not recommended.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500269
270.. _ref-classes-chrpath:
271
272``chrpath.bbclass``
273===================
274
275The ``chrpath`` class is a wrapper around the "chrpath" utility, which
276is used during the build process for ``nativesdk``, ``cross``, and
277``cross-canadian`` recipes to change ``RPATH`` records within binaries
278in order to make them relocatable.
279
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280.. _ref-classes-cmake:
281
282``cmake.bbclass``
283=================
284
285The ``cmake`` class allows for recipes that need to build software using
286the `CMake <https://cmake.org/overview/>`__ build system. You can use
287the :term:`EXTRA_OECMAKE` variable to specify
288additional configuration options to be passed using the ``cmake``
289command line.
290
291On the occasion that you would be installing custom CMake toolchain
292files supplied by the application being built, you should install them
293to the preferred CMake Module directory: ``${D}${datadir}/cmake/``
294Modules during
295:ref:`ref-tasks-install`.
296
297.. _ref-classes-cml1:
298
299``cml1.bbclass``
300================
301
302The ``cml1`` class provides basic support for the Linux kernel style
303build configuration system.
304
305.. _ref-classes-compress_doc:
306
307``compress_doc.bbclass``
308========================
309
310Enables compression for man pages and info pages. This class is intended
311to be inherited globally. The default compression mechanism is gz (gzip)
312but you can select an alternative mechanism by setting the
313:term:`DOC_COMPRESS` variable.
314
315.. _ref-classes-copyleft_compliance:
316
317``copyleft_compliance.bbclass``
318===============================
319
320The ``copyleft_compliance`` class preserves source code for the purposes
321of license compliance. This class is an alternative to the ``archiver``
322class and is still used by some users even though it has been deprecated
323in favor of the :ref:`archiver <ref-classes-archiver>` class.
324
325.. _ref-classes-copyleft_filter:
326
327``copyleft_filter.bbclass``
328===========================
329
330A class used by the :ref:`archiver <ref-classes-archiver>` and
331:ref:`copyleft_compliance <ref-classes-copyleft_compliance>` classes
332for filtering licenses. The ``copyleft_filter`` class is an internal
333class and is not intended to be used directly.
334
335.. _ref-classes-core-image:
336
337``core-image.bbclass``
338======================
339
340The ``core-image`` class provides common definitions for the
341``core-image-*`` image recipes, such as support for additional
342:term:`IMAGE_FEATURES`.
343
344.. _ref-classes-cpan:
345
346``cpan*.bbclass``
347=================
348
349The ``cpan*`` classes support Perl modules.
350
351Recipes for Perl modules are simple. These recipes usually only need to
352point to the source's archive and then inherit the proper class file.
353Building is split into two methods depending on which method the module
354authors used.
355
356- Modules that use old ``Makefile.PL``-based build system require
357 ``cpan.bbclass`` in their recipes.
358
359- Modules that use ``Build.PL``-based build system require using
360 ``cpan_build.bbclass`` in their recipes.
361
362Both build methods inherit the ``cpan-base`` class for basic Perl
363support.
364
365.. _ref-classes-cross:
366
367``cross.bbclass``
368=================
369
370The ``cross`` class provides support for the recipes that build the
371cross-compilation tools.
372
373.. _ref-classes-cross-canadian:
374
375``cross-canadian.bbclass``
376==========================
377
378The ``cross-canadian`` class provides support for the recipes that build
379the Canadian Cross-compilation tools for SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600380":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500381section in the Yocto Project Overview and Concepts Manual for more
382discussion on these cross-compilation tools.
383
384.. _ref-classes-crosssdk:
385
386``crosssdk.bbclass``
387====================
388
389The ``crosssdk`` class provides support for the recipes that build the
390cross-compilation tools used for building SDKs. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600391":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500392section in the Yocto Project Overview and Concepts Manual for more
393discussion on these cross-compilation tools.
394
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500395.. _ref-classes-cve-check:
396
397``cve-check.bbclass``
398=====================
399
400The ``cve-check`` class looks for known CVEs (Common Vulnerabilities
401and Exposures) while building an image. This class is meant to be
402inherited globally from a configuration file::
403
404 INHERIT += "cve-check"
405
406You can also look for vulnerabilities in specific packages by passing
407``-c cve_check`` to BitBake. You will find details in the
408":ref:`dev-manual/common-tasks:checking for vulnerabilities`"
409section in the Development Tasks Manual.
410
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500411.. _ref-classes-debian:
412
413``debian.bbclass``
414==================
415
416The ``debian`` class renames output packages so that they follow the
417Debian naming policy (i.e. ``glibc`` becomes ``libc6`` and
418``glibc-devel`` becomes ``libc6-dev``.) Renaming includes the library
419name and version as part of the package name.
420
421If a recipe creates packages for multiple libraries (shared object files
422of ``.so`` type), use the :term:`LEAD_SONAME`
423variable in the recipe to specify the library on which to apply the
424naming scheme.
425
426.. _ref-classes-deploy:
427
428``deploy.bbclass``
429==================
430
431The ``deploy`` class handles deploying files to the
432:term:`DEPLOY_DIR_IMAGE` directory. The main
433function of this class is to allow the deploy step to be accelerated by
434shared state. Recipes that inherit this class should define their own
435:ref:`ref-tasks-deploy` function to copy the files to be
436deployed to :term:`DEPLOYDIR`, and use ``addtask`` to
437add the task at the appropriate place, which is usually after
438:ref:`ref-tasks-compile` or
439:ref:`ref-tasks-install`. The class then takes care of
Andrew Geissler09036742021-06-25 14:25:14 -0500440staging the files from :term:`DEPLOYDIR` to :term:`DEPLOY_DIR_IMAGE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500441
442.. _ref-classes-devshell:
443
444``devshell.bbclass``
445====================
446
447The ``devshell`` class adds the ``do_devshell`` task. Distribution
Andrew Geissler09209ee2020-12-13 08:44:15 -0600448policy dictates whether to include this class. See the ":ref:`dev-manual/common-tasks:using a development shell`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500449section in the Yocto Project Development Tasks Manual for more
450information about using ``devshell``.
451
452.. _ref-classes-devupstream:
453
454``devupstream.bbclass``
455=======================
456
457The ``devupstream`` class uses
458:term:`BBCLASSEXTEND` to add a variant of the
459recipe that fetches from an alternative URI (e.g. Git) instead of a
Andrew Geisslerc926e172021-05-07 16:11:35 -0500460tarball. Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500461
462 BBCLASSEXTEND = "devupstream:target"
Andrew Geissler9aee5002022-03-30 16:27:02 +0000463 SRC_URI:class-devupstream = "git://git.example.com/example;branch=main"
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500464 SRCREV:class-devupstream = "abcd1234"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500465
466Adding the above statements to your recipe creates a variant that has
467:term:`DEFAULT_PREFERENCE` set to "-1".
468Consequently, you need to select the variant of the recipe to use it.
469Any development-specific adjustments can be done by using the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500470``class-devupstream`` override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500471
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500472 DEPENDS:append:class-devupstream = " gperf-native"
473 do_configure:prepend:class-devupstream() {
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500474 touch ${S}/README
475 }
476
477The class
478currently only supports creating a development variant of the target
479recipe, not ``native`` or ``nativesdk`` variants.
480
Andrew Geissler09036742021-06-25 14:25:14 -0500481The :term:`BBCLASSEXTEND` syntax (i.e. ``devupstream:target``) provides
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500482support for ``native`` and ``nativesdk`` variants. Consequently, this
483functionality can be added in a future release.
484
485Support for other version control systems such as Subversion is limited
486due to BitBake's automatic fetch dependencies (e.g.
487``subversion-native``).
488
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500489.. _ref-classes-externalsrc:
490
491``externalsrc.bbclass``
492=======================
493
494The ``externalsrc`` class supports building software from source code
495that is external to the OpenEmbedded build system. Building software
496from an external source tree means that the build system's normal fetch,
497unpack, and patch process is not used.
498
499By default, the OpenEmbedded build system uses the :term:`S`
500and :term:`B` variables to locate unpacked recipe source code
501and to build it, respectively. When your recipe inherits the
502``externalsrc`` class, you use the
503:term:`EXTERNALSRC` and
504:term:`EXTERNALSRC_BUILD` variables to
Andrew Geissler09036742021-06-25 14:25:14 -0500505ultimately define :term:`S` and :term:`B`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500506
507By default, this class expects the source code to support recipe builds
508that use the :term:`B` variable to point to the directory in
509which the OpenEmbedded build system places the generated objects built
Andrew Geissler09036742021-06-25 14:25:14 -0500510from the recipes. By default, the :term:`B` directory is set to the
511following, which is separate from the source directory (:term:`S`)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500512
Andrew Geissler5199d832021-09-24 16:47:35 -0500513 ${WORKDIR}/${BPN}-{PV}/
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500514
515See these variables for more information:
516:term:`WORKDIR`, :term:`BPN`, and
517:term:`PV`,
518
519For more information on the ``externalsrc`` class, see the comments in
520``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
521For information on how to use the
522``externalsrc`` class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600523":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500524section in the Yocto Project Development Tasks Manual.
525
526.. _ref-classes-extrausers:
527
528``extrausers.bbclass``
529======================
530
531The ``extrausers`` class allows additional user and group configuration
532to be applied at the image level. Inheriting this class either globally
533or from an image recipe allows additional user and group operations to
534be performed using the
535:term:`EXTRA_USERS_PARAMS` variable.
536
537.. note::
538
539 The user and group operations added using the
Andrew Geissler595f6302022-01-24 19:11:47 +0000540 :ref:`extrausers <ref-classes-extrausers>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500541 class are not tied to a specific recipe outside of the recipe for the
542 image. Thus, the operations can be performed across the image as a
543 whole. Use the
Andrew Geissler595f6302022-01-24 19:11:47 +0000544 :ref:`useradd <ref-classes-useradd>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500545 class to add user and group configuration to a specific recipe.
546
Andrew Geisslerc926e172021-05-07 16:11:35 -0500547Here is an example that uses this class in an image recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500548
549 inherit extrausers
550 EXTRA_USERS_PARAMS = "\
551 useradd -p '' tester; \
552 groupadd developers; \
553 userdel nobody; \
554 groupdel -g video; \
555 groupmod -g 1020 developers; \
556 usermod -s /bin/sh tester; \
557 "
558
559Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
Andrew Geissler9aee5002022-03-30 16:27:02 +0000560passwords. First on host, create the (escaped) password hash::
Andrew Geisslereff27472021-10-29 15:35:00 -0500561
Andrew Geissler9aee5002022-03-30 16:27:02 +0000562 printf "%q" $(mkpasswd -m sha256crypt tester01)
Andrew Geisslereff27472021-10-29 15:35:00 -0500563
Andrew Geissler9aee5002022-03-30 16:27:02 +0000564The resulting hash is set to a variable and used in ``useradd`` command parameters::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500565
566 inherit extrausers
Andrew Geisslereff27472021-10-29 15:35:00 -0500567 PASSWD = "\$X\$ABC123\$A-Long-Hash"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500568 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500569 useradd -p '${PASSWD}' tester-jim; \
570 useradd -p '${PASSWD}' tester-sue; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500571 "
572
Andrew Geisslereff27472021-10-29 15:35:00 -0500573Finally, here is an example that sets the root password::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500574
575 inherit extrausers
576 EXTRA_USERS_PARAMS = "\
Andrew Geisslereff27472021-10-29 15:35:00 -0500577 usermod -p '${PASSWD}' root; \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500578 "
579
Patrick Williams03907ee2022-05-01 06:28:52 -0500580.. note::
581
582 From a security perspective, hardcoding a default password is not
583 generally a good idea or even legal in some jurisdictions. It is
584 recommended that you do not do this if you are building a production
585 image.
586
587
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600588.. _ref-classes-features_check:
589
590``features_check.bbclass``
591=================================
592
593The ``features_check`` class allows individual recipes to check
594for required and conflicting
595:term:`DISTRO_FEATURES`, :term:`MACHINE_FEATURES` or :term:`COMBINED_FEATURES`.
596
597This class provides support for the following variables:
598
599- :term:`REQUIRED_DISTRO_FEATURES`
600- :term:`CONFLICT_DISTRO_FEATURES`
601- :term:`ANY_OF_DISTRO_FEATURES`
602- ``REQUIRED_MACHINE_FEATURES``
603- ``CONFLICT_MACHINE_FEATURES``
604- ``ANY_OF_MACHINE_FEATURES``
605- ``REQUIRED_COMBINED_FEATURES``
606- ``CONFLICT_COMBINED_FEATURES``
607- ``ANY_OF_COMBINED_FEATURES``
608
609If any conditions specified in the recipe using the above
610variables are not met, the recipe will be skipped, and if the
611build system attempts to build the recipe then an error will be
612triggered.
613
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500614.. _ref-classes-fontcache:
615
616``fontcache.bbclass``
617=====================
618
619The ``fontcache`` class generates the proper post-install and
620post-remove (postinst and postrm) scriptlets for font packages. These
621scriptlets call ``fc-cache`` (part of ``Fontconfig``) to add the fonts
622to the font information cache. Since the cache files are
623architecture-specific, ``fc-cache`` runs using QEMU if the postinst
624scriptlets need to be run on the build host during image creation.
625
626If the fonts being installed are in packages other than the main
627package, set :term:`FONT_PACKAGES` to specify the
628packages containing the fonts.
629
630.. _ref-classes-fs-uuid:
631
632``fs-uuid.bbclass``
633===================
634
635The ``fs-uuid`` class extracts UUID from
636``${``\ :term:`ROOTFS`\ ``}``, which must have been built
637by the time that this function gets called. The ``fs-uuid`` class only
638works on ``ext`` file systems and depends on ``tune2fs``.
639
640.. _ref-classes-gconf:
641
642``gconf.bbclass``
643=================
644
645The ``gconf`` class provides common functionality for recipes that need
646to install GConf schemas. The schemas will be put into a separate
647package (``${``\ :term:`PN`\ ``}-gconf``) that is created
648automatically when this class is inherited. This package uses the
649appropriate post-install and post-remove (postinst/postrm) scriptlets to
650register and unregister the schemas in the target image.
651
652.. _ref-classes-gettext:
653
654``gettext.bbclass``
655===================
656
657The ``gettext`` class provides support for building software that uses
658the GNU ``gettext`` internationalization and localization system. All
659recipes building software that use ``gettext`` should inherit this
660class.
661
662.. _ref-classes-gnomebase:
663
664``gnomebase.bbclass``
665=====================
666
667The ``gnomebase`` class is the base class for recipes that build
668software from the GNOME stack. This class sets
669:term:`SRC_URI` to download the source from the GNOME
670mirrors as well as extending :term:`FILES` with the typical
671GNOME installation paths.
672
673.. _ref-classes-gobject-introspection:
674
675``gobject-introspection.bbclass``
676=================================
677
678Provides support for recipes building software that supports GObject
679introspection. This functionality is only enabled if the
680"gobject-introspection-data" feature is in
681:term:`DISTRO_FEATURES` as well as
682"qemu-usermode" being in
683:term:`MACHINE_FEATURES`.
684
685.. note::
686
687 This functionality is backfilled by default and, if not applicable,
Andrew Geissler09036742021-06-25 14:25:14 -0500688 should be disabled through :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` or
689 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`, respectively.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500690
691.. _ref-classes-grub-efi:
692
693``grub-efi.bbclass``
694====================
695
696The ``grub-efi`` class provides ``grub-efi``-specific functions for
697building bootable images.
698
699This class supports several variables:
700
701- :term:`INITRD`: Indicates list of filesystem images to
702 concatenate and use as an initial RAM disk (initrd) (optional).
703
704- :term:`ROOTFS`: Indicates a filesystem image to include
705 as the root filesystem (optional).
706
707- :term:`GRUB_GFXSERIAL`: Set this to "1" to have
708 graphics and serial in the boot menu.
709
710- :term:`LABELS`: A list of targets for the automatic
711 configuration.
712
713- :term:`APPEND`: An override list of append strings for
714 each ``LABEL``.
715
716- :term:`GRUB_OPTS`: Additional options to add to the
717 configuration (optional). Options are delimited using semi-colon
718 characters (``;``).
719
720- :term:`GRUB_TIMEOUT`: Timeout before executing
721 the default ``LABEL`` (optional).
722
723.. _ref-classes-gsettings:
724
725``gsettings.bbclass``
726=====================
727
728The ``gsettings`` class provides common functionality for recipes that
729need to install GSettings (glib) schemas. The schemas are assumed to be
730part of the main package. Appropriate post-install and post-remove
731(postinst/postrm) scriptlets are added to register and unregister the
732schemas in the target image.
733
734.. _ref-classes-gtk-doc:
735
736``gtk-doc.bbclass``
737===================
738
739The ``gtk-doc`` class is a helper class to pull in the appropriate
740``gtk-doc`` dependencies and disable ``gtk-doc``.
741
742.. _ref-classes-gtk-icon-cache:
743
744``gtk-icon-cache.bbclass``
745==========================
746
747The ``gtk-icon-cache`` class generates the proper post-install and
748post-remove (postinst/postrm) scriptlets for packages that use GTK+ and
749install icons. These scriptlets call ``gtk-update-icon-cache`` to add
750the fonts to GTK+'s icon cache. Since the cache files are
751architecture-specific, ``gtk-update-icon-cache`` is run using QEMU if
752the postinst scriptlets need to be run on the build host during image
753creation.
754
755.. _ref-classes-gtk-immodules-cache:
756
757``gtk-immodules-cache.bbclass``
758===============================
759
760The ``gtk-immodules-cache`` class generates the proper post-install and
761post-remove (postinst/postrm) scriptlets for packages that install GTK+
762input method modules for virtual keyboards. These scriptlets call
763``gtk-update-icon-cache`` to add the input method modules to the cache.
764Since the cache files are architecture-specific,
765``gtk-update-icon-cache`` is run using QEMU if the postinst scriptlets
766need to be run on the build host during image creation.
767
768If the input method modules being installed are in packages other than
769the main package, set
770:term:`GTKIMMODULES_PACKAGES` to specify
771the packages containing the modules.
772
773.. _ref-classes-gzipnative:
774
775``gzipnative.bbclass``
776======================
777
778The ``gzipnative`` class enables the use of different native versions of
779``gzip`` and ``pigz`` rather than the versions of these tools from the
780build host.
781
782.. _ref-classes-icecc:
783
784``icecc.bbclass``
785=================
786
787The ``icecc`` class supports
788`Icecream <https://github.com/icecc/icecream>`__, which facilitates
789taking compile jobs and distributing them among remote machines.
790
791The class stages directories with symlinks from ``gcc`` and ``g++`` to
792``icecc``, for both native and cross compilers. Depending on each
793configure or compile, the OpenEmbedded build system adds the directories
794at the head of the ``PATH`` list and then sets the ``ICECC_CXX`` and
795``ICEC_CC`` variables, which are the paths to the ``g++`` and ``gcc``
796compilers, respectively.
797
798For the cross compiler, the class creates a ``tar.gz`` file that
799contains the Yocto Project toolchain and sets ``ICECC_VERSION``, which
800is the version of the cross-compiler used in the cross-development
801toolchain, accordingly.
802
803The class handles all three different compile stages (i.e native
804,cross-kernel and target) and creates the necessary environment
805``tar.gz`` file to be used by the remote machines. The class also
806supports SDK generation.
807
808If :term:`ICECC_PATH` is not set in your
809``local.conf`` file, then the class tries to locate the ``icecc`` binary
810using ``which``. If :term:`ICECC_ENV_EXEC` is set
811in your ``local.conf`` file, the variable should point to the
812``icecc-create-env`` script provided by the user. If you do not point to
813a user-provided script, the build system uses the default script
814provided by the recipe ``icecc-create-env-native.bb``.
815
816.. note::
817
818 This script is a modified version and not the one that comes with
819 icecc.
820
821If you do not want the Icecream distributed compile support to apply to
Andrew Geissler595f6302022-01-24 19:11:47 +0000822specific recipes or classes, you can ask them to be ignored by Icecream
823by listing the recipes and classes using the
Andrew Geissler9aee5002022-03-30 16:27:02 +0000824:term:`ICECC_RECIPE_DISABLE` and
825:term:`ICECC_CLASS_DISABLE` variables,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500826respectively, in your ``local.conf`` file. Doing so causes the
827OpenEmbedded build system to handle these compilations locally.
828
829Additionally, you can list recipes using the
Andrew Geissler9aee5002022-03-30 16:27:02 +0000830:term:`ICECC_RECIPE_ENABLE` variable in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500831your ``local.conf`` file to force ``icecc`` to be enabled for recipes
832using an empty :term:`PARALLEL_MAKE` variable.
833
834Inheriting the ``icecc`` class changes all sstate signatures.
835Consequently, if a development team has a dedicated build system that
836populates :term:`SSTATE_MIRRORS` and they want to
Andrew Geissler09036742021-06-25 14:25:14 -0500837reuse sstate from :term:`SSTATE_MIRRORS`, then all developers and the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500838system need to either inherit the ``icecc`` class or nobody should.
839
840At the distribution level, you can inherit the ``icecc`` class to be
841sure that all builders start with the same sstate signatures. After
842inheriting the class, you can then disable the feature by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500843:term:`ICECC_DISABLED` variable to "1" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500844
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500845 INHERIT_DISTRO:append = " icecc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500846 ICECC_DISABLED ??= "1"
847
848This practice
849makes sure everyone is using the same signatures but also requires
850individuals that do want to use Icecream to enable the feature
Andrew Geisslerc926e172021-05-07 16:11:35 -0500851individually as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500852
853 ICECC_DISABLED = ""
854
855.. _ref-classes-image:
856
857``image.bbclass``
858=================
859
860The ``image`` class helps support creating images in different formats.
861First, the root filesystem is created from packages using one of the
862``rootfs*.bbclass`` files (depending on the package format used) and
863then one or more image files are created.
864
Andrew Geissler09036742021-06-25 14:25:14 -0500865- The :term:`IMAGE_FSTYPES` variable controls the types of images to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500866 generate.
867
Andrew Geissler09036742021-06-25 14:25:14 -0500868- The :term:`IMAGE_INSTALL` variable controls the list of packages to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500869 install into the image.
870
871For information on customizing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600872":ref:`dev-manual/common-tasks:customizing images`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500873in the Yocto Project Development Tasks Manual. For information on how
874images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600875":ref:`overview-manual/concepts:images`" section in the
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600876Yocto Project Overview and Concepts Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500877
878.. _ref-classes-image-buildinfo:
879
880``image-buildinfo.bbclass``
881===========================
882
883The ``image-buildinfo`` class writes information to the target
884filesystem on ``/etc/build``.
885
886.. _ref-classes-image_types:
887
888``image_types.bbclass``
889=======================
890
891The ``image_types`` class defines all of the standard image output types
892that you can enable through the
893:term:`IMAGE_FSTYPES` variable. You can use this
894class as a reference on how to add support for custom image output
895types.
896
897By default, the :ref:`image <ref-classes-image>` class automatically
898enables the ``image_types`` class. The ``image`` class uses the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500899``IMGCLASSES`` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500900
901 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
902 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
903 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
904 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
905 IMGCLASSES += "image_types_wic"
906 IMGCLASSES += "rootfs-postcommands"
907 IMGCLASSES += "image-postinst-intercepts"
908 inherit ${IMGCLASSES}
909
910The ``image_types`` class also handles conversion and compression of images.
911
912.. note::
913
914 To build a VMware VMDK image, you need to add "wic.vmdk" to
Andrew Geissler09036742021-06-25 14:25:14 -0500915 :term:`IMAGE_FSTYPES`. This would also be similar for Virtual Box Virtual Disk
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500916 Image ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500917
918.. _ref-classes-image-live:
919
920``image-live.bbclass``
921======================
922
923This class controls building "live" (i.e. HDDIMG and ISO) images. Live
924images contain syslinux for legacy booting, as well as the bootloader
925specified by :term:`EFI_PROVIDER` if
926:term:`MACHINE_FEATURES` contains "efi".
927
928Normally, you do not use this class directly. Instead, you add "live" to
929:term:`IMAGE_FSTYPES`.
930
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500931.. _ref-classes-insane:
932
933``insane.bbclass``
934==================
935
936The ``insane`` class adds a step to the package generation process so
937that output quality assurance checks are generated by the OpenEmbedded
938build system. A range of checks are performed that check the build's
939output for common problems that show up during runtime. Distribution
940policy usually dictates whether to include this class.
941
942You can configure the sanity checks so that specific test failures
943either raise a warning or an error message. Typically, failures for new
944tests generate a warning. Subsequent failures for the same test would
945then generate an error message once the metadata is in a known and good
Andrew Geissler09209ee2020-12-13 08:44:15 -0600946condition. See the ":doc:`/ref-manual/qa-checks`" Chapter for a list of all the warning
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500947and error messages you might encounter using a default configuration.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500948
949Use the :term:`WARN_QA` and
950:term:`ERROR_QA` variables to control the behavior of
951these checks at the global level (i.e. in your custom distro
952configuration). However, to skip one or more checks in recipes, you
953should use :term:`INSANE_SKIP`. For example, to skip
954the check for symbolic link ``.so`` files in the main package of a
955recipe, add the following to the recipe. You need to realize that the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500956package name override, in this example ``${PN}``, must be used::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500957
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500958 INSANE_SKIP:${PN} += "dev-so"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500959
960Please keep in mind that the QA checks
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700961are meant to detect real or potential problems in the packaged
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500962output. So exercise caution when disabling these checks.
963
Andrew Geissler09036742021-06-25 14:25:14 -0500964Here are the tests you can list with the :term:`WARN_QA` and
Andrew Geissler5f350902021-07-23 13:09:54 -0400965:term:`ERROR_QA` variables:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500966
967- ``already-stripped:`` Checks that produced binaries have not
968 already been stripped prior to the build system extracting debug
969 symbols. It is common for upstream software projects to default to
970 stripping debug symbols for output binaries. In order for debugging
971 to work on the target using ``-dbg`` packages, this stripping must be
972 disabled.
973
974- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit
975 size, and endianness of any binaries to ensure they match the target
976 architecture. This test fails if any binaries do not match the type
977 since there would be an incompatibility. The test could indicate that
978 the wrong compiler or compiler options have been used. Sometimes
979 software, like bootloaders, might need to bypass this check.
980
981- ``buildpaths:`` Checks for paths to locations on the build host
982 inside the output files. Currently, this test triggers too many false
983 positives and thus is not normally enabled.
984
985- ``build-deps:`` Determines if a build-time dependency that is
986 specified through :term:`DEPENDS`, explicit
987 :term:`RDEPENDS`, or task-level dependencies exists
988 to match any runtime dependency. This determination is particularly
989 useful to discover where runtime dependencies are detected and added
990 during packaging. If no explicit dependency has been specified within
991 the metadata, at the packaging stage it is too late to ensure that
992 the dependency is built, and thus you can end up with an error when
993 the package is installed into the image during the
994 :ref:`ref-tasks-rootfs` task because the auto-detected
995 dependency was not satisfied. An example of this would be where the
996 :ref:`update-rc.d <ref-classes-update-rc.d>` class automatically
997 adds a dependency on the ``initscripts-functions`` package to
998 packages that install an initscript that refers to
999 ``/etc/init.d/functions``. The recipe should really have an explicit
Andrew Geissler5f350902021-07-23 13:09:54 -04001000 :term:`RDEPENDS` for the package in question on ``initscripts-functions``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001001 so that the OpenEmbedded build system is able to ensure that the
1002 ``initscripts`` recipe is actually built and thus the
1003 ``initscripts-functions`` package is made available.
1004
1005- ``compile-host-path:`` Checks the
1006 :ref:`ref-tasks-compile` log for indications that
1007 paths to locations on the build host were used. Using such paths
1008 might result in host contamination of the build output.
1009
1010- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
1011 do not depend on ``-dbg`` packages, which would cause a packaging
1012 bug.
1013
1014- ``debug-files:`` Checks for ``.debug`` directories in anything but
1015 the ``-dbg`` package. The debug files should all be in the ``-dbg``
1016 package. Thus, anything packaged elsewhere is incorrect packaging.
1017
1018- ``dep-cmp:`` Checks for invalid version comparison statements in
1019 runtime dependency relationships between packages (i.e. in
1020 :term:`RDEPENDS`,
1021 :term:`RRECOMMENDS`,
1022 :term:`RSUGGESTS`,
1023 :term:`RPROVIDES`,
1024 :term:`RREPLACES`, and
1025 :term:`RCONFLICTS` variable values). Any invalid
1026 comparisons might trigger failures or undesirable behavior when
1027 passed to the package manager.
1028
1029- ``desktop:`` Runs the ``desktop-file-validate`` program against any
1030 ``.desktop`` files to validate their contents against the
1031 specification for ``.desktop`` files.
1032
1033- ``dev-deps:`` Checks that all packages except ``-dev`` or
1034 ``-staticdev`` packages do not depend on ``-dev`` packages, which
1035 would be a packaging bug.
1036
1037- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
1038 ``-dev`` package and not in any of the other packages. In general,
1039 these symlinks are only useful for development purposes. Thus, the
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001040 ``-dev`` package is the correct location for them. In very rare
1041 cases, such as dynamically loaded modules, these symlinks
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001042 are needed instead in the main package.
1043
Patrick Williams03907ee2022-05-01 06:28:52 -05001044- ``empty-dirs:`` Checks that packages are not installing files to
1045 directories that are normally expected to be empty (such as ``/tmp``)
1046 The list of directories that are checked is specified by the
1047 :term:`QA_EMPTY_DIRS` variable.
1048
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001049- ``file-rdeps:`` Checks that file-level dependencies identified by
1050 the OpenEmbedded build system at packaging time are satisfied. For
1051 example, a shell script might start with the line ``#!/bin/bash``.
1052 This line would translate to a file dependency on ``/bin/bash``. Of
1053 the three package managers that the OpenEmbedded build system
1054 supports, only RPM directly handles file-level dependencies,
1055 resolving them automatically to packages providing the files.
1056 However, the lack of that functionality in the other two package
1057 managers does not mean the dependencies do not still need resolving.
1058 This QA check attempts to ensure that explicitly declared
1059 :term:`RDEPENDS` exist to handle any file-level
1060 dependency detected in packaged files.
1061
1062- ``files-invalid:`` Checks for :term:`FILES` variable
1063 values that contain "//", which is invalid.
1064
1065- ``host-user-contaminated:`` Checks that no package produced by the
1066 recipe contains any files outside of ``/home`` with a user or group
1067 ID that matches the user running BitBake. A match usually indicates
1068 that the files are being installed with an incorrect UID/GID, since
1069 target IDs are independent from host IDs. For additional information,
1070 see the section describing the
1071 :ref:`ref-tasks-install` task.
1072
1073- ``incompatible-license:`` Report when packages are excluded from
1074 being created due to being marked with a license that is in
1075 :term:`INCOMPATIBLE_LICENSE`.
1076
1077- ``install-host-path:`` Checks the
1078 :ref:`ref-tasks-install` log for indications that
1079 paths to locations on the build host were used. Using such paths
1080 might result in host contamination of the build output.
1081
1082- ``installed-vs-shipped:`` Reports when files have been installed
1083 within ``do_install`` but have not been included in any package by
1084 way of the :term:`FILES` variable. Files that do not
1085 appear in any package cannot be present in an image later on in the
1086 build process. Ideally, all installed files should be packaged or not
1087 installed at all. These files can be deleted at the end of
1088 ``do_install`` if the files are not needed in any package.
1089
1090- ``invalid-chars:`` Checks that the recipe metadata variables
1091 :term:`DESCRIPTION`,
1092 :term:`SUMMARY`, :term:`LICENSE`, and
1093 :term:`SECTION` do not contain non-UTF-8 characters.
1094 Some package managers do not support such characters.
1095
1096- ``invalid-packageconfig:`` Checks that no undefined features are
1097 being added to :term:`PACKAGECONFIG`. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05001098 example, any name "foo" for which the following form does not exist::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001099
1100 PACKAGECONFIG[foo] = "..."
1101
Andrew Geissler09036742021-06-25 14:25:14 -05001102- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001103 file containing these paths is incorrect since ``libtool`` adds the
1104 correct sysroot prefix when using the files automatically itself.
1105
1106- ``ldflags:`` Ensures that the binaries were linked with the
1107 :term:`LDFLAGS` options provided by the build system.
Andrew Geissler09036742021-06-25 14:25:14 -05001108 If this test fails, check that the :term:`LDFLAGS` variable is being
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001109 passed to the linker command.
1110
1111- ``libdir:`` Checks for libraries being installed into incorrect
1112 (possibly hardcoded) installation paths. For example, this test will
1113 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
1114 "lib32". Another example is when recipes install
1115 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
1116
1117- ``libexec:`` Checks if a package contains files in
1118 ``/usr/libexec``. This check is not performed if the ``libexecdir``
1119 variable has been set explicitly to ``/usr/libexec``.
1120
1121- ``packages-list:`` Checks for the same package being listed
1122 multiple times through the :term:`PACKAGES` variable
1123 value. Installing the package in this manner can cause errors during
1124 packaging.
1125
1126- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
1127 invalid format.
1128
1129- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
1130 invalid format.
1131
1132- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
1133 'link' where the specified target already exists.
1134
1135- ``perms:`` Currently, this check is unused but reserved.
1136
1137- ``pkgconfig:`` Checks ``.pc`` files for any
1138 :term:`TMPDIR`/:term:`WORKDIR` paths.
1139 Any ``.pc`` file containing these paths is incorrect since
1140 ``pkg-config`` itself adds the correct sysroot prefix when the files
1141 are accessed.
1142
1143- ``pkgname:`` Checks that all packages in
1144 :term:`PACKAGES` have names that do not contain
1145 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1146 -).
1147
Andrew Geissler09036742021-06-25 14:25:14 -05001148- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001149 undefined during :ref:`ref-tasks-package`.
1150
1151- ``pkgvarcheck:`` Checks through the variables
1152 :term:`RDEPENDS`,
1153 :term:`RRECOMMENDS`,
1154 :term:`RSUGGESTS`,
1155 :term:`RCONFLICTS`,
1156 :term:`RPROVIDES`,
1157 :term:`RREPLACES`, :term:`FILES`,
1158 :term:`ALLOW_EMPTY`, ``pkg_preinst``,
1159 ``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, and reports if
1160 there are variable sets that are not package-specific. Using these
1161 variables without a package suffix is bad practice, and might
1162 unnecessarily complicate dependencies of other packages within the
1163 same recipe or have other unintended consequences.
1164
1165- ``pn-overrides:`` Checks that a recipe does not have a name
1166 (:term:`PN`) value that appears in
1167 :term:`OVERRIDES`. If a recipe is named such that
Andrew Geissler09036742021-06-25 14:25:14 -05001168 its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
1169 :term:`PN` happens to be the same as :term:`MACHINE` or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001170 :term:`DISTRO`), it can have unexpected consequences.
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001171 For example, assignments such as ``FILES:${PN} = "xyz"`` effectively
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001172 turn into ``FILES = "xyz"``.
1173
1174- ``rpaths:`` Checks for rpaths in the binaries that contain build
Andrew Geissler5f350902021-07-23 13:09:54 -04001175 system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001176 options are being passed to the linker commands and your binaries
1177 have potential security issues.
1178
1179- ``split-strip:`` Reports that splitting or stripping debug symbols
1180 from binaries has failed.
1181
1182- ``staticdev:`` Checks for static library files (``*.a``) in
1183 non-``staticdev`` packages.
1184
1185- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
1186 into :term:`TMPDIR` on the host. Such symlinks will
1187 work on the host, but are clearly invalid when running on the target.
1188
1189- ``textrel:`` Checks for ELF binaries that contain relocations in
1190 their ``.text`` sections, which can result in a performance impact at
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001191 runtime. See the explanation for the ``ELF binary`` message in
Andrew Geissler09209ee2020-12-13 08:44:15 -06001192 ":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001193 issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001194
1195- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
1196 for a package are also declared on the recipe level (i.e. any license
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001197 in ``LICENSE:*`` should appear in :term:`LICENSE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001198
1199- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
1200 in the binaries that by default on a standard system are searched by
1201 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
1202 not cause any breakage, they do waste space and are unnecessary.
1203
1204- ``var-undefined:`` Reports when variables fundamental to packaging
1205 (i.e. :term:`WORKDIR`,
1206 :term:`DEPLOY_DIR`, :term:`D`,
1207 :term:`PN`, and :term:`PKGD`) are undefined
1208 during :ref:`ref-tasks-package`.
1209
1210- ``version-going-backwards:`` If Build History is enabled, reports
1211 when a package being written out has a lower version than the
1212 previously written package under the same name. If you are placing
1213 output packages into a feed and upgrading packages on a target system
1214 using that feed, the version of a package going backwards can result
1215 in the target system not correctly upgrading to the "new" version of
1216 the package.
1217
1218 .. note::
1219
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001220 This is only relevant when you are using runtime package management
1221 on your target system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001222
1223- ``xorg-driver-abi:`` Checks that all packages containing Xorg
1224 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
1225 driver ABI names. All drivers should depend on the ABI versions that
1226 they have been built against. Driver recipes that include
1227 ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
1228 automatically get these versions. Consequently, you should only need
1229 to explicitly add dependencies to binary driver recipes.
1230
1231.. _ref-classes-insserv:
1232
1233``insserv.bbclass``
1234===================
1235
1236The ``insserv`` class uses the ``insserv`` utility to update the order
1237of symbolic links in ``/etc/rc?.d/`` within an image based on
1238dependencies specified by LSB headers in the ``init.d`` scripts
1239themselves.
1240
1241.. _ref-classes-kernel:
1242
1243``kernel.bbclass``
1244==================
1245
1246The ``kernel`` class handles building Linux kernels. The class contains
1247code to build all kernel trees. All needed headers are staged into the
Andrew Geissler5f350902021-07-23 13:09:54 -04001248:term:`STAGING_KERNEL_DIR` directory to allow out-of-tree module builds
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001249using the :ref:`module <ref-classes-module>` class.
1250
1251This means that each built kernel module is packaged separately and
1252inter-module dependencies are created by parsing the ``modinfo`` output.
1253If all modules are required, then installing the ``kernel-modules``
1254package installs all packages with modules and various other kernel
1255packages such as ``kernel-vmlinux``.
1256
1257The ``kernel`` class contains logic that allows you to embed an initial
1258RAM filesystem (initramfs) image when you build the kernel image. For
1259information on how to build an initramfs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001260":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001261the Yocto Project Development Tasks Manual.
1262
1263Various other classes are used by the ``kernel`` and ``module`` classes
1264internally including the :ref:`kernel-arch <ref-classes-kernel-arch>`,
1265:ref:`module-base <ref-classes-module-base>`, and
1266:ref:`linux-kernel-base <ref-classes-linux-kernel-base>` classes.
1267
1268.. _ref-classes-kernel-arch:
1269
1270``kernel-arch.bbclass``
1271=======================
1272
1273The ``kernel-arch`` class sets the ``ARCH`` environment variable for
1274Linux kernel compilation (including modules).
1275
1276.. _ref-classes-kernel-devicetree:
1277
1278``kernel-devicetree.bbclass``
1279=============================
1280
1281The ``kernel-devicetree`` class, which is inherited by the
1282:ref:`kernel <ref-classes-kernel>` class, supports device tree
1283generation.
1284
1285.. _ref-classes-kernel-fitimage:
1286
1287``kernel-fitimage.bbclass``
1288===========================
1289
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001290The ``kernel-fitimage`` class provides support to pack a kernel image,
1291device trees, a U-boot script, a Initramfs bundle and a RAM disk
1292into a single FIT image. In theory, a FIT image can support any number
1293of kernels, U-boot scripts, Initramfs bundles, RAM disks and device-trees.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001294However, ``kernel-fitimage`` currently only supports
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001295limited usescases: just one kernel image, an optional U-boot script,
1296an optional Initramfs bundle, an optional RAM disk, and any number of
1297device tree.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001298
1299To create a FIT image, it is required that :term:`KERNEL_CLASSES`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001300is set to include "kernel-fitimage" and :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001301is set to "fitImage".
1302
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001303The options for the device tree compiler passed to ``mkimage -D``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001304when creating the FIT image are specified using the
1305:term:`UBOOT_MKIMAGE_DTCOPTS` variable.
1306
1307Only a single kernel can be added to the FIT image created by
1308``kernel-fitimage`` and the kernel image in FIT is mandatory. The
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001309address where the kernel image is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001310specified by :term:`UBOOT_LOADADDRESS` and the entrypoint by
1311:term:`UBOOT_ENTRYPOINT`.
1312
1313Multiple device trees can be added to the FIT image created by
1314``kernel-fitimage`` and the device tree is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001315The address where the device tree is to be loaded by U-Boot is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001316specified by :term:`UBOOT_DTBO_LOADADDRESS` for device tree overlays
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001317and by :term:`UBOOT_DTB_LOADADDRESS` for device tree binaries.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001318
1319Only a single RAM disk can be added to the FIT image created by
1320``kernel-fitimage`` and the RAM disk in FIT is optional.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001321The address where the RAM disk image is to be loaded by U-Boot
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001322is specified by :term:`UBOOT_RD_LOADADDRESS` and the entrypoint by
1323:term:`UBOOT_RD_ENTRYPOINT`. The ramdisk is added to FIT image when
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001324:term:`INITRAMFS_IMAGE` is specified and that :term:`INITRAMFS_IMAGE_BUNDLE`
1325is set to 0.
1326
1327Only a single Initramfs bundle can be added to the FIT image created by
1328``kernel-fitimage`` and the Initramfs bundle in FIT is optional.
Andrew Geissler595f6302022-01-24 19:11:47 +00001329In case of Initramfs, the kernel is configured to be bundled with the root filesystem
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001330in the same binary (example: zImage-initramfs-:term:`MACHINE`.bin).
Andrew Geissler595f6302022-01-24 19:11:47 +00001331When the kernel is copied to RAM and executed, it unpacks the Initramfs root filesystem.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001332The Initramfs bundle can be enabled when :term:`INITRAMFS_IMAGE`
1333is specified and that :term:`INITRAMFS_IMAGE_BUNDLE` is set to 1.
1334The address where the Initramfs bundle is to be loaded by U-boot is specified
1335by :term:`UBOOT_LOADADDRESS` and the entrypoint by :term:`UBOOT_ENTRYPOINT`.
1336
1337Only a single U-boot boot script can be added to the FIT image created by
1338``kernel-fitimage`` and the boot script is optional.
1339The boot script is specified in the ITS file as a text file containing
1340U-boot commands. When using a boot script the user should configure the
1341U-boot ``do_install`` task to copy the script to sysroot.
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001342So the script can be included in the FIT image by the ``kernel-fitimage``
Andrew Geisslerd1e89492021-02-12 15:35:20 -06001343class. At run-time, U-boot CONFIG_BOOTCOMMAND define can be configured to
1344load the boot script from the FIT image and executes it.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001345
1346The FIT image generated by ``kernel-fitimage`` class is signed when the
1347variables :term:`UBOOT_SIGN_ENABLE`, :term:`UBOOT_MKIMAGE_DTCOPTS`,
1348:term:`UBOOT_SIGN_KEYDIR` and :term:`UBOOT_SIGN_KEYNAME` are set
1349appropriately. The default values used for :term:`FIT_HASH_ALG` and
1350:term:`FIT_SIGN_ALG` in ``kernel-fitimage`` are "sha256" and
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05001351"rsa2048" respectively. The keys for signing fitImage can be generated using
1352the ``kernel-fitimage`` class when both :term:`FIT_GENERATE_KEYS` and
1353:term:`UBOOT_SIGN_ENABLE` are set to "1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001354
1355
1356.. _ref-classes-kernel-grub:
1357
1358``kernel-grub.bbclass``
1359=======================
1360
1361The ``kernel-grub`` class updates the boot area and the boot menu with
1362the kernel as the priority boot mechanism while installing a RPM to
1363update the kernel on a deployed target.
1364
1365.. _ref-classes-kernel-module-split:
1366
1367``kernel-module-split.bbclass``
1368===============================
1369
1370The ``kernel-module-split`` class provides common functionality for
1371splitting Linux kernel modules into separate packages.
1372
1373.. _ref-classes-kernel-uboot:
1374
1375``kernel-uboot.bbclass``
1376========================
1377
1378The ``kernel-uboot`` class provides support for building from
1379vmlinux-style kernel sources.
1380
1381.. _ref-classes-kernel-uimage:
1382
1383``kernel-uimage.bbclass``
1384=========================
1385
1386The ``kernel-uimage`` class provides support to pack uImage.
1387
1388.. _ref-classes-kernel-yocto:
1389
1390``kernel-yocto.bbclass``
1391========================
1392
1393The ``kernel-yocto`` class provides common functionality for building
1394from linux-yocto style kernel source repositories.
1395
1396.. _ref-classes-kernelsrc:
1397
1398``kernelsrc.bbclass``
1399=====================
1400
1401The ``kernelsrc`` class sets the Linux kernel source and version.
1402
1403.. _ref-classes-lib_package:
1404
1405``lib_package.bbclass``
1406=======================
1407
1408The ``lib_package`` class supports recipes that build libraries and
1409produce executable binaries, where those binaries should not be
1410installed by default along with the library. Instead, the binaries are
1411added to a separate ``${``\ :term:`PN`\ ``}-bin`` package to
1412make their installation optional.
1413
1414.. _ref-classes-libc*:
1415
1416``libc*.bbclass``
1417=================
1418
1419The ``libc*`` classes support recipes that build packages with ``libc``:
1420
1421- The ``libc-common`` class provides common support for building with
1422 ``libc``.
1423
1424- The ``libc-package`` class supports packaging up ``glibc`` and
1425 ``eglibc``.
1426
1427.. _ref-classes-license:
1428
1429``license.bbclass``
1430===================
1431
1432The ``license`` class provides license manifest creation and license
1433exclusion. This class is enabled by default using the default value for
1434the :term:`INHERIT_DISTRO` variable.
1435
1436.. _ref-classes-linux-kernel-base:
1437
1438``linux-kernel-base.bbclass``
1439=============================
1440
1441The ``linux-kernel-base`` class provides common functionality for
1442recipes that build out of the Linux kernel source tree. These builds
1443goes beyond the kernel itself. For example, the Perf recipe also
1444inherits this class.
1445
1446.. _ref-classes-linuxloader:
1447
1448``linuxloader.bbclass``
1449=======================
1450
1451Provides the function ``linuxloader()``, which gives the value of the
1452dynamic loader/linker provided on the platform. This value is used by a
1453number of other classes.
1454
1455.. _ref-classes-logging:
1456
1457``logging.bbclass``
1458===================
1459
1460The ``logging`` class provides the standard shell functions used to log
1461messages for various BitBake severity levels (i.e. ``bbplain``,
1462``bbnote``, ``bbwarn``, ``bberror``, ``bbfatal``, and ``bbdebug``).
1463
1464This class is enabled by default since it is inherited by the ``base``
1465class.
1466
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001467.. _ref-classes-metadata_scm:
1468
1469``metadata_scm.bbclass``
1470========================
1471
1472The ``metadata_scm`` class provides functionality for querying the
1473branch and revision of a Source Code Manager (SCM) repository.
1474
1475The :ref:`base <ref-classes-base>` class uses this class to print the
1476revisions of each layer before starting every build. The
1477``metadata_scm`` class is enabled by default because it is inherited by
1478the ``base`` class.
1479
1480.. _ref-classes-migrate_localcount:
1481
1482``migrate_localcount.bbclass``
1483==============================
1484
1485The ``migrate_localcount`` class verifies a recipe's localcount data and
1486increments it appropriately.
1487
1488.. _ref-classes-mime:
1489
1490``mime.bbclass``
1491================
1492
1493The ``mime`` class generates the proper post-install and post-remove
1494(postinst/postrm) scriptlets for packages that install MIME type files.
1495These scriptlets call ``update-mime-database`` to add the MIME types to
1496the shared database.
1497
1498.. _ref-classes-mirrors:
1499
1500``mirrors.bbclass``
1501===================
1502
1503The ``mirrors`` class sets up some standard
1504:term:`MIRRORS` entries for source code mirrors. These
1505mirrors provide a fall-back path in case the upstream source specified
1506in :term:`SRC_URI` within recipes is unavailable.
1507
1508This class is enabled by default since it is inherited by the
1509:ref:`base <ref-classes-base>` class.
1510
1511.. _ref-classes-module:
1512
1513``module.bbclass``
1514==================
1515
1516The ``module`` class provides support for building out-of-tree Linux
1517kernel modules. The class inherits the
1518:ref:`module-base <ref-classes-module-base>` and
1519:ref:`kernel-module-split <ref-classes-kernel-module-split>` classes,
1520and implements the :ref:`ref-tasks-compile` and
1521:ref:`ref-tasks-install` tasks. The class provides
1522everything needed to build and package a kernel module.
1523
1524For general information on out-of-tree Linux kernel modules, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001525":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001526section in the Yocto Project Linux Kernel Development Manual.
1527
1528.. _ref-classes-module-base:
1529
1530``module-base.bbclass``
1531=======================
1532
1533The ``module-base`` class provides the base functionality for building
1534Linux kernel modules. Typically, a recipe that builds software that
1535includes one or more kernel modules and has its own means of building
1536the module inherits this class as opposed to inheriting the
1537:ref:`module <ref-classes-module>` class.
1538
1539.. _ref-classes-multilib*:
1540
1541``multilib*.bbclass``
1542=====================
1543
1544The ``multilib*`` classes provide support for building libraries with
1545different target optimizations or target architectures and installing
1546them side-by-side in the same image.
1547
1548For more information on using the Multilib feature, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001549":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001550section in the Yocto Project Development Tasks Manual.
1551
1552.. _ref-classes-native:
1553
1554``native.bbclass``
1555==================
1556
1557The ``native`` class provides common functionality for recipes that
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001558build tools to run on the :term:`Build Host` (i.e. tools that use the compiler
1559or other tools from the build host).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001560
1561You can create a recipe that builds tools that run natively on the host
1562a couple different ways:
1563
Andrew Geisslereff27472021-10-29 15:35:00 -05001564- Create a ``myrecipe-native.bb`` recipe that inherits the ``native``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001565 class. If you use this method, you must order the inherit statement
1566 in the recipe after all other inherit statements so that the
1567 ``native`` class is inherited last.
1568
1569 .. note::
1570
1571 When creating a recipe this way, the recipe name must follow this
Andrew Geisslerc926e172021-05-07 16:11:35 -05001572 naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001573
1574 myrecipe-native.bb
1575
1576
1577 Not using this naming convention can lead to subtle problems
1578 caused by existing code that depends on that naming convention.
1579
Andrew Geisslerc926e172021-05-07 16:11:35 -05001580- Create or modify a target recipe that contains the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001581
1582 BBCLASSEXTEND = "native"
1583
1584 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001585 recipe, use ``:class-native`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001586 specify any functionality specific to the respective native or target
1587 case.
1588
1589Although applied differently, the ``native`` class is used with both
1590methods. The advantage of the second method is that you do not need to
1591have two separate recipes (assuming you need both) for native and
1592target. All common parts of the recipe are automatically shared.
1593
1594.. _ref-classes-nativesdk:
1595
1596``nativesdk.bbclass``
1597=====================
1598
1599The ``nativesdk`` class provides common functionality for recipes that
1600wish to build tools to run as part of an SDK (i.e. tools that run on
1601:term:`SDKMACHINE`).
1602
1603You can create a recipe that builds tools that run on the SDK machine a
1604couple different ways:
1605
Andrew Geisslereff27472021-10-29 15:35:00 -05001606- Create a ``nativesdk-myrecipe.bb`` recipe that inherits the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001607 ``nativesdk`` class. If you use this method, you must order the
1608 inherit statement in the recipe after all other inherit statements so
1609 that the ``nativesdk`` class is inherited last.
1610
Andrew Geisslerc926e172021-05-07 16:11:35 -05001611- Create a ``nativesdk`` variant of any recipe by adding the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001612
1613 BBCLASSEXTEND = "nativesdk"
1614
1615 Inside the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001616 recipe, use ``:class-nativesdk`` and ``:class-target`` overrides to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001617 specify any functionality specific to the respective SDK machine or
1618 target case.
1619
1620.. note::
1621
Andrew Geisslerc926e172021-05-07 16:11:35 -05001622 When creating a recipe, you must follow this naming convention::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001623
1624 nativesdk-myrecipe.bb
1625
1626
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001627 Not doing so can lead to subtle problems because there is code that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001628 depends on the naming convention.
1629
1630Although applied differently, the ``nativesdk`` class is used with both
1631methods. The advantage of the second method is that you do not need to
1632have two separate recipes (assuming you need both) for the SDK machine
1633and the target. All common parts of the recipe are automatically shared.
1634
1635.. _ref-classes-nopackages:
1636
1637``nopackages.bbclass``
1638======================
1639
1640Disables packaging tasks for those recipes and classes where packaging
1641is not needed.
1642
1643.. _ref-classes-npm:
1644
1645``npm.bbclass``
1646===============
1647
1648Provides support for building Node.js software fetched using the `node
1649package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
1650
1651.. note::
1652
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001653 Currently, recipes inheriting this class must use the ``npm://``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001654 fetcher to have dependencies fetched and packaged automatically.
1655
1656For information on how to create NPM packages, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001657":ref:`dev-manual/common-tasks:creating node package manager (npm) packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001658section in the Yocto Project Development Tasks Manual.
1659
1660.. _ref-classes-oelint:
1661
1662``oelint.bbclass``
1663==================
1664
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001665The ``oelint`` class is an obsolete lint checking tool available in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001666``meta/classes`` in the :term:`Source Directory`.
1667
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001668There are some classes that could be generally useful in OE-Core but
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001669are never actually used within OE-Core itself. The ``oelint`` class is
1670one such example. However, being aware of this class can reduce the
1671proliferation of different versions of similar classes across multiple
1672layers.
1673
Andrew Geissler5199d832021-09-24 16:47:35 -05001674.. _ref-classes-overlayfs:
1675
1676``overlayfs.bbclass``
1677=======================
1678
Andrew Geissler595f6302022-01-24 19:11:47 +00001679It's often desired in Embedded System design to have a read-only root filesystem.
Andrew Geissler5199d832021-09-24 16:47:35 -05001680But a lot of different applications might want to have read-write access to
1681some parts of a filesystem. It can be especially useful when your update mechanism
Andrew Geissler595f6302022-01-24 19:11:47 +00001682overwrites the whole root filesystem, but you may want your application data to be preserved
Andrew Geissler5199d832021-09-24 16:47:35 -05001683between updates. The :ref:`overlayfs <ref-classes-overlayfs>` class provides a way
1684to achieve that by means of ``overlayfs`` and at the same time keeping the base
Andrew Geissler595f6302022-01-24 19:11:47 +00001685root filesystem read-only.
Andrew Geissler5199d832021-09-24 16:47:35 -05001686
1687To use this class, set a mount point for a partition ``overlayfs`` is going to use as upper
1688layer in your machine configuration. The underlying file system can be anything that
1689is supported by ``overlayfs``. This has to be done in your machine configuration::
1690
1691 OVERLAYFS_MOUNT_POINT[data] = "/data"
1692
1693.. note::
1694
1695 * QA checks fail to catch file existence if you redefine this variable in your recipe!
1696 * Only the existence of the systemd mount unit file is checked, not its contents.
1697 * To get more details on ``overlayfs``, its internals and supported operations, please refer
1698 to the official documentation of the `Linux kernel <https://www.kernel.org/doc/html/latest/filesystems/overlayfs.html>`_.
1699
1700The class assumes you have a ``data.mount`` systemd unit defined elsewhere in your BSP
1701(e.g. in ``systemd-machine-units`` recipe) and it's installed into the image.
1702
1703Then you can specify writable directories on a recipe basis (e.g. in my-application.bb)::
1704
1705 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
1706
1707To support several mount points you can use a different variable flag. Assuming we
1708want to have a writable location on the file system, but do not need that the data
Andrew Geissler595f6302022-01-24 19:11:47 +00001709survives a reboot, then we could have a ``mnt-overlay.mount`` unit for a ``tmpfs``
1710file system.
Andrew Geissler5199d832021-09-24 16:47:35 -05001711
1712In your machine configuration::
1713
1714 OVERLAYFS_MOUNT_POINT[mnt-overlay] = "/mnt/overlay"
1715
1716and then in your recipe::
1717
1718 OVERLAYFS_WRITABLE_PATHS[mnt-overlay] = "/usr/share/another-application"
1719
Andrew Geissler595f6302022-01-24 19:11:47 +00001720On a practical note, your application recipe might require multiple
1721overlays to be mounted before running to avoid writing to the underlying
1722file system (which can be forbidden in case of read-only file system)
1723To achieve that :ref:`overlayfs <ref-classes-overlayfs>` provides a ``systemd``
1724helper service for mounting overlays. This helper service is named
1725``${PN}-overlays.service`` and can be depended on in your application recipe
1726(named ``application`` in the following example) ``systemd`` unit by adding
1727to the unit the following::
1728
1729 [Unit]
1730 After=application-overlays.service
1731 Requires=application-overlays.service
1732
Andrew Geissler5199d832021-09-24 16:47:35 -05001733.. note::
1734
1735 The class does not support the ``/etc`` directory itself, because ``systemd`` depends on it.
Andrew Geissler595f6302022-01-24 19:11:47 +00001736 In order to get ``/etc`` in overlayfs, see :ref:`overlayfs-etc <ref-classes-overlayfs-etc>`.
1737
1738.. _ref-classes-overlayfs-etc:
1739
1740``overlayfs-etc.bbclass``
1741=========================
1742
1743In order to have the ``/etc`` directory in overlayfs a special handling at early
1744boot stage is required. The idea is to supply a custom init script that mounts
1745``/etc`` before launching the actual init program, because the latter already
1746requires ``/etc`` to be mounted.
1747
1748Example usage in image recipe::
1749
1750 IMAGE_FEATURES += "overlayfs-etc"
1751
1752.. note::
1753
1754 This class must not be inherited directly. Use :term:`IMAGE_FEATURES` or :term:`EXTRA_IMAGE_FEATURES`
1755
1756Your machine configuration should define at least the device, mount point, and file system type
1757you are going to use for ``overlayfs``::
1758
1759 OVERLAYFS_ETC_MOUNT_POINT = "/data"
1760 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
1761 OVERLAYFS_ETC_FSTYPE ?= "ext4"
1762
1763To control more mount options you should consider setting mount options
1764(``defaults`` is used by default)::
1765
1766 OVERLAYFS_ETC_MOUNT_OPTIONS = "wsync"
1767
1768The class provides two options for ``/sbin/init`` generation:
1769
1770- The default option is to rename the original ``/sbin/init`` to ``/sbin/init.orig``
1771 and place the generated init under original name, i.e. ``/sbin/init``. It has an advantage
1772 that you won't need to change any kernel parameters in order to make it work,
1773 but it poses a restriction that package-management can't be used, because updating
1774 the init manager would remove the generated script.
1775
1776- If you wish to keep original init as is, you can set::
1777
1778 OVERLAYFS_ETC_USE_ORIG_INIT_NAME = "0"
1779
1780 Then the generated init will be named ``/sbin/preinit`` and you would need to extend your
1781 kernel parameters manually in your bootloader configuration.
Andrew Geissler5199d832021-09-24 16:47:35 -05001782
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001783.. _ref-classes-own-mirrors:
1784
1785``own-mirrors.bbclass``
1786=======================
1787
1788The ``own-mirrors`` class makes it easier to set up your own
1789:term:`PREMIRRORS` from which to first fetch source
1790before attempting to fetch it from the upstream specified in
1791:term:`SRC_URI` within each recipe.
1792
1793To use this class, inherit it globally and specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05001794:term:`SOURCE_MIRROR_URL`. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001795
1796 INHERIT += "own-mirrors"
1797 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1798
1799You can specify only a single URL
Andrew Geissler09036742021-06-25 14:25:14 -05001800in :term:`SOURCE_MIRROR_URL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001801
1802.. _ref-classes-package:
1803
1804``package.bbclass``
1805===================
1806
1807The ``package`` class supports generating packages from a build's
1808output. The core generic functionality is in ``package.bbclass``. The
1809code specific to particular package types resides in these
1810package-specific classes:
1811:ref:`package_deb <ref-classes-package_deb>`,
1812:ref:`package_rpm <ref-classes-package_rpm>`,
1813:ref:`package_ipk <ref-classes-package_ipk>`, and
1814:ref:`package_tar <ref-classes-package_tar>`.
1815
1816.. note::
1817
1818 The
1819 package_tar
1820 class is broken and not supported. It is recommended that you do not
1821 use this class.
1822
1823You can control the list of resulting package formats by using the
Andrew Geissler09036742021-06-25 14:25:14 -05001824:term:`PACKAGE_CLASSES` variable defined in your ``conf/local.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001825configuration file, which is located in the :term:`Build Directory`.
1826When defining the variable, you can
1827specify one or more package types. Since images are generated from
1828packages, a packaging class is needed to enable image generation. The
1829first class listed in this variable is used for image generation.
1830
1831If you take the optional step to set up a repository (package feed) on
1832the development host that can be used by DNF, you can install packages
1833from the feed while you are running the image on the target (i.e.
1834runtime installation of packages). For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001835":ref:`dev-manual/common-tasks:using runtime package management`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001836section in the Yocto Project Development Tasks Manual.
1837
1838The package-specific class you choose can affect build-time performance
1839and has space ramifications. In general, building a package with IPK
1840takes about thirty percent less time as compared to using RPM to build
1841the same or similar package. This comparison takes into account a
1842complete build of the package with all dependencies previously built.
1843The reason for this discrepancy is because the RPM package manager
1844creates and processes more :term:`Metadata` than the IPK package
Andrew Geissler09036742021-06-25 14:25:14 -05001845manager. Consequently, you might consider setting :term:`PACKAGE_CLASSES` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001846"package_ipk" if you are building smaller systems.
1847
1848Before making your package manager decision, however, you should
1849consider some further things about using RPM:
1850
1851- RPM starts to provide more abilities than IPK due to the fact that it
1852 processes more Metadata. For example, this information includes
1853 individual file types, file checksum generation and evaluation on
1854 install, sparse file support, conflict detection and resolution for
1855 Multilib systems, ACID style upgrade, and repackaging abilities for
1856 rollbacks.
1857
1858- For smaller systems, the extra space used for the Berkeley Database
1859 and the amount of metadata when using RPM can affect your ability to
1860 perform on-device upgrades.
1861
1862You can find additional information on the effects of the package class
1863at these two Yocto Project mailing list links:
1864
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001865- :yocto_lists:`/pipermail/poky/2011-May/006362.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001866
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001867- :yocto_lists:`/pipermail/poky/2011-May/006363.html`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001868
1869.. _ref-classes-package_deb:
1870
1871``package_deb.bbclass``
1872=======================
1873
1874The ``package_deb`` class provides support for creating packages that
1875use the Debian (i.e. ``.deb``) file format. The class ensures the
1876packages are written out in a ``.deb`` file format to the
1877``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory.
1878
1879This class inherits the :ref:`package <ref-classes-package>` class and
1880is enabled through the :term:`PACKAGE_CLASSES`
1881variable in the ``local.conf`` file.
1882
1883.. _ref-classes-package_ipk:
1884
1885``package_ipk.bbclass``
1886=======================
1887
1888The ``package_ipk`` class provides support for creating packages that
1889use the IPK (i.e. ``.ipk``) file format. The class ensures the packages
1890are written out in a ``.ipk`` file format to the
1891``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory.
1892
1893This class inherits the :ref:`package <ref-classes-package>` class and
1894is enabled through the :term:`PACKAGE_CLASSES`
1895variable in the ``local.conf`` file.
1896
1897.. _ref-classes-package_rpm:
1898
1899``package_rpm.bbclass``
1900=======================
1901
1902The ``package_rpm`` class provides support for creating packages that
1903use the RPM (i.e. ``.rpm``) file format. The class ensures the packages
1904are written out in a ``.rpm`` file format to the
1905``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory.
1906
1907This class inherits the :ref:`package <ref-classes-package>` class and
1908is enabled through the :term:`PACKAGE_CLASSES`
1909variable in the ``local.conf`` file.
1910
1911.. _ref-classes-package_tar:
1912
1913``package_tar.bbclass``
1914=======================
1915
1916The ``package_tar`` class provides support for creating tarballs. The
1917class ensures the packages are written out in a tarball format to the
1918``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory.
1919
1920This class inherits the :ref:`package <ref-classes-package>` class and
1921is enabled through the :term:`PACKAGE_CLASSES`
1922variable in the ``local.conf`` file.
1923
1924.. note::
1925
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001926 You cannot specify the ``package_tar`` class first using the
Andrew Geissler09036742021-06-25 14:25:14 -05001927 :term:`PACKAGE_CLASSES` variable. You must use ``.deb``, ``.ipk``, or ``.rpm``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001928 file formats for your image or SDK.
1929
1930.. _ref-classes-packagedata:
1931
1932``packagedata.bbclass``
1933=======================
1934
1935The ``packagedata`` class provides common functionality for reading
1936``pkgdata`` files found in :term:`PKGDATA_DIR`. These
1937files contain information about each output package produced by the
1938OpenEmbedded build system.
1939
1940This class is enabled by default because it is inherited by the
1941:ref:`package <ref-classes-package>` class.
1942
1943.. _ref-classes-packagegroup:
1944
1945``packagegroup.bbclass``
1946========================
1947
1948The ``packagegroup`` class sets default values appropriate for package
Andrew Geissler09036742021-06-25 14:25:14 -05001949group recipes (e.g. :term:`PACKAGES`, :term:`PACKAGE_ARCH`, :term:`ALLOW_EMPTY`, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001950so forth). It is highly recommended that all package group recipes
1951inherit this class.
1952
1953For information on how to use this class, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001954":ref:`dev-manual/common-tasks:customizing images using custom package groups`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001955section in the Yocto Project Development Tasks Manual.
1956
1957Previously, this class was called the ``task`` class.
1958
1959.. _ref-classes-patch:
1960
1961``patch.bbclass``
1962=================
1963
1964The ``patch`` class provides all functionality for applying patches
1965during the :ref:`ref-tasks-patch` task.
1966
1967This class is enabled by default because it is inherited by the
1968:ref:`base <ref-classes-base>` class.
1969
1970.. _ref-classes-perlnative:
1971
1972``perlnative.bbclass``
1973======================
1974
1975When inherited by a recipe, the ``perlnative`` class supports using the
1976native version of Perl built by the build system rather than using the
1977version provided by the build host.
1978
Patrick Williams45852732022-04-02 08:58:32 -05001979.. _ref-classes-python_flit_core:
1980
1981``python_flit_core.bbclass``
1982============================
1983
1984The ``python_flit_core`` class enables building Python modules which declare
1985the `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
1986``flit_core.buildapi`` ``build-backend`` in the ``[build-system]``
1987section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
1988
1989Python modules built with ``flit_core.buildapi`` are pure Python (no
1990``C`` or ``Rust`` extensions).
1991
1992Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
1993
Andrew Geissler9aee5002022-03-30 16:27:02 +00001994.. _ref-classes-python_pep517:
1995
1996``python_pep517.bbclass``
Patrick Williams45852732022-04-02 08:58:32 -05001997=========================
Andrew Geissler9aee5002022-03-30 16:27:02 +00001998
Patrick Williams45852732022-04-02 08:58:32 -05001999The ``python_pep517`` class builds and installs a Python ``wheel`` binary
2000archive (see `PEP-517 <https://peps.python.org/pep-0517/>`__).
Andrew Geissler9aee5002022-03-30 16:27:02 +00002001
Patrick Williams45852732022-04-02 08:58:32 -05002002Recipes wouldn't inherit this directly, instead typically another class will
2003inherit this, add the relevant native dependencies, and set
2004:term:`PEP517_BUILD_API` to the Python class which implements the PEP-517 build
2005API.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002006
Patrick Williams45852732022-04-02 08:58:32 -05002007Examples of classes which do this are :ref:`python_flit_core
2008<ref-classes-python_flit_core>`, :ref:`python_setuptools_build_meta
2009<ref-classes-python_setuptools_build_meta>`, and :ref:`python_poetry_core
2010<ref-classes-python_poetry_core>`.
2011
2012.. _ref-classes-python_poetry_core:
2013
2014``python_poetry_core.bbclass``
2015==============================
2016
2017The ``python_poetry_core`` class enables building Python modules which use the
2018`Poetry Core <https://python-poetry.org>`__ build system.
2019
2020Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002021
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002022.. _ref-classes-pixbufcache:
2023
2024``pixbufcache.bbclass``
2025=======================
2026
2027The ``pixbufcache`` class generates the proper post-install and
2028post-remove (postinst/postrm) scriptlets for packages that install
2029pixbuf loaders, which are used with ``gdk-pixbuf``. These scriptlets
2030call ``update_pixbuf_cache`` to add the pixbuf loaders to the cache.
2031Since the cache files are architecture-specific, ``update_pixbuf_cache``
2032is run using QEMU if the postinst scriptlets need to be run on the build
2033host during image creation.
2034
2035If the pixbuf loaders being installed are in packages other than the
2036recipe's main package, set
2037:term:`PIXBUF_PACKAGES` to specify the packages
2038containing the loaders.
2039
2040.. _ref-classes-pkgconfig:
2041
2042``pkgconfig.bbclass``
2043=====================
2044
2045The ``pkgconfig`` class provides a standard way to get header and
2046library information by using ``pkg-config``. This class aims to smooth
2047integration of ``pkg-config`` into libraries that use it.
2048
2049During staging, BitBake installs ``pkg-config`` data into the
2050``sysroots/`` directory. By making use of sysroot functionality within
2051``pkg-config``, the ``pkgconfig`` class no longer has to manipulate the
2052files.
2053
2054.. _ref-classes-populate-sdk:
2055
2056``populate_sdk.bbclass``
2057========================
2058
2059The ``populate_sdk`` class provides support for SDK-only recipes. For
2060information on advantages gained when building a cross-development
2061toolchain using the :ref:`ref-tasks-populate_sdk`
Andrew Geissler09209ee2020-12-13 08:44:15 -06002062task, see the ":ref:`sdk-manual/appendix-obtain:building an sdk installer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002063section in the Yocto Project Application Development and the Extensible
2064Software Development Kit (eSDK) manual.
2065
2066.. _ref-classes-populate-sdk-*:
2067
2068``populate_sdk_*.bbclass``
2069==========================
2070
2071The ``populate_sdk_*`` classes support SDK creation and consist of the
2072following classes:
2073
2074- ``populate_sdk_base``: The base class supporting SDK creation under
2075 all package managers (i.e. DEB, RPM, and opkg).
2076
2077- ``populate_sdk_deb``: Supports creation of the SDK given the Debian
2078 package manager.
2079
2080- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM
2081 package manager.
2082
2083- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg
2084 (IPK format) package manager.
2085
2086- ``populate_sdk_ext``: Supports extensible SDK creation under all
2087 package managers.
2088
2089The ``populate_sdk_base`` class inherits the appropriate
2090``populate_sdk_*`` (i.e. ``deb``, ``rpm``, and ``ipk``) based on
2091:term:`IMAGE_PKGTYPE`.
2092
2093The base class ensures all source and destination directories are
2094established and then populates the SDK. After populating the SDK, the
2095``populate_sdk_base`` class constructs two sysroots:
2096``${``\ :term:`SDK_ARCH`\ ``}-nativesdk``, which
2097contains the cross-compiler and associated tooling, and the target,
2098which contains a target root filesystem that is configured for the SDK
2099usage. These two images reside in :term:`SDK_OUTPUT`,
Andrew Geisslerc926e172021-05-07 16:11:35 -05002100which consists of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002101
2102 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
2103 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
2104
2105Finally, the base populate SDK class creates the toolchain environment
2106setup script, the tarball of the SDK, and the installer.
2107
2108The respective ``populate_sdk_deb``, ``populate_sdk_rpm``, and
2109``populate_sdk_ipk`` classes each support the specific type of SDK.
2110These classes are inherited by and used with the ``populate_sdk_base``
2111class.
2112
2113For more information on the cross-development toolchain generation, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06002114the ":ref:`overview-manual/concepts:cross-development toolchain generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002115section in the Yocto Project Overview and Concepts Manual. For
2116information on advantages gained when building a cross-development
2117toolchain using the :ref:`ref-tasks-populate_sdk`
2118task, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002119":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-prexport:
2124
2125``prexport.bbclass``
2126====================
2127
2128The ``prexport`` class provides functionality for exporting
2129:term:`PR` values.
2130
2131.. note::
2132
2133 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002134 when using "``bitbake-prserv-tool export``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002135
2136.. _ref-classes-primport:
2137
2138``primport.bbclass``
2139====================
2140
2141The ``primport`` class provides functionality for importing
2142:term:`PR` values.
2143
2144.. note::
2145
2146 This class is not intended to be used directly. Rather, it is enabled
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002147 when using "``bitbake-prserv-tool import``".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002148
2149.. _ref-classes-prserv:
2150
2151``prserv.bbclass``
2152==================
2153
2154The ``prserv`` class provides functionality for using a :ref:`PR
Andrew Geissler09209ee2020-12-13 08:44:15 -06002155service <dev-manual/common-tasks:working with a pr service>` in order to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002156automatically manage the incrementing of the :term:`PR`
2157variable for each recipe.
2158
2159This class is enabled by default because it is inherited by the
2160:ref:`package <ref-classes-package>` class. However, the OpenEmbedded
2161build system will not enable the functionality of this class unless
2162:term:`PRSERV_HOST` has been set.
2163
2164.. _ref-classes-ptest:
2165
2166``ptest.bbclass``
2167=================
2168
2169The ``ptest`` class provides functionality for packaging and installing
2170runtime tests for recipes that build software that provides these tests.
2171
2172This class is intended to be inherited by individual recipes. However,
2173the class' functionality is largely disabled unless "ptest" appears in
2174:term:`DISTRO_FEATURES`. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002175":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002176section in the Yocto Project Development Tasks Manual for more information
2177on ptest.
2178
2179.. _ref-classes-ptest-gnome:
2180
2181``ptest-gnome.bbclass``
2182=======================
2183
2184Enables package tests (ptests) specifically for GNOME packages, which
2185have tests intended to be executed with ``gnome-desktop-testing``.
2186
2187For information on setting up and running ptests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002188":ref:`dev-manual/common-tasks:testing packages with ptest`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002189section in the Yocto Project Development Tasks Manual.
2190
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002191.. _ref-classes-python3-dir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002192
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002193``python3-dir.bbclass``
2194=======================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002195
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002196The ``python3-dir`` class provides the base version, location, and site
2197package location for Python 3.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002198
2199.. _ref-classes-python3native:
2200
2201``python3native.bbclass``
2202=========================
2203
2204The ``python3native`` class supports using the native version of Python
22053 built by the build system rather than support of the version provided
2206by the build host.
2207
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002208.. _ref-classes-python3targetconfig:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002209
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002210``python3targetconfig.bbclass``
2211===============================
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002212
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002213The ``python3targetconfig`` class supports using the native version of Python
22143 built by the build system rather than support of the version provided
2215by the build host, except that the configuration for the target machine
2216is accessible (such as correct installation directories). This also adds a
2217dependency on target ``python3``, so should only be used where appropriate
2218in order to avoid unnecessarily lengthening builds.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002219
2220.. _ref-classes-qemu:
2221
2222``qemu.bbclass``
2223================
2224
2225The ``qemu`` class provides functionality for recipes that either need
2226QEMU or test for the existence of QEMU. Typically, this class is used to
2227run programs for a target system on the build host using QEMU's
2228application emulation mode.
2229
2230.. _ref-classes-recipe_sanity:
2231
2232``recipe_sanity.bbclass``
2233=========================
2234
2235The ``recipe_sanity`` class checks for the presence of any host system
2236recipe prerequisites that might affect the build (e.g. variables that
2237are set or software that is present).
2238
2239.. _ref-classes-relocatable:
2240
2241``relocatable.bbclass``
2242=======================
2243
2244The ``relocatable`` class enables relocation of binaries when they are
2245installed into the sysroot.
2246
2247This class makes use of the :ref:`chrpath <ref-classes-chrpath>` class
2248and is used by both the :ref:`cross <ref-classes-cross>` and
2249:ref:`native <ref-classes-native>` classes.
2250
2251.. _ref-classes-remove-libtool:
2252
2253``remove-libtool.bbclass``
2254==========================
2255
2256The ``remove-libtool`` class adds a post function to the
2257:ref:`ref-tasks-install` task to remove all ``.la`` files
2258installed by ``libtool``. Removing these files results in them being
2259absent from both the sysroot and target packages.
2260
2261If a recipe needs the ``.la`` files to be installed, then the recipe can
Andrew Geisslerc926e172021-05-07 16:11:35 -05002262override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002263
2264 REMOVE_LIBTOOL_LA = "0"
2265
2266.. note::
2267
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002268 The ``remove-libtool`` class is not enabled by default.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002269
2270.. _ref-classes-report-error:
2271
2272``report-error.bbclass``
2273========================
2274
2275The ``report-error`` class supports enabling the :ref:`error reporting
Andrew Geissler09209ee2020-12-13 08:44:15 -06002276tool <dev-manual/common-tasks:using the error reporting tool>`",
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002277which allows you to submit build error information to a central database.
2278
2279The class collects debug information for recipe, recipe version, task,
2280machine, distro, build system, target system, host distro, branch,
2281commit, and log. From the information, report files using a JSON format
2282are created and stored in
2283``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2284
2285.. _ref-classes-rm-work:
2286
2287``rm_work.bbclass``
2288===================
2289
2290The ``rm_work`` class supports deletion of temporary workspace, which
2291can ease your hard drive demands during builds.
2292
2293The OpenEmbedded build system can use a substantial amount of disk space
2294during the build process. A portion of this space is the work files
2295under the ``${TMPDIR}/work`` directory for each recipe. Once the build
2296system generates the packages for a recipe, the work files for that
2297recipe are no longer needed. However, by default, the build system
2298preserves these files for inspection and possible debugging purposes. If
2299you would rather have these files deleted to save disk space as the
2300build progresses, you can enable ``rm_work`` by adding the following to
2301your ``local.conf`` file, which is found in the :term:`Build Directory`.
2302::
2303
2304 INHERIT += "rm_work"
2305
2306If you are
2307modifying and building source code out of the work directory for a
2308recipe, enabling ``rm_work`` will potentially result in your changes to
2309the source being lost. To exclude some recipes from having their work
2310directories deleted by ``rm_work``, you can add the names of the recipe
Andrew Geissler09036742021-06-25 14:25:14 -05002311or recipes you are working on to the :term:`RM_WORK_EXCLUDE` variable, which
Andrew Geisslerc926e172021-05-07 16:11:35 -05002312can also be set in your ``local.conf`` file. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002313
2314 RM_WORK_EXCLUDE += "busybox glibc"
2315
2316.. _ref-classes-rootfs*:
2317
2318``rootfs*.bbclass``
2319===================
2320
2321The ``rootfs*`` classes support creating the root filesystem for an
2322image and consist of the following classes:
2323
2324- The ``rootfs-postcommands`` class, which defines filesystem
2325 post-processing functions for image recipes.
2326
2327- The ``rootfs_deb`` class, which supports creation of root filesystems
2328 for images built using ``.deb`` packages.
2329
2330- The ``rootfs_rpm`` class, which supports creation of root filesystems
2331 for images built using ``.rpm`` packages.
2332
2333- The ``rootfs_ipk`` class, which supports creation of root filesystems
2334 for images built using ``.ipk`` packages.
2335
2336- The ``rootfsdebugfiles`` class, which installs additional files found
2337 on the build host directly into the root filesystem.
2338
2339The root filesystem is created from packages using one of the
2340``rootfs*.bbclass`` files as determined by the
2341:term:`PACKAGE_CLASSES` variable.
2342
2343For information on how root filesystem images are created, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002344":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002345section in the Yocto Project Overview and Concepts Manual.
2346
2347.. _ref-classes-sanity:
2348
2349``sanity.bbclass``
2350==================
2351
2352The ``sanity`` class checks to see if prerequisite software is present
2353on the host system so that users can be notified of potential problems
2354that might affect their build. The class also performs basic user
2355configuration checks from the ``local.conf`` configuration file to
2356prevent common mistakes that cause build failures. Distribution policy
2357usually determines whether to include this class.
2358
2359.. _ref-classes-scons:
2360
2361``scons.bbclass``
2362=================
2363
2364The ``scons`` class supports recipes that need to build software that
2365uses the SCons build system. You can use the
2366:term:`EXTRA_OESCONS` variable to specify
2367additional configuration options you want to pass SCons command line.
2368
2369.. _ref-classes-sdl:
2370
2371``sdl.bbclass``
2372===============
2373
2374The ``sdl`` class supports recipes that need to build software that uses
2375the Simple DirectMedia Layer (SDL) library.
2376
Patrick Williams45852732022-04-02 08:58:32 -05002377.. _ref-classes-python_setuptools_build_meta:
Andrew Geissler9aee5002022-03-30 16:27:02 +00002378
Patrick Williams45852732022-04-02 08:58:32 -05002379``python_setuptools_build_meta.bbclass``
2380========================================
Andrew Geissler9aee5002022-03-30 16:27:02 +00002381
Patrick Williams45852732022-04-02 08:58:32 -05002382The ``python_setuptools_build_meta`` class enables building Python modules which
Andrew Geissler9aee5002022-03-30 16:27:02 +00002383declare the
2384`PEP-517 <https://www.python.org/dev/peps/pep-0517/>`__ compliant
2385``setuptools.build_meta`` ``build-backend`` in the ``[build-system]``
2386section of ``pyproject.toml`` (See `PEP-518 <https://www.python.org/dev/peps/pep-0518/>`__).
2387
2388Python modules built with ``setuptools.build_meta`` can be pure Python or
2389include ``C`` or ``Rust`` extensions).
2390
Patrick Williams45852732022-04-02 08:58:32 -05002391Internally this uses the :ref:`python_pep517 <ref-classes-python_pep517>` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00002392
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002393.. _ref-classes-setuptools3:
2394
2395``setuptools3.bbclass``
2396=======================
2397
2398The ``setuptools3`` class supports Python version 3.x extensions that
Andrew Geissler9aee5002022-03-30 16:27:02 +00002399use build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and
2400have not migrated to the official ``pyproject.toml`` format). If your recipe
2401uses these build systems, the recipe needs to inherit the ``setuptools3`` class.
2402
2403 .. note::
2404
2405 The ``setuptools3`` class ``do_compile()`` task now calls
2406 ``setup.py bdist_wheel`` to build the ``wheel`` binary archive format
2407 (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__).
2408
2409 A consequence of this is that legacy software still using deprecated
2410 ``distutils`` from the Python standard library cannot be packaged as
2411 ``wheels``. A common solution is the replace
2412 ``from distutils.core import setup`` with ``from setuptools import setup``.
2413
2414 .. note::
2415
2416 The ``setuptools3`` class ``do_install()`` task now installs the ``wheel``
2417 binary archive. In current versions of ``setuptools`` the legacy ``setup.py
2418 install`` method is deprecated. If the ``setup.py`` cannot be used with
2419 wheels, for example it creates files outside of the Python module or
2420 standard entry points, then :ref:`setuptools3_legacy
2421 <ref-classes-setuptools3_legacy>` should be used.
2422
2423.. _ref-classes-setuptools3_legacy:
2424
2425``setuptools3_legacy.bbclass``
2426==============================
2427
2428The ``setuptools3_legacy`` class supports Python version 3.x extensions that use
2429build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and have
2430not migrated to the official ``pyproject.toml`` format). Unlike
2431``setuptools3.bbclass``, this uses the traditional ``setup.py`` ``build`` and
2432``install`` commands and not wheels. This use of ``setuptools`` like this is
2433`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`_
2434but still relatively common.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002435
Andrew Geissler595f6302022-01-24 19:11:47 +00002436.. _ref-classes-setuptools3-base:
2437
2438``setuptools3-base.bbclass``
2439============================
2440
2441The ``setuptools3-base`` class provides a reusable base for other classes
2442that support building Python version 3.x extensions. If you need
2443functionality that is not provided by the :ref:`setuptools3 <ref-classes-setuptools3>` class, you may
2444want to ``inherit setuptools3-base``. Some recipes do not need the tasks
2445in the :ref:`setuptools3 <ref-classes-setuptools3>` class and inherit this class instead.
2446
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002447.. _ref-classes-sign_rpm:
2448
2449``sign_rpm.bbclass``
2450====================
2451
2452The ``sign_rpm`` class supports generating signed RPM packages.
2453
2454.. _ref-classes-sip:
2455
2456``sip.bbclass``
2457===============
2458
2459The ``sip`` class supports recipes that build or package SIP-based
2460Python bindings.
2461
2462.. _ref-classes-siteconfig:
2463
2464``siteconfig.bbclass``
2465======================
2466
2467The ``siteconfig`` class provides functionality for handling site
2468configuration. The class is used by the
2469:ref:`autotools <ref-classes-autotools>` class to accelerate the
2470:ref:`ref-tasks-configure` task.
2471
2472.. _ref-classes-siteinfo:
2473
2474``siteinfo.bbclass``
2475====================
2476
2477The ``siteinfo`` class provides information about the targets that might
2478be needed by other classes or recipes.
2479
2480As an example, consider Autotools, which can require tests that must
2481execute on the target hardware. Since this is not possible in general
2482when cross compiling, site information is used to provide cached test
2483results so these tests can be skipped over but still make the correct
2484values available. The ``meta/site directory`` contains test results
2485sorted into different categories such as architecture, endianness, and
2486the ``libc`` used. Site information provides a list of files containing
Andrew Geissler09036742021-06-25 14:25:14 -05002487data relevant to the current build in the :term:`CONFIG_SITE` variable that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002488Autotools automatically picks up.
2489
Andrew Geissler09036742021-06-25 14:25:14 -05002490The class also provides variables like :term:`SITEINFO_ENDIANNESS` and
2491:term:`SITEINFO_BITS` that can be used elsewhere in the metadata.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002492
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002493.. _ref-classes-sstate:
2494
2495``sstate.bbclass``
2496==================
2497
2498The ``sstate`` class provides support for Shared State (sstate). By
2499default, the class is enabled through the
2500:term:`INHERIT_DISTRO` variable's default value.
2501
2502For more information on sstate, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002503":ref:`overview-manual/concepts:shared state cache`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002504section in the Yocto Project Overview and Concepts Manual.
2505
2506.. _ref-classes-staging:
2507
2508``staging.bbclass``
2509===================
2510
2511The ``staging`` class installs files into individual recipe work
2512directories for sysroots. The class contains the following key tasks:
2513
2514- The :ref:`ref-tasks-populate_sysroot` task,
2515 which is responsible for handing the files that end up in the recipe
2516 sysroots.
2517
2518- The
2519 :ref:`ref-tasks-prepare_recipe_sysroot`
2520 task (a "partner" task to the ``populate_sysroot`` task), which
2521 installs the files into the individual recipe work directories (i.e.
2522 :term:`WORKDIR`).
2523
2524The code in the ``staging`` class is complex and basically works in two
2525stages:
2526
2527- *Stage One:* The first stage addresses recipes that have files they
2528 want to share with other recipes that have dependencies on the
2529 originating recipe. Normally these dependencies are installed through
2530 the :ref:`ref-tasks-install` task into
2531 ``${``\ :term:`D`\ ``}``. The ``do_populate_sysroot`` task
2532 copies a subset of these files into ``${SYSROOT_DESTDIR}``. This
2533 subset of files is controlled by the
2534 :term:`SYSROOT_DIRS`,
2535 :term:`SYSROOT_DIRS_NATIVE`, and
Andrew Geissler9aee5002022-03-30 16:27:02 +00002536 :term:`SYSROOT_DIRS_IGNORE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002537 variables.
2538
2539 .. note::
2540
2541 Additionally, a recipe can customize the files further by
Andrew Geissler09036742021-06-25 14:25:14 -05002542 declaring a processing function in the :term:`SYSROOT_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002543 variable.
2544
2545 A shared state (sstate) object is built from these files and the
2546 files are placed into a subdirectory of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002547 :ref:`structure-build-tmp-sysroots-components`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002548 The files are scanned for hardcoded paths to the original
2549 installation location. If the location is found in text files, the
2550 hardcoded locations are replaced by tokens and a list of the files
2551 needing such replacements is created. These adjustments are referred
2552 to as "FIXMEs". The list of files that are scanned for paths is
2553 controlled by the :term:`SSTATE_SCAN_FILES`
2554 variable.
2555
2556- *Stage Two:* The second stage addresses recipes that want to use
2557 something from another recipe and declare a dependency on that recipe
2558 through the :term:`DEPENDS` variable. The recipe will
2559 have a
2560 :ref:`ref-tasks-prepare_recipe_sysroot`
2561 task and when this task executes, it creates the ``recipe-sysroot``
2562 and ``recipe-sysroot-native`` in the recipe work directory (i.e.
2563 :term:`WORKDIR`). The OpenEmbedded build system
2564 creates hard links to copies of the relevant files from
2565 ``sysroots-components`` into the recipe work directory.
2566
2567 .. note::
2568
2569 If hard links are not possible, the build system uses actual
2570 copies.
2571
2572 The build system then addresses any "FIXMEs" to paths as defined from
2573 the list created in the first stage.
2574
2575 Finally, any files in ``${bindir}`` within the sysroot that have the
2576 prefix "``postinst-``" are executed.
2577
2578 .. note::
2579
2580 Although such sysroot post installation scripts are not
2581 recommended for general use, the files do allow some issues such
2582 as user creation and module indexes to be addressed.
2583
Andrew Geissler09036742021-06-25 14:25:14 -05002584 Because recipes can have other dependencies outside of :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002585 (e.g. ``do_unpack[depends] += "tar-native:do_populate_sysroot"``),
2586 the sysroot creation function ``extend_recipe_sysroot`` is also added
2587 as a pre-function for those tasks whose dependencies are not through
Andrew Geissler09036742021-06-25 14:25:14 -05002588 :term:`DEPENDS` but operate similarly.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002589
2590 When installing dependencies into the sysroot, the code traverses the
2591 dependency graph and processes dependencies in exactly the same way
2592 as the dependencies would or would not be when installed from sstate.
2593 This processing means, for example, a native tool would have its
2594 native dependencies added but a target library would not have its
2595 dependencies traversed or installed. The same sstate dependency code
2596 is used so that builds should be identical regardless of whether
2597 sstate was used or not. For a closer look, see the
2598 ``setscene_depvalid()`` function in the
2599 :ref:`sstate <ref-classes-sstate>` class.
2600
2601 The build system is careful to maintain manifests of the files it
2602 installs so that any given dependency can be installed as needed. The
2603 sstate hash of the installed item is also stored so that if it
2604 changes, the build system can reinstall it.
2605
2606.. _ref-classes-syslinux:
2607
2608``syslinux.bbclass``
2609====================
2610
2611The ``syslinux`` class provides syslinux-specific functions for building
2612bootable images.
2613
2614The class supports the following variables:
2615
2616- :term:`INITRD`: Indicates list of filesystem images to
2617 concatenate and use as an initial RAM disk (initrd). This variable is
2618 optional.
2619
2620- :term:`ROOTFS`: Indicates a filesystem image to include
2621 as the root filesystem. This variable is optional.
2622
2623- :term:`AUTO_SYSLINUXMENU`: Enables creating
2624 an automatic menu when set to "1".
2625
2626- :term:`LABELS`: Lists targets for automatic
2627 configuration.
2628
2629- :term:`APPEND`: Lists append string overrides for each
2630 label.
2631
2632- :term:`SYSLINUX_OPTS`: Lists additional options
2633 to add to the syslinux file. Semicolon characters separate multiple
2634 options.
2635
2636- :term:`SYSLINUX_SPLASH`: Lists a background
2637 for the VGA boot menu when you are using the boot menu.
2638
2639- :term:`SYSLINUX_DEFAULT_CONSOLE`: Set
2640 to "console=ttyX" to change kernel boot default console.
2641
2642- :term:`SYSLINUX_SERIAL`: Sets an alternate
2643 serial port. Or, turns off serial when the variable is set with an
2644 empty string.
2645
2646- :term:`SYSLINUX_SERIAL_TTY`: Sets an
2647 alternate "console=tty..." kernel boot argument.
2648
2649.. _ref-classes-systemd:
2650
2651``systemd.bbclass``
2652===================
2653
2654The ``systemd`` class provides support for recipes that install systemd
2655unit files.
2656
2657The functionality for this class is disabled unless you have "systemd"
2658in :term:`DISTRO_FEATURES`.
2659
2660Under this class, the recipe or Makefile (i.e. whatever the recipe is
2661calling during the :ref:`ref-tasks-install` task)
2662installs unit files into
2663``${``\ :term:`D`\ ``}${systemd_unitdir}/system``. If the unit
2664files being installed go into packages other than the main package, you
2665need to set :term:`SYSTEMD_PACKAGES` in your
2666recipe to identify the packages in which the files will be installed.
2667
2668You should set :term:`SYSTEMD_SERVICE` to the
2669name of the service file. You should also use a package name override to
2670indicate the package to which the value applies. If the value applies to
2671the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
Andrew Geisslerc926e172021-05-07 16:11:35 -05002672is an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002673
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002674 SYSTEMD_SERVICE:${PN} = "connman.service"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002675
2676Services are set up to start on boot automatically
2677unless you have set
2678:term:`SYSTEMD_AUTO_ENABLE` to "disable".
2679
2680For more information on ``systemd``, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002681":ref:`dev-manual/common-tasks:selecting an initialization manager`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002682section in the Yocto Project Development Tasks Manual.
2683
2684.. _ref-classes-systemd-boot:
2685
2686``systemd-boot.bbclass``
2687========================
2688
2689The ``systemd-boot`` class provides functions specific to the
2690systemd-boot bootloader for building bootable images. This is an
2691internal class and is not intended to be used directly.
2692
2693.. note::
2694
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002695 The ``systemd-boot`` class is a result from merging the ``gummiboot`` class
2696 used in previous Yocto Project releases with the ``systemd`` project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002697
2698Set the :term:`EFI_PROVIDER` variable to
2699"systemd-boot" to use this class. Doing so creates a standalone EFI
2700bootloader that is not dependent on systemd.
2701
2702For information on more variables used and supported in this class, see
2703the :term:`SYSTEMD_BOOT_CFG`,
2704:term:`SYSTEMD_BOOT_ENTRIES`, and
2705:term:`SYSTEMD_BOOT_TIMEOUT` variables.
2706
2707You can also see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002708documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002709for more information.
2710
2711.. _ref-classes-terminal:
2712
2713``terminal.bbclass``
2714====================
2715
2716The ``terminal`` class provides support for starting a terminal session.
2717The :term:`OE_TERMINAL` variable controls which
2718terminal emulator is used for the session.
2719
2720Other classes use the ``terminal`` class anywhere a separate terminal
2721session needs to be started. For example, the
2722:ref:`patch <ref-classes-patch>` class assuming
2723:term:`PATCHRESOLVE` is set to "user", the
2724:ref:`cml1 <ref-classes-cml1>` class, and the
2725:ref:`devshell <ref-classes-devshell>` class all use the ``terminal``
2726class.
2727
2728.. _ref-classes-testimage*:
2729
2730``testimage*.bbclass``
2731======================
2732
2733The ``testimage*`` classes support running automated tests against
2734images using QEMU and on actual hardware. The classes handle loading the
2735tests and starting the image. To use the classes, you need to perform
2736steps to set up the environment.
2737
2738.. note::
2739
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002740 Best practices include using :term:`IMAGE_CLASSES` rather than
2741 :term:`INHERIT` to inherit the ``testimage`` class for automated image
2742 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002743
2744The tests are commands that run on the target system over ``ssh``. Each
2745test is written in Python and makes use of the ``unittest`` module.
2746
2747The ``testimage.bbclass`` runs tests on an image when called using the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002748following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002749
2750 $ bitbake -c testimage image
2751
2752The ``testimage-auto`` class
2753runs tests on an image after the image is constructed (i.e.
2754:term:`TESTIMAGE_AUTO` must be set to "1").
2755
2756For information on how to enable, run, and create new tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002757":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002758section in the Yocto Project Development Tasks Manual.
2759
2760.. _ref-classes-testsdk:
2761
2762``testsdk.bbclass``
2763===================
2764
2765This class supports running automated tests against software development
2766kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
Andrew Geisslerc926e172021-05-07 16:11:35 -05002767using the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002768
2769 $ bitbake -c testsdk image
2770
2771.. note::
2772
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002773 Best practices include using :term:`IMAGE_CLASSES` rather than
2774 :term:`INHERIT` to inherit the ``testsdk`` class for automated SDK
2775 testing.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002776
2777.. _ref-classes-texinfo:
2778
2779``texinfo.bbclass``
2780===================
2781
2782This class should be inherited by recipes whose upstream packages invoke
2783the ``texinfo`` utilities at build-time. Native and cross recipes are
2784made to use the dummy scripts provided by ``texinfo-dummy-native``, for
2785improved performance. Target architecture recipes use the genuine
2786Texinfo utilities. By default, they use the Texinfo utilities on the
2787host system.
2788
2789.. note::
2790
2791 If you want to use the Texinfo recipe shipped with the build system,
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002792 you can remove "texinfo-native" from :term:`ASSUME_PROVIDED` and makeinfo
2793 from :term:`SANITY_REQUIRED_UTILITIES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002794
2795.. _ref-classes-toaster:
2796
2797``toaster.bbclass``
2798===================
2799
2800The ``toaster`` class collects information about packages and images and
2801sends them as events that the BitBake user interface can receive. The
2802class is enabled when the Toaster user interface is running.
2803
2804This class is not intended to be used directly.
2805
2806.. _ref-classes-toolchain-scripts:
2807
2808``toolchain-scripts.bbclass``
2809=============================
2810
2811The ``toolchain-scripts`` class provides the scripts used for setting up
2812the environment for installed SDKs.
2813
2814.. _ref-classes-typecheck:
2815
2816``typecheck.bbclass``
2817=====================
2818
2819The ``typecheck`` class provides support for validating the values of
2820variables set at the configuration level against their defined types.
2821The OpenEmbedded build system allows you to define the type of a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002822variable using the "type" varflag. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002823
2824 IMAGE_FEATURES[type] = "list"
2825
2826.. _ref-classes-uboot-config:
2827
2828``uboot-config.bbclass``
2829========================
2830
2831The ``uboot-config`` class provides support for U-Boot configuration for
Andrew Geisslerc926e172021-05-07 16:11:35 -05002832a machine. Specify the machine in your recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002833
2834 UBOOT_CONFIG ??= <default>
2835 UBOOT_CONFIG[foo] = "config,images"
2836
Andrew Geisslerc926e172021-05-07 16:11:35 -05002837You can also specify the machine using this method::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002838
2839 UBOOT_MACHINE = "config"
2840
2841See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
2842information.
2843
2844.. _ref-classes-uninative:
2845
2846``uninative.bbclass``
2847=====================
2848
2849Attempts to isolate the build system from the host distribution's C
2850library in order to make re-use of native shared state artifacts across
2851different host distributions practical. With this class enabled, a
2852tarball containing a pre-built C library is downloaded at the start of
2853the build. In the Poky reference distribution this is enabled by default
2854through ``meta/conf/distro/include/yocto-uninative.inc``. Other
2855distributions that do not derive from poky can also
2856"``require conf/distro/include/yocto-uninative.inc``" to use this.
2857Alternatively if you prefer, you can build the uninative-tarball recipe
2858yourself, publish the resulting tarball (e.g. via HTTP) and set
2859``UNINATIVE_URL`` and ``UNINATIVE_CHECKSUM`` appropriately. For an
2860example, see the ``meta/conf/distro/include/yocto-uninative.inc``.
2861
2862The ``uninative`` class is also used unconditionally by the extensible
2863SDK. When building the extensible SDK, ``uninative-tarball`` is built
2864and the resulting tarball is included within the SDK.
2865
2866.. _ref-classes-update-alternatives:
2867
2868``update-alternatives.bbclass``
2869===============================
2870
2871The ``update-alternatives`` class helps the alternatives system when
2872multiple sources provide the same command. This situation occurs when
2873several programs that have the same or similar function are installed
2874with the same name. For example, the ``ar`` command is available from
2875the ``busybox``, ``binutils`` and ``elfutils`` packages. The
2876``update-alternatives`` class handles renaming the binaries so that
2877multiple packages can be installed without conflicts. The ``ar`` command
2878still works regardless of which packages are installed or subsequently
2879removed. The class renames the conflicting binary in each package and
2880symlinks the highest priority binary during installation or removal of
2881packages.
2882
2883To use this class, you need to define a number of variables:
2884
2885- :term:`ALTERNATIVE`
2886
2887- :term:`ALTERNATIVE_LINK_NAME`
2888
2889- :term:`ALTERNATIVE_TARGET`
2890
2891- :term:`ALTERNATIVE_PRIORITY`
2892
2893These variables list alternative commands needed by a package, provide
2894pathnames for links, default links for targets, and so forth. For
2895details on how to use this class, see the comments in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002896:yocto_git:`update-alternatives.bbclass </poky/tree/meta/classes/update-alternatives.bbclass>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002897file.
2898
2899.. note::
2900
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002901 You can use the ``update-alternatives`` command directly in your recipes.
2902 However, this class simplifies things in most cases.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002903
2904.. _ref-classes-update-rc.d:
2905
2906``update-rc.d.bbclass``
2907=======================
2908
2909The ``update-rc.d`` class uses ``update-rc.d`` to safely install an
2910initialization script on behalf of the package. The OpenEmbedded build
2911system takes care of details such as making sure the script is stopped
2912before a package is removed and started when the package is installed.
2913
Andrew Geissler09036742021-06-25 14:25:14 -05002914Three variables control this class: :term:`INITSCRIPT_PACKAGES`,
2915:term:`INITSCRIPT_NAME` and :term:`INITSCRIPT_PARAMS`. See the variable links
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002916for details.
2917
2918.. _ref-classes-useradd:
2919
2920``useradd*.bbclass``
2921====================
2922
2923The ``useradd*`` classes support the addition of users or groups for
2924usage by the package on the target. For example, if you have packages
2925that contain system services that should be run under their own user or
2926group, you can use these classes to enable creation of the user or
Andrew Geissler595f6302022-01-24 19:11:47 +00002927group. The :oe_git:`meta-skeleton/recipes-skeleton/useradd/useradd-example.bb
2928</openembedded-core/tree/meta-skeleton/recipes-skeleton/useradd/useradd-example.bb>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002929recipe in the :term:`Source Directory` provides a simple
2930example that shows how to add three users and groups to two packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002931
2932The ``useradd_base`` class provides basic functionality for user or
2933groups settings.
2934
2935The ``useradd*`` classes support the
2936:term:`USERADD_PACKAGES`,
2937:term:`USERADD_PARAM`,
2938:term:`GROUPADD_PARAM`, and
2939:term:`GROUPMEMS_PARAM` variables.
2940
2941The ``useradd-staticids`` class supports the addition of users or groups
2942that have static user identification (``uid``) and group identification
2943(``gid``) values.
2944
2945The default behavior of the OpenEmbedded build system for assigning
2946``uid`` and ``gid`` values when packages add users and groups during
2947package install time is to add them dynamically. This works fine for
2948programs that do not care what the values of the resulting users and
2949groups become. In these cases, the order of the installation determines
2950the final ``uid`` and ``gid`` values. However, if non-deterministic
2951``uid`` and ``gid`` values are a problem, you can override the default,
2952dynamic application of these values by setting static values. When you
2953set static values, the OpenEmbedded build system looks in
2954:term:`BBPATH` for ``files/passwd`` and ``files/group``
2955files for the values.
2956
2957To use static ``uid`` and ``gid`` values, you need to set some
2958variables. See the :term:`USERADDEXTENSION`,
2959:term:`USERADD_UID_TABLES`,
2960:term:`USERADD_GID_TABLES`, and
2961:term:`USERADD_ERROR_DYNAMIC` variables.
2962You can also see the :ref:`useradd <ref-classes-useradd>` class for
2963additional information.
2964
2965.. note::
2966
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002967 You do not use the ``useradd-staticids`` class directly. You either enable
Andrew Geissler09036742021-06-25 14:25:14 -05002968 or disable the class by setting the :term:`USERADDEXTENSION` variable. If you
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002969 enable or disable the class in a configured system, :term:`TMPDIR` might
Andrew Geissler09036742021-06-25 14:25:14 -05002970 contain incorrect ``uid`` and ``gid`` values. Deleting the :term:`TMPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002971 directory will correct this condition.
2972
2973.. _ref-classes-utility-tasks:
2974
2975``utility-tasks.bbclass``
2976=========================
2977
2978The ``utility-tasks`` class provides support for various "utility" type
2979tasks that are applicable to all recipes, such as
2980:ref:`ref-tasks-clean` and
2981:ref:`ref-tasks-listtasks`.
2982
2983This class is enabled by default because it is inherited by the
2984:ref:`base <ref-classes-base>` class.
2985
2986.. _ref-classes-utils:
2987
2988``utils.bbclass``
2989=================
2990
2991The ``utils`` class provides some useful Python functions that are
2992typically used in inline Python expressions (e.g. ``${@...}``). One
2993example use is for ``bb.utils.contains()``.
2994
2995This class is enabled by default because it is inherited by the
2996:ref:`base <ref-classes-base>` class.
2997
2998.. _ref-classes-vala:
2999
3000``vala.bbclass``
3001================
3002
3003The ``vala`` class supports recipes that need to build software written
3004using the Vala programming language.
3005
3006.. _ref-classes-waf:
3007
3008``waf.bbclass``
3009===============
3010
3011The ``waf`` class supports recipes that need to build software that uses
3012the Waf build system. You can use the
3013:term:`EXTRA_OECONF` or
3014:term:`PACKAGECONFIG_CONFARGS` variables
3015to specify additional configuration options to be passed on the Waf
3016command line.