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