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