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