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