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