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