Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/ref-manual/ref-classes.xml b/poky/documentation/ref-manual/ref-classes.xml
new file mode 100644
index 0000000..1dcd5fd
--- /dev/null
+++ b/poky/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,3974 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='ref-classes'>
+<title>Classes</title>
+
+<para>
+ Class files are used to abstract common functionality and share it amongst
+ multiple recipe (<filename>.bb</filename>) files.
+ To use a class file, you simply make sure the recipe inherits the class.
+ In most cases, when a recipe inherits a class it is enough to enable its
+ features.
+ There are cases, however, where in the recipe you might need to set
+ variables or override some default behavior.
+</para>
+
+<para>
+ Any <link linkend='metadata'>Metadata</link> usually
+ found in a recipe can also be placed in a class file.
+ Class files are identified by the extension <filename>.bbclass</filename>
+ and are usually placed in a <filename>classes/</filename> directory beneath
+ the <filename>meta*/</filename> directory found in the
+ <link linkend='source-directory'>Source Directory</link>.
+ Class files can also be pointed to by
+ <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
+ (e.g. <filename>build/</filename>) in the same way as
+ <filename>.conf</filename> files in the <filename>conf</filename> directory.
+ Class files are searched for in
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+ using the same method by which <filename>.conf</filename> files are
+ searched.
+</para>
+
+<para>
+ This chapter discusses only the most useful and important classes.
+ Other classes do exist within the <filename>meta/classes</filename>
+ directory in the Source Directory.
+ You can reference the <filename>.bbclass</filename> files directly
+ for more information.
+</para>
+
+<section id='ref-classes-allarch'>
+ <title><filename>allarch.bbclass</filename></title>
+
+ <para>
+ The <filename>allarch</filename> class is inherited
+ by recipes that do not produce architecture-specific output.
+ The class disables functionality that is normally needed for recipes
+ that produce executable binaries (such as building the cross-compiler
+ and a C library as pre-requisites, and splitting out of debug symbols
+ during packaging).
+ <note>
+ <para>Unlike some distro recipes (e.g. Debian), OpenEmbedded recipes
+ that produce packages that depend on tunings through use of the
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+ and
+ <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
+ variables, should never be configured for all architectures
+ using <filename>allarch</filename>.
+ This is the case even if the recipes do not produce
+ architecture-specific output.</para>
+ <para>Configuring such recipes for all architectures causes the
+ <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>
+ tasks to have different signatures for the machines with different
+ tunings.
+ Additionally, unnecessary rebuilds occur every time an
+ image for a different <filename>MACHINE</filename> is built
+ even when the recipe never changes.</para>
+ </note>
+ </para>
+
+ <para>
+ By default, all recipes inherit the
+ <link linkend='ref-classes-base'><filename>base</filename></link> and
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ classes, which enable functionality
+ needed for recipes that produce executable output.
+ If your recipe, for example, only produces packages that contain
+ configuration files, media files, or scripts (e.g. Python and Perl),
+ then it should inherit the <filename>allarch</filename> class.
+ </para>
+</section>
+
+<section id='ref-classes-archiver'>
+ <title><filename>archiver.bbclass</filename></title>
+
+ <para>
+ The <filename>archiver</filename> class supports releasing
+ source code and other materials with the binaries.
+ </para>
+
+ <para>
+ For more details on the source archiver, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ You can also see the
+ <link linkend='var-ARCHIVER_MODE'><filename>ARCHIVER_MODE</filename></link>
+ variable for information about the variable flags (varflags)
+ that help control archive creation.
+ </para>
+</section>
+
+<section id='ref-classes-autotools'>
+ <title><filename>autotools*.bbclass</filename></title>
+
+ <para>
+ The <filename>autotools*</filename> classes support Autotooled
+ packages.
+ </para>
+
+ <para>
+ The <filename>autoconf</filename>, <filename>automake</filename>,
+ and <filename>libtool</filename> packages bring standardization.
+ This class defines a set of tasks (e.g.
+ <filename>configure</filename>, <filename>compile</filename> and
+ so forth) that
+ work for all Autotooled packages.
+ It should usually be enough to define a few standard variables
+ and then simply <filename>inherit autotools</filename>.
+ These classes can also work with software that emulates Autotools.
+ For more information, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ By default, the <filename>autotools*</filename> classes
+ use out-of-tree builds (i.e.
+ <filename>autotools.bbclass</filename> building with
+ <filename>B != S</filename>).
+ </para>
+
+ <para>
+ If the software being built by a recipe does not support
+ using out-of-tree builds, you should have the recipe inherit the
+ <filename>autotools-brokensep</filename> class.
+ The <filename>autotools-brokensep</filename> class behaves the same
+ as the <filename>autotools</filename> class but builds with
+ <link linkend='var-B'><filename>B</filename></link> ==
+ <link linkend='var-S'><filename>S</filename></link>.
+ This method is useful when out-of-tree build support is either not
+ present or is broken.
+ <note>
+ It is recommended that out-of-tree support be fixed and used
+ if at all possible.
+ </note>
+ </para>
+
+ <para>
+ It's useful to have some idea of how the tasks defined by
+ the <filename>autotools*</filename> classes work and what they do
+ behind the scenes.
+ <itemizedlist>
+ <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
+ Regenerates the
+ configure script (using <filename>autoreconf</filename>) and
+ then launches it with a standard set of arguments used during
+ cross-compilation.
+ You can pass additional parameters to
+ <filename>configure</filename> through the
+ <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename>
+ or
+ <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
+ variables.
+ </para></listitem>
+ <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
+ Runs <filename>make</filename> with arguments that specify the
+ compiler and linker.
+ You can pass additional arguments through
+ the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename>
+ variable.
+ </para></listitem>
+ <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
+ Runs <filename>make install</filename> and passes in
+ <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
+ as <filename>DESTDIR</filename>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='ref-classes-base'>
+ <title><filename>base.bbclass</filename></title>
+
+ <para>
+ The <filename>base</filename> class is special in that every
+ <filename>.bb</filename> file implicitly inherits the class.
+ This class contains definitions for standard basic
+ tasks such as fetching, unpacking, configuring (empty by default),
+ compiling (runs any <filename>Makefile</filename> present), installing
+ (empty by default) and packaging (empty by default).
+ These classes are often overridden or extended by other classes
+ such as the
+ <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
+ class or the
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ class.
+ </para>
+
+ <para>
+ The class also contains some commonly used functions such as
+ <filename>oe_runmake</filename>, which runs
+ <filename>make</filename> with the arguments specified in
+ <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link>
+ variable as well as the arguments passed directly to
+ <filename>oe_runmake</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-bash-completion'>
+ <title><filename>bash-completion.bbclass</filename></title>
+
+ <para>
+ Sets up packaging and dependencies appropriate for recipes that
+ build software that includes bash-completion data.
+ </para>
+</section>
+
+<section id='ref-classes-bin-package'>
+ <title><filename>bin_package.bbclass</filename></title>
+
+ <para>
+ The <filename>bin_package</filename> class is a
+ helper class for recipes that extract the contents of a binary package
+ (e.g. an RPM) and install those contents rather than building the
+ binary from source.
+ The binary package is extracted and new packages in the configured
+ output package format are created.
+ Extraction and installation of proprietary binaries is a good example
+ use for this class.
+ <note>
+ For RPMs and other packages that do not contain a subdirectory,
+ you should specify an appropriate fetcher parameter to point to
+ the subdirectory.
+ For example, if BitBake is using the Git fetcher
+ (<filename>git://</filename>), the "subpath" parameter limits
+ the checkout to a specific subpath of the tree.
+ Here is an example where <filename>${BP}</filename> is used so that
+ the files are extracted into the subdirectory expected by the
+ default value of
+ <link linkend='var-S'><filename>S</filename></link>:
+ <literallayout class='monospaced'>
+ SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
+ </literallayout>
+ See the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#bb-fetchers'>Fetchers</ulink>"
+ section in the BitBake User Manual for more information on
+ supported BitBake Fetchers.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-binconfig'>
+ <title><filename>binconfig.bbclass</filename></title>
+
+ <para>
+ The <filename>binconfig</filename> class helps to correct paths in
+ shell scripts.
+ </para>
+
+ <para>
+ Before <filename>pkg-config</filename> had become widespread, libraries
+ shipped shell scripts to give information about the libraries and
+ include paths needed to build software (usually named
+ <filename>LIBNAME-config</filename>).
+ This class assists any recipe using such scripts.
+ </para>
+
+ <para>
+ During staging, the OpenEmbedded build system installs such scripts
+ into the <filename>sysroots/</filename> directory.
+ Inheriting this class results in all paths in these scripts being
+ changed to point into the <filename>sysroots/</filename> directory so
+ that all builds that use the script use the correct directories
+ for the cross compiling layout.
+ See the
+ <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
+ variable for more information.
+ </para>
+</section>
+
+<section id='ref-classes-binconfig-disabled'>
+ <title><filename>binconfig-disabled.bbclass</filename></title>
+
+ <para>
+ An alternative version of the
+ <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link>
+ class, which disables binary configuration scripts by making them
+ return an error in favor of using <filename>pkg-config</filename>
+ to query the information.
+ The scripts to be disabled should be specified using the
+ <link linkend='var-BINCONFIG'><filename>BINCONFIG</filename></link>
+ variable within the recipe inheriting the class.
+ </para>
+</section>
+
+<section id='ref-classes-blacklist'>
+ <title><filename>blacklist.bbclass</filename></title>
+
+ <para>
+ The <filename>blacklist</filename> class prevents
+ the OpenEmbedded build system from building specific recipes
+ (blacklists them).
+ To use this class, inherit the class globally and set
+ <link linkend='var-PNBLACKLIST'><filename>PNBLACKLIST</filename></link>
+ for each recipe you wish to blacklist.
+ Specify the <link linkend='var-PN'><filename>PN</filename></link>
+ value as a variable flag (varflag) and provide a reason, which is
+ reported, if the package is requested to be built as the value.
+ For example, if you want to blacklist a recipe called "exoticware",
+ you add the following to your <filename>local.conf</filename>
+ or distribution configuration:
+ <literallayout class='monospaced'>
+ INHERIT += "blacklist"
+ PNBLACKLIST[exoticware] = "Not supported by our organization."
+ </literallayout>
+ </para>
+</section>
+
+<section id='ref-classes-buildhistory'>
+ <title><filename>buildhistory.bbclass</filename></title>
+
+ <para>
+ The <filename>buildhistory</filename> class records a
+ history of build output metadata, which can be used to detect possible
+ regressions as well as used for analysis of the build output.
+ For more information on using Build History, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='ref-classes-buildstats'>
+ <title><filename>buildstats.bbclass</filename></title>
+
+ <para>
+ The <filename>buildstats</filename> class records
+ performance statistics about each task executed during the build
+ (e.g. elapsed time, CPU usage, and I/O usage).
+ </para>
+
+ <para>
+ When you use this class, the output goes into the
+ <link linkend='var-BUILDSTATS_BASE'><filename>BUILDSTATS_BASE</filename></link>
+ directory, which defaults to <filename>${TMPDIR}/buildstats/</filename>.
+ You can analyze the elapsed time using
+ <filename>scripts/pybootchartgui/pybootchartgui.py</filename>, which
+ produces a cascading chart of the entire build process and can be
+ useful for highlighting bottlenecks.
+ </para>
+
+ <para>
+ Collecting build statistics is enabled by default through the
+ <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
+ variable from your <filename>local.conf</filename> file.
+ Consequently, you do not have to do anything to enable the class.
+ However, if you want to disable the class, simply remove "buildstats"
+ from the <filename>USER_CLASSES</filename> list.
+ </para>
+</section>
+
+<section id='ref-classes-buildstats-summary'>
+ <title><filename>buildstats-summary.bbclass</filename></title>
+
+ <para>
+ When inherited globally, prints statistics at the end of the build
+ on sstate re-use.
+ In order to function, this class requires the
+ <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link>
+ class be enabled.
+ </para>
+</section>
+
+<section id='ref-classes-ccache'>
+ <title><filename>ccache.bbclass</filename></title>
+
+ <para>
+ The <filename>ccache</filename> class enables the C/C++ Compiler Cache
+ for the build.
+ This class is used to give a minor performance boost during the build.
+ However, using the class can lead to unexpected side-effects.
+ Thus, it is recommended that you do not use this class.
+ See <ulink url='http://ccache.samba.org/'></ulink> for information on
+ the C/C++ Compiler Cache.
+ </para>
+</section>
+
+<section id='ref-classes-chrpath'>
+ <title><filename>chrpath.bbclass</filename></title>
+
+ <para>
+ The <filename>chrpath</filename> class
+ is a wrapper around the "chrpath" utility, which is used during the
+ build process for <filename>nativesdk</filename>,
+ <filename>cross</filename>, and
+ <filename>cross-canadian</filename> recipes to change
+ <filename>RPATH</filename> records within binaries in order to make
+ them relocatable.
+ </para>
+</section>
+
+<section id='ref-classes-clutter'>
+ <title><filename>clutter.bbclass</filename></title>
+
+ <para>
+ The <filename>clutter</filename> class consolidates the
+ major and minor version naming and other common items used by Clutter
+ and related recipes.
+ <note>
+ Unlike some other classes related to specific libraries, recipes
+ building other software that uses Clutter do not need to
+ inherit this class unless they use the same recipe versioning
+ scheme that the Clutter and related recipes do.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-cmake'>
+ <title><filename>cmake.bbclass</filename></title>
+
+ <para>
+ The <filename>cmake</filename> class allows for recipes that need to
+ build software using the
+ <ulink url='https://cmake.org/overview/'>CMake</ulink> build system.
+ You can use the
+ <link linkend='var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></link>
+ variable to specify additional configuration options to be passed
+ using the <filename>cmake</filename> command line.
+ </para>
+
+ <para>
+ On the occasion that you would be installing custom CMake toolchain
+ files supplied by the application being built, you should install them
+ to the preferred CMake Module directory:
+ <filename>${D}${datadir}/cmake/</filename> Modules during
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>.
+ </para>
+</section>
+
+<section id='ref-classes-cml1'>
+ <title><filename>cml1.bbclass</filename></title>
+
+ <para>
+ The <filename>cml1</filename> class provides basic support for the
+ Linux kernel style build configuration system.
+ </para>
+</section>
+
+<section id='ref-classes-compress_doc'>
+ <title><filename>compress_doc.bbclass</filename></title>
+
+ <para>
+ Enables compression for man pages and info pages.
+ This class is intended to be inherited globally.
+ The default compression mechanism is gz (gzip) but you can
+ select an alternative mechanism by setting the
+ <link linkend='var-DOC_COMPRESS'><filename>DOC_COMPRESS</filename></link>
+ variable.
+ </para>
+</section>
+
+<section id='ref-classes-copyleft_compliance'>
+ <title><filename>copyleft_compliance.bbclass</filename></title>
+
+ <para>
+ The <filename>copyleft_compliance</filename> class
+ preserves source code for the purposes of license compliance.
+ This class is an alternative to the <filename>archiver</filename>
+ class and is still used by some users even though it has been
+ deprecated in favor of the
+ <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
+ class.
+ </para>
+</section>
+
+<section id='ref-classes-copyleft_filter'>
+ <title><filename>copyleft_filter.bbclass</filename></title>
+
+ <para>
+ A class used by the
+ <link linkend='ref-classes-archiver'><filename>archiver</filename></link>
+ and
+ <link linkend='ref-classes-copyleft_compliance'><filename>copyleft_compliance</filename></link>
+ classes for filtering licenses.
+ The <filename>copyleft_filter</filename> class is an internal class
+ and is not intended to be used directly.
+ </para>
+</section>
+
+<section id='ref-classes-core-image'>
+ <title><filename>core-image.bbclass</filename></title>
+
+ <para>
+ The <filename>core-image</filename> class
+ provides common definitions for the
+ <filename>core-image-*</filename> image recipes, such as support for
+ additional
+ <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
+ </para>
+</section>
+
+<section id='ref-classes-cpan'>
+ <title><filename>cpan*.bbclass</filename></title>
+
+ <para>
+ The <filename>cpan*</filename> classes support Perl modules.
+ </para>
+
+ <para>
+ Recipes for Perl modules are simple.
+ These recipes usually only need to point to the source's archive and
+ then inherit the proper class file.
+ Building is split into two methods depending on which method the module
+ authors used.
+ <itemizedlist>
+ <listitem><para>Modules that use old
+ <filename>Makefile.PL</filename>-based build system require
+ <filename>cpan.bbclass</filename> in their recipes.
+ </para></listitem>
+ <listitem><para>Modules that use
+ <filename>Build.PL</filename>-based build system require
+ using <filename>cpan_build.bbclass</filename> in their recipes.
+ </para></listitem>
+ </itemizedlist>
+ Both build methods inherit the <filename>cpan-base</filename> class
+ for basic Perl support.
+ </para>
+</section>
+
+<section id='ref-classes-cross'>
+ <title><filename>cross.bbclass</filename></title>
+
+ <para>
+ The <filename>cross</filename> class provides support for the recipes
+ that build the cross-compilation tools.
+ </para>
+</section>
+
+<section id='ref-classes-cross-canadian'>
+ <title><filename>cross-canadian.bbclass</filename></title>
+
+ <para>
+ The <filename>cross-canadian</filename> class
+ provides support for the recipes that build the Canadian
+ Cross-compilation tools for SDKs.
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for more
+ discussion on these cross-compilation tools.
+ </para>
+</section>
+
+<section id='ref-classes-crosssdk'>
+ <title><filename>crosssdk.bbclass</filename></title>
+
+ <para>
+ The <filename>crosssdk</filename> class
+ provides support for the recipes that build the cross-compilation
+ tools used for building SDKs.
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for more
+ discussion on these cross-compilation tools.
+ </para>
+</section>
+
+<section id='ref-classes-debian'>
+ <title><filename>debian.bbclass</filename></title>
+
+ <para>
+ The <filename>debian</filename> class renames output packages so that
+ they follow the Debian naming policy (i.e. <filename>glibc</filename>
+ becomes <filename>libc6</filename> and <filename>glibc-devel</filename>
+ becomes <filename>libc6-dev</filename>.)
+ Renaming includes the library name and version as part of the package
+ name.
+ </para>
+
+ <para>
+ If a recipe creates packages for multiple libraries
+ (shared object files of <filename>.so</filename> type), use the
+ <link linkend='var-LEAD_SONAME'><filename>LEAD_SONAME</filename></link>
+ variable in the recipe to specify the library on which to apply the
+ naming scheme.
+ </para>
+</section>
+
+<section id='ref-classes-deploy'>
+ <title><filename>deploy.bbclass</filename></title>
+
+ <para>
+ The <filename>deploy</filename> class handles deploying files
+ to the
+ <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
+ directory.
+ The main function of this class is to allow the deploy step to be
+ accelerated by shared state.
+ Recipes that inherit this class should define their own
+ <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>
+ function to copy the files to be deployed to
+ <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link>,
+ and use <filename>addtask</filename> to add the task at the appropriate
+ place, which is usually after
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ or
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>.
+ The class then takes care of staging the files from
+ <filename>DEPLOYDIR</filename> to
+ <filename>DEPLOY_DIR_IMAGE</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-devshell'>
+ <title><filename>devshell.bbclass</filename></title>
+
+ <para>
+ The <filename>devshell</filename> class adds the
+ <filename>do_devshell</filename> task.
+ Distribution policy dictates whether to include this class.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
+ in the Yocto Project Development Tasks Manual for more information about
+ using <filename>devshell</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-devupstream'>
+ <title><filename>devupstream.bbclass</filename></title>
+
+ <para>
+ The <filename>devupstream</filename> class uses
+ <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link>
+ to add a variant of the recipe that fetches from an alternative URI
+ (e.g. Git) instead of a tarball.
+ Following is an example:
+ <literallayout class='monospaced'>
+ BBCLASSEXTEND = "devupstream:target"
+ SRC_URI_class-devupstream = "git://git.example.com/example"
+ SRCREV_class-devupstream = "abcd1234"
+ </literallayout>
+ Adding the above statements to your recipe creates a variant that has
+ <link linkend='var-DEFAULT_PREFERENCE'><filename>DEFAULT_PREFERENCE</filename></link>
+ set to "-1".
+ Consequently, you need to select the variant of the recipe to use it.
+ Any development-specific adjustments can be done by using the
+ <filename>class-devupstream</filename> override.
+ Here is an example:
+ <literallayout class='monospaced'>
+ DEPENDS_append_class-devupstream = " gperf-native"
+
+ do_configure_prepend_class-devupstream() {
+ touch ${S}/README
+ }
+ </literallayout>
+ The class currently only supports creating a development variant of
+ the target recipe, not <filename>native</filename> or
+ <filename>nativesdk</filename> variants.
+ </para>
+
+ <para>
+ The <filename>BBCLASSEXTEND</filename> syntax
+ (i.e. <filename>devupstream:target</filename>) provides support for
+ <filename>native</filename> and <filename>nativesdk</filename>
+ variants.
+ Consequently, this functionality can be added in a future release.
+ </para>
+
+ <para>
+ Support for other version control systems such as Subversion is
+ limited due to BitBake's automatic fetch dependencies (e.g.
+ <filename>subversion-native</filename>).
+ </para>
+</section>
+
+<section id='ref-classes-distro_features_check'>
+ <title><filename>distro_features_check.bbclass</filename></title>
+
+ <para>
+ The <filename>distro_features_check</filename> class
+ allows individual recipes to check for required and conflicting
+ <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+ </para>
+
+ <para>
+ This class provides support for the
+ <link linkend='var-REQUIRED_DISTRO_FEATURES'><filename>REQUIRED_DISTRO_FEATURES</filename></link>
+ and
+ <link linkend='var-CONFLICT_DISTRO_FEATURES'><filename>CONFLICT_DISTRO_FEATURES</filename></link>
+ variables.
+ If any conditions specified in the recipe using the above variables are
+ not met, the recipe will be skipped.
+ </para>
+</section>
+
+<section id='ref-classes-distutils'>
+ <title><filename>distutils*.bbclass</filename></title>
+
+ <para>
+ The <filename>distutils*</filename> classes support recipes for Python
+ version 2.x extensions, which are simple.
+ These recipes usually only need to point to the source's archive and
+ then inherit the proper class.
+ Building is split into two methods depending on which method the
+ module authors used.
+ <itemizedlist>
+ <listitem><para>Extensions that use an Autotools-based build system
+ require Autotools and the classes based on
+ <filename>distutils</filename> in their recipes.
+ </para></listitem>
+ <listitem><para>Extensions that use build systems based on
+ <filename>distutils</filename> require
+ the <filename>distutils</filename> class in their recipes.
+ </para></listitem>
+ <listitem><para>Extensions that use build systems based on
+ <filename>setuptools</filename> require the
+ <link linkend='ref-classes-setuptools'><filename>setuptools</filename></link>
+ class in their recipes.
+ </para></listitem>
+ </itemizedlist>
+ The <filename>distutils-common-base</filename> class is required by
+ some of the <filename>distutils*</filename> classes to provide common
+ Python2 support.
+ </para>
+</section>
+
+<section id='ref-classes-distutils3'>
+ <title><filename>distutils3*.bbclass</filename></title>
+
+ <para>
+ The <filename>distutils3*</filename> classes support recipes for Python
+ version 3.x extensions, which are simple.
+ These recipes usually only need to point to the source's archive and
+ then inherit the proper class.
+ Building is split into three methods depending on which method the
+ module authors used.
+ <itemizedlist>
+ <listitem><para>Extensions that use an Autotools-based build system
+ require Autotools and
+ <filename>distutils</filename>-based classes in their recipes.
+ </para></listitem>
+ <listitem><para>Extensions that use
+ <filename>distutils</filename>-based build systems require
+ the <filename>distutils</filename> class in their recipes.
+ </para></listitem>
+ <listitem><para>Extensions that use build systems based on
+ <filename>setuptools3</filename> require the
+ <link linkend='ref-classes-setuptools'><filename>setuptools3</filename></link>
+ class in their recipes.
+ </para></listitem>
+ </itemizedlist>
+ The <filename>distutils3*</filename> classes either inherit their
+ corresponding <filename>distutils*</filename> class or replicate them
+ using a Python3 version instead (e.g.
+ <filename>distutils3-base</filename> inherits
+ <filename>distutils-common-base</filename>, which is the same as
+ <filename>distutils-base</filename> but inherits
+ <filename>python3native</filename> instead of
+ <filename>pythonnative</filename>).
+ </para>
+</section>
+
+<section id='ref-classes-externalsrc'>
+ <title><filename>externalsrc.bbclass</filename></title>
+
+ <para>
+ The <filename>externalsrc</filename> class supports building software
+ from source code that is external to the OpenEmbedded build system.
+ Building software from an external source tree means that the build
+ system's normal fetch, unpack, and patch process is not used.
+ </para>
+
+ <para>
+ By default, the OpenEmbedded build system uses the
+ <link linkend='var-S'><filename>S</filename></link> and
+ <link linkend='var-B'><filename>B</filename></link> variables to
+ locate unpacked recipe source code and to build it, respectively.
+ When your recipe inherits the <filename>externalsrc</filename> class,
+ you use the
+ <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
+ and
+ <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
+ variables to ultimately define <filename>S</filename> and
+ <filename>B</filename>.
+ </para>
+
+ <para>
+ By default, this class expects the source code to support recipe builds
+ that use the <link linkend='var-B'><filename>B</filename></link>
+ variable to point to the directory in which the OpenEmbedded build
+ system places the generated objects built from the recipes.
+ By default, the <filename>B</filename> directory is set to the
+ following, which is separate from the source directory
+ (<filename>S</filename>):
+ <literallayout class='monospaced'>
+ ${WORKDIR}/${BPN}/{PV}/
+ </literallayout>
+ See these variables for more information:
+ <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
+ <link linkend='var-BPN'><filename>BPN</filename></link>, and
+ <link linkend='var-PV'><filename>PV</filename></link>,
+ </para>
+
+ <para>
+ For more information on the
+ <filename>externalsrc</filename> class, see the comments in
+ <filename>meta/classes/externalsrc.bbclass</filename> in the
+ <link linkend='source-directory'>Source Directory</link>.
+ For information on how to use the <filename>externalsrc</filename>
+ class, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='ref-classes-extrausers'>
+ <title><filename>extrausers.bbclass</filename></title>
+
+ <para>
+ The <filename>extrausers</filename> class allows
+ additional user and group configuration to be applied at the image
+ level.
+ Inheriting this class either globally or from an image recipe allows
+ additional user and group operations to be performed using the
+ <link linkend='var-EXTRA_USERS_PARAMS'><filename>EXTRA_USERS_PARAMS</filename></link>
+ variable.
+ <note>
+ The user and group operations added using the
+ <filename>extrausers</filename> class are not tied to a specific
+ recipe outside of the recipe for the image.
+ Thus, the operations can be performed across the image as a whole.
+ Use the
+ <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
+ class to add user and group configuration to a specific recipe.
+ </note>
+ Here is an example that uses this class in an image recipe:
+ <literallayout class='monospaced'>
+ inherit extrausers
+ EXTRA_USERS_PARAMS = "\
+ useradd -p '' tester; \
+ groupadd developers; \
+ userdel nobody; \
+ groupdel -g video; \
+ groupmod -g 1020 developers; \
+ usermod -s /bin/sh tester; \
+ "
+ </literallayout>
+ Here is an example that adds two users named "tester-jim" and
+ "tester-sue" and assigns passwords:
+ <literallayout class='monospaced'>
+ inherit extrausers
+ EXTRA_USERS_PARAMS = "\
+ useradd -P tester01 tester-jim; \
+ useradd -P tester01 tester-sue; \
+ "
+ </literallayout>
+ Finally, here is an example that sets the root password to
+ "1876*18":
+ <literallayout class='monospaced'>
+ inherit extrausers
+ EXTRA_USERS_PARAMS = "\
+ usermod -P 1876*18 root; \
+ "
+ </literallayout>
+ </para>
+</section>
+
+<section id='ref-classes-fontcache'>
+ <title><filename>fontcache.bbclass</filename></title>
+
+ <para>
+ The <filename>fontcache</filename> class generates the
+ proper post-install and post-remove (postinst and postrm)
+ scriptlets for font packages.
+ These scriptlets call <filename>fc-cache</filename> (part of
+ <filename>Fontconfig</filename>) to add the fonts to the font
+ information cache.
+ Since the cache files are architecture-specific,
+ <filename>fc-cache</filename> runs using QEMU if the postinst
+ scriptlets need to be run on the build host during image creation.
+ </para>
+
+ <para>
+ If the fonts being installed are in packages other than the main
+ package, set
+ <link linkend='var-FONT_PACKAGES'><filename>FONT_PACKAGES</filename></link>
+ to specify the packages containing the fonts.
+ </para>
+</section>
+
+<section id='ref-classes-fs-uuid'>
+ <title><filename>fs-uuid.bbclass</filename></title>
+
+ <para>
+ The <filename>fs-uuid</filename> class extracts UUID from
+ <filename>${</filename><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link><filename>}</filename>,
+ which must have been built by the time that this function gets called.
+ The <filename>fs-uuid</filename> class only works on
+ <filename>ext</filename> file systems and depends on
+ <filename>tune2fs</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-gconf'>
+ <title><filename>gconf.bbclass</filename></title>
+
+ <para>
+ The <filename>gconf</filename> class provides common
+ functionality for recipes that need to install GConf schemas.
+ The schemas will be put into a separate package
+ (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-gconf</filename>)
+ that is created automatically when this class is inherited.
+ This package uses the appropriate post-install and post-remove
+ (postinst/postrm) scriptlets to register and unregister the schemas
+ in the target image.
+ </para>
+</section>
+
+<section id='ref-classes-gettext'>
+ <title><filename>gettext.bbclass</filename></title>
+
+ <para>
+ The <filename>gettext</filename> class provides support for
+ building software that uses the GNU <filename>gettext</filename>
+ internationalization and localization system.
+ All recipes building software that use
+ <filename>gettext</filename> should inherit this class.
+ </para>
+</section>
+
+<section id='ref-classes-gnomebase'>
+ <title><filename>gnomebase.bbclass</filename></title>
+
+ <para>
+ The <filename>gnomebase</filename> class is the base
+ class for recipes that build software from the GNOME stack.
+ This class sets
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> to
+ download the source from the GNOME mirrors as well as extending
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ with the typical GNOME installation paths.
+ </para>
+</section>
+
+<section id='ref-classes-gobject-introspection'>
+ <title><filename>gobject-introspection.bbclass</filename></title>
+
+ <para>
+ Provides support for recipes building software that
+ supports GObject introspection.
+ This functionality is only enabled if the
+ "gobject-introspection-data" feature is in
+ <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
+ as well as "qemu-usermode" being in
+ <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
+ <note>
+ This functionality is backfilled by default and,
+ if not applicable, should be disabled through
+ <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
+ or
+ <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>,
+ respectively.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-grub-efi'>
+ <title><filename>grub-efi.bbclass</filename></title>
+
+ <para>
+ The <filename>grub-efi</filename>
+ class provides <filename>grub-efi</filename>-specific functions for
+ building bootable images.
+ </para>
+
+ <para>
+ This class supports several variables:
+ <itemizedlist>
+ <listitem><para>
+ <link linkend='var-INITRD'><filename>INITRD</filename></link>:
+ Indicates list of filesystem images to concatenate and use
+ as an initial RAM disk (initrd) (optional).
+ </para></listitem>
+ <listitem><para>
+ <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
+ Indicates a filesystem image to include as the root filesystem
+ (optional).</para></listitem>
+ <listitem><para>
+ <link linkend='var-GRUB_GFXSERIAL'><filename>GRUB_GFXSERIAL</filename></link>:
+ Set this to "1" to have graphics and serial in the boot menu.
+ </para></listitem>
+ <listitem><para>
+ <link linkend='var-LABELS'><filename>LABELS</filename></link>:
+ A list of targets for the automatic configuration.
+ </para></listitem>
+ <listitem><para>
+ <link linkend='var-APPEND'><filename>APPEND</filename></link>:
+ An override list of append strings for each
+ <filename>LABEL</filename>.
+ </para></listitem>
+ <listitem><para>
+ <link linkend='var-GRUB_OPTS'><filename>GRUB_OPTS</filename></link>:
+ Additional options to add to the configuration (optional).
+ Options are delimited using semi-colon characters
+ (<filename>;</filename>).</para></listitem>
+ <listitem><para>
+ <link linkend='var-GRUB_TIMEOUT'><filename>GRUB_TIMEOUT</filename></link>:
+ Timeout before executing the default <filename>LABEL</filename>
+ (optional).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='ref-classes-gsettings'>
+ <title><filename>gsettings.bbclass</filename></title>
+
+ <para>
+ The <filename>gsettings</filename> class
+ provides common functionality for recipes that need to install
+ GSettings (glib) schemas.
+ The schemas are assumed to be part of the main package.
+ Appropriate post-install and post-remove (postinst/postrm)
+ scriptlets are added to register and unregister the schemas in the
+ target image.
+ </para>
+</section>
+
+<section id='ref-classes-gtk-doc'>
+ <title><filename>gtk-doc.bbclass</filename></title>
+
+ <para>
+ The <filename>gtk-doc</filename> class
+ is a helper class to pull in the appropriate
+ <filename>gtk-doc</filename> dependencies and disable
+ <filename>gtk-doc</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-gtk-icon-cache'>
+ <title><filename>gtk-icon-cache.bbclass</filename></title>
+
+ <para>
+ The <filename>gtk-icon-cache</filename> class
+ generates the proper post-install and post-remove (postinst/postrm)
+ scriptlets for packages that use GTK+ and install icons.
+ These scriptlets call <filename>gtk-update-icon-cache</filename> to add
+ the fonts to GTK+'s icon cache.
+ Since the cache files are architecture-specific,
+ <filename>gtk-update-icon-cache</filename> is run using QEMU if the
+ postinst scriptlets need to be run on the build host during image
+ creation.
+ </para>
+</section>
+
+<section id='ref-classes-gtk-immodules-cache'>
+ <title><filename>gtk-immodules-cache.bbclass</filename></title>
+
+ <para>
+ The <filename>gtk-immodules-cache</filename> class
+ generates the proper post-install and post-remove (postinst/postrm)
+ scriptlets for packages that install GTK+ input method modules for
+ virtual keyboards.
+ These scriptlets call <filename>gtk-update-icon-cache</filename> to add
+ the input method modules to the cache.
+ Since the cache files are architecture-specific,
+ <filename>gtk-update-icon-cache</filename> is run using QEMU if the
+ postinst scriptlets need to be run on the build host during image
+ creation.
+ </para>
+
+ <para>
+ If the input method modules being installed are in packages other than
+ the main package, set
+ <link linkend='var-GTKIMMODULES_PACKAGES'><filename>GTKIMMODULES_PACKAGES</filename></link>
+ to specify the packages containing the modules.
+ </para>
+</section>
+
+<section id='ref-classes-gzipnative'>
+ <title><filename>gzipnative.bbclass</filename></title>
+
+ <para>
+ The <filename>gzipnative</filename> class enables the use of
+ different native versions of <filename>gzip</filename>
+ and <filename>pigz</filename> rather than the versions of these tools
+ from the build host.
+ </para>
+</section>
+
+<section id='ref-classes-icecc'>
+ <title><filename>icecc.bbclass</filename></title>
+
+ <para>
+ The <filename>icecc</filename> class supports
+ <ulink url='https://github.com/icecc/icecream'>Icecream</ulink>, which
+ facilitates taking compile jobs and distributing them among remote
+ machines.
+ </para>
+
+ <para>
+ The class stages directories with symlinks from <filename>gcc</filename>
+ and <filename>g++</filename> to <filename>icecc</filename>, for both
+ native and cross compilers.
+ Depending on each configure or compile, the OpenEmbedded build system
+ adds the directories at the head of the <filename>PATH</filename> list
+ and then sets the <filename>ICECC_CXX</filename> and
+ <filename>ICEC_CC</filename> variables, which are the paths to the
+ <filename>g++</filename> and <filename>gcc</filename> compilers,
+ respectively.
+ </para>
+
+ <para>
+ For the cross compiler, the class creates a <filename>tar.gz</filename>
+ file that contains the Yocto Project toolchain and sets
+ <filename>ICECC_VERSION</filename>, which is the version of the
+ cross-compiler used in the cross-development toolchain, accordingly.
+ </para>
+
+ <para>
+ The class handles all three different compile stages
+ (i.e native ,cross-kernel and target) and creates the necessary
+ environment <filename>tar.gz</filename> file to be used by the remote
+ machines.
+ The class also supports SDK generation.
+ </para>
+
+ <para>
+ If <link linkend='var-ICECC_PATH'><filename>ICECC_PATH</filename></link>
+ is not set in your <filename>local.conf</filename> file, then the
+ class tries to locate the <filename>icecc</filename> binary
+ using <filename>which</filename>.
+
+ If
+ <link linkend='var-ICECC_ENV_EXEC'><filename>ICECC_ENV_EXEC</filename></link>
+ is set in your <filename>local.conf</filename> file, the variable should
+ point to the <filename>icecc-create-env</filename> script
+ provided by the user.
+ If you do not point to a user-provided script, the build system
+ uses the default script provided by the recipe
+ <filename>icecc-create-env-native.bb</filename>.
+ <note>
+ This script is a modified version and not the one that comes with
+ <filename>icecc</filename>.
+ </note>
+ </para>
+
+ <para>
+ If you do not want the Icecream distributed compile support to apply
+ to specific recipes or classes, you can effectively "blacklist" them
+ by listing the recipes and classes using the
+ <link linkend='var-ICECC_USER_PACKAGE_BL'><filename>ICECC_USER_PACKAGE_BL</filename></link>
+ and
+ <link linkend='var-ICECC_USER_CLASS_BL'><filename>ICECC_USER_CLASS_BL</filename></link>,
+ variables, respectively, in your <filename>local.conf</filename> file.
+ Doing so causes the OpenEmbedded build system to handle these
+ compilations locally.
+ </para>
+
+ <para>
+ Additionally, you can list recipes using the
+ <link linkend='var-ICECC_USER_PACKAGE_WL'><filename>ICECC_USER_PACKAGE_WL</filename></link>
+ variable in your <filename>local.conf</filename> file to force
+ <filename>icecc</filename> to be enabled for recipes using an empty
+ <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
+ variable.
+ </para>
+
+ <para>
+ Inheriting the <filename>icecc</filename> class changes all sstate
+ signatures.
+ Consequently, if a development team has a dedicated build system
+ that populates
+ <link linkend='var-SSTATE_MIRRORS'><filename>STATE_MIRRORS</filename></link>
+ and they want to reuse sstate from
+ <filename>STATE_MIRRORS</filename>, then all developers and the
+ build system need to either inherit the <filename>icecc</filename>
+ class or nobody should.
+ </para>
+
+ <para>
+ At the distribution level, you can inherit the
+ <filename>icecc</filename> class to be sure that all builders start
+ with the same sstate signatures.
+ After inheriting the class, you can then disable the feature by setting
+ the
+ <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link>
+ variable to "1" as follows:
+ <literallayout class='monospaced'>
+ INHERIT_DISTRO_append = " icecc"
+ ICECC_DISABLED ??= "1"
+ </literallayout>
+ This practice makes sure everyone is using the same signatures but also
+ requires individuals that do want to use Icecream to enable the feature
+ individually as follows in your <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ ICECC_DISABLED = ""
+ </literallayout>
+ </para>
+</section>
+
+<section id='ref-classes-image'>
+ <title><filename>image.bbclass</filename></title>
+
+ <para>
+ The <filename>image</filename> class helps support creating images
+ in different formats.
+ First, the root filesystem is created from packages using
+ one of the <filename>rootfs*.bbclass</filename>
+ files (depending on the package format used) and then one or more image
+ files are created.
+ <itemizedlist>
+ <listitem><para>The
+ <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
+ variable controls the types of images to generate.
+ </para></listitem>
+ <listitem><para>The
+ <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
+ variable controls the list of packages to install into the
+ image.</para></listitem>
+ </itemizedlist>
+ For information on customizing images, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage'>Customizing Images</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ For information on how images are created, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
+ section in the Yocto Project Overview and Concpets Manual.
+ </para>
+</section>
+
+<section id='ref-classes-image-buildinfo'>
+ <title><filename>image-buildinfo.bbclass</filename></title>
+
+ <para>
+ The <filename>image-buildinfo</filename> class writes information
+ to the target filesystem on <filename>/etc/build</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-image_types'>
+ <title><filename>image_types.bbclass</filename></title>
+
+ <para>
+ The <filename>image_types</filename> class defines all of the
+ standard image output types that you can enable through the
+ <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
+ variable.
+ You can use this class as a reference on how to add support for
+ custom image output types.
+ </para>
+
+ <para>
+ By default, the
+ <link linkend='ref-classes-image'><filename>image</filename></link>
+ class automatically enables the <filename>image_types</filename> class.
+ The <filename>image</filename> class uses the
+ <filename>IMGCLASSES</filename> variable as follows:
+ <literallayout class='monospaced'>
+ IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
+ IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
+ IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
+ IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
+ IMGCLASSES += "image_types_wic"
+ IMGCLASSES += "rootfs-postcommands"
+ IMGCLASSES += "image-postinst-intercepts"
+ inherit ${IMGCLASSES}
+ </literallayout>
+ </para>
+
+ <para>
+ The <filename>image_types</filename> class also handles conversion and
+ compression of images.
+ <note>
+ To build a VMware VMDK image, you need to add "wic.vmdk" to
+ <filename>IMAGE_FSTYPES</filename>.
+ This would also be similar for Virtual Box Virtual Disk Image
+ ("vdi") and QEMU Copy On Write Version 2 ("qcow2") images.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-image-live'>
+ <title><filename>image-live.bbclass</filename></title>
+
+ <para>
+ This class controls building "live" (i.e. HDDIMG and ISO) images.
+ Live images contain syslinux for legacy booting, as well as the
+ bootloader specified by
+ <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
+ if
+ <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
+ contains "efi".
+ </para>
+
+ <para>
+ Normally, you do not use this class directly.
+ Instead, you add "live" to
+ <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
+ </para>
+</section>
+
+<section id='ref-classes-image-mklibs'>
+ <title><filename>image-mklibs.bbclass</filename></title>
+
+ <para>
+ The <filename>image-mklibs</filename> class
+ enables the use of the <filename>mklibs</filename> utility during the
+ <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
+ task, which optimizes the size of
+ libraries contained in the image.
+ </para>
+
+ <para>
+ By default, the class is enabled in the
+ <filename>local.conf.template</filename> using the
+ <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
+ variable as follows:
+ <literallayout class='monospaced'>
+ USER_CLASSES ?= "buildstats image-mklibs image-prelink"
+ </literallayout>
+ </para>
+</section>
+
+<section id='ref-classes-image-prelink'>
+ <title><filename>image-prelink.bbclass</filename></title>
+
+ <para>
+ The <filename>image-prelink</filename> class
+ enables the use of the <filename>prelink</filename> utility during
+ the
+ <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
+ task, which optimizes the dynamic
+ linking of shared libraries to reduce executable startup time.
+ </para>
+
+ <para>
+ By default, the class is enabled in the
+ <filename>local.conf.template</filename> using the
+ <link linkend='var-USER_CLASSES'><filename>USER_CLASSES</filename></link>
+ variable as follows:
+ <literallayout class='monospaced'>
+ USER_CLASSES ?= "buildstats image-mklibs image-prelink"
+ </literallayout>
+ </para>
+</section>
+
+<section id='ref-classes-insane'>
+ <title><filename>insane.bbclass</filename></title>
+
+ <para>
+ The <filename>insane</filename> class adds a step to the package
+ generation process so that output quality assurance checks are
+ generated by the OpenEmbedded build system.
+ A range of checks are performed that check the build's output
+ for common problems that show up during runtime.
+ Distribution policy usually dictates whether to include this class.
+ </para>
+
+ <para>
+ You can configure the sanity checks so that specific test failures
+ either raise a warning or an error message.
+ Typically, failures for new tests generate a warning.
+ Subsequent failures for the same test would then generate an error
+ message once the metadata is in a known and good condition.
+ See the
+ "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>"
+ Chapter for a list of all the warning and error messages
+ you might encounter using a default configuration.
+ </para>
+
+ <para>
+ Use the
+ <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
+ <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
+ variables to control the behavior of
+ these checks at the global level (i.e. in your custom distro
+ configuration).
+ However, to skip one or more checks in recipes, you should use
+ <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
+ For example, to skip the check for symbolic link
+ <filename>.so</filename> files in the main package of a recipe,
+ add the following to the recipe.
+ You need to realize that the package name override, in this example
+ <filename>${PN}</filename>, must be used:
+ <literallayout class='monospaced'>
+ INSANE_SKIP_${PN} += "dev-so"
+ </literallayout>
+ Please keep in mind that the QA checks exist in order to detect real
+ or potential problems in the packaged output.
+ So exercise caution when disabling these checks.
+ </para>
+
+ <para>
+ The following list shows the tests you can list with the
+ <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
+ variables:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
+ Checks that produced binaries have not already been
+ stripped prior to the build system extracting debug symbols.
+ It is common for upstream software projects to default to
+ stripping debug symbols for output binaries.
+ In order for debugging to work on the target using
+ <filename>-dbg</filename> packages, this stripping must be
+ disabled.
+ </para></listitem>
+ <listitem><para><emphasis><filename>arch:</filename></emphasis>
+ Checks the Executable and Linkable Format (ELF) type, bit size,
+ and endianness of any binaries to ensure they match the target
+ architecture.
+ This test fails if any binaries do not match the type since
+ there would be an incompatibility.
+ The test could indicate that the
+ wrong compiler or compiler options have been used.
+ Sometimes software, like bootloaders, might need to bypass
+ this check.
+ </para></listitem>
+ <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
+ Checks for paths to locations on the build host inside the
+ output files.
+ Currently, this test triggers too many false positives and
+ thus is not normally enabled.
+ </para></listitem>
+ <listitem><para><emphasis><filename>build-deps:</filename></emphasis>
+ Determines if a build-time dependency that is specified through
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>,
+ explicit
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
+ or task-level dependencies exists to match any runtime
+ dependency.
+ This determination is particularly useful to discover where
+ runtime dependencies are detected and added during packaging.
+ If no explicit dependency has been specified within the
+ metadata, at the packaging stage it is too late to ensure that
+ the dependency is built, and thus you can end up with an
+ error when the package is installed into the image during the
+ <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
+ task because the auto-detected dependency was not satisfied.
+ An example of this would be where the
+ <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link>
+ class automatically adds a dependency on the
+ <filename>initscripts-functions</filename> package to packages
+ that install an initscript that refers to
+ <filename>/etc/init.d/functions</filename>.
+ The recipe should really have an explicit
+ <filename>RDEPENDS</filename> for the package in question on
+ <filename>initscripts-functions</filename> so that the
+ OpenEmbedded build system is able to ensure that the
+ <filename>initscripts</filename> recipe is actually built and
+ thus the <filename>initscripts-functions</filename> package is
+ made available.
+ </para></listitem>
+ <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
+ Checks the
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ log for indications
+ that paths to locations on the build host were used.
+ Using such paths might result in host contamination of the
+ build output.
+ </para></listitem>
+ <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
+ Checks that all packages except <filename>-dbg</filename>
+ packages do not depend on <filename>-dbg</filename>
+ packages, which would cause a packaging bug.
+ </para></listitem>
+ <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
+ Checks for <filename>.debug</filename> directories in anything but the
+ <filename>-dbg</filename> package.
+ The debug files should all be in the <filename>-dbg</filename> package.
+ Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
+ <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
+ Checks for invalid version comparison statements in runtime
+ dependency relationships between packages (i.e. in
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
+ <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
+ <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
+ <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
+ <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
+ and
+ <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
+ variable values).
+ Any invalid comparisons might trigger failures or undesirable
+ behavior when passed to the package manager.
+ </para></listitem>
+ <listitem><para><emphasis><filename>desktop:</filename></emphasis>
+ Runs the <filename>desktop-file-validate</filename> program
+ against any <filename>.desktop</filename> files to validate
+ their contents against the specification for
+ <filename>.desktop</filename> files.</para></listitem>
+ <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
+ Checks that all packages except <filename>-dev</filename>
+ or <filename>-staticdev</filename> packages do not depend on
+ <filename>-dev</filename> packages, which would be a
+ packaging bug.</para></listitem>
+ <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
+ Checks that the <filename>.so</filename> symbolic links are in the
+ <filename>-dev</filename> package and not in any of the other packages.
+ In general, these symlinks are only useful for development purposes.
+ Thus, the <filename>-dev</filename> package is the correct location for
+ them.
+ Some very rare cases do exist for dynamically loaded modules where
+ these symlinks are needed instead in the main package.
+ </para></listitem>
+ <listitem><para><emphasis><filename>file-rdeps:</filename></emphasis>
+ Checks that file-level dependencies identified by the
+ OpenEmbedded build system at packaging time are satisfied.
+ For example, a shell script might start with the line
+ <filename>#!/bin/bash</filename>.
+ This line would translate to a file dependency on
+ <filename>/bin/bash</filename>.
+ Of the three package managers that the OpenEmbedded build
+ system supports, only RPM directly handles file-level
+ dependencies, resolving them automatically to packages
+ providing the files.
+ However, the lack of that functionality in the other two
+ package managers does not mean the dependencies do not still
+ need resolving.
+ This QA check attempts to ensure that explicitly declared
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+ exist to handle any file-level dependency detected in
+ packaged files.
+ </para></listitem>
+ <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
+ Checks for
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ variable values that contain "//", which is invalid.
+ </para></listitem>
+ <listitem><para id='insane-host-user-contaminated'>
+ <emphasis><filename>host-user-contaminated:</filename></emphasis>
+ Checks that no package produced by the recipe contains any
+ files outside of <filename>/home</filename> with a user or
+ group ID that matches the user running BitBake.
+ A match usually indicates that the files are being installed
+ with an incorrect UID/GID, since target IDs are independent
+ from host IDs.
+ For additional information, see the section describing the
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ task.
+ </para></listitem>
+ <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
+ Report when packages are excluded from being created due to
+ being marked with a license that is in
+ <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
+ </para></listitem>
+ <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
+ Checks the
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ log for indications
+ that paths to locations on the build host were used.
+ Using such paths might result in host contamination of the
+ build output.
+ </para></listitem>
+ <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
+ Reports when files have been installed within
+ <filename>do_install</filename> but have not been included in
+ any package by way of the
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ variable.
+ Files that do not appear in any package cannot be present in
+ an image later on in the build process.
+ Ideally, all installed files should be packaged or not
+ installed at all.
+ These files can be deleted at the end of
+ <filename>do_install</filename> if the files are not
+ needed in any package.
+ </para></listitem>
+ <listitem><para><emphasis><filename>invalid-chars:</filename></emphasis>
+ Checks that the recipe metadata variables
+ <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>,
+ <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>,
+ <link linkend='var-LICENSE'><filename>LICENSE</filename></link>,
+ and
+ <link linkend='var-SECTION'><filename>SECTION</filename></link>
+ do not contain non-UTF-8 characters.
+ Some package managers do not support such characters.
+ </para></listitem>
+ <listitem><para><emphasis><filename>invalid-packageconfig:</filename></emphasis>
+ Checks that no undefined features are being added to
+ <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>.
+ For example, any name "foo" for which the following form
+ does not exist:
+ <literallayout class='monospaced'>
+ PACKAGECONFIG[foo] = "..."
+ </literallayout>
+ </para></listitem>
+ <listitem><para><emphasis><filename>la:</filename></emphasis>
+ Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
+ paths.
+ Any <filename>.la</filename> file containing these paths is incorrect since
+ <filename>libtool</filename> adds the correct sysroot prefix when using the
+ files automatically itself.</para></listitem>
+ <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
+ Ensures that the binaries were linked with the
+ <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
+ options provided by the build system.
+ If this test fails, check that the <filename>LDFLAGS</filename> variable
+ is being passed to the linker command.</para></listitem>
+ <listitem><para><emphasis><filename>libdir:</filename></emphasis>
+ Checks for libraries being installed into incorrect
+ (possibly hardcoded) installation paths.
+ For example, this test will catch recipes that install
+ <filename>/lib/bar.so</filename> when
+ <filename>${base_libdir}</filename> is "lib32".
+ Another example is when recipes install
+ <filename>/usr/lib64/foo.so</filename> when
+ <filename>${libdir}</filename> is "/usr/lib".
+ </para></listitem>
+ <listitem><para><emphasis><filename>libexec:</filename></emphasis>
+ Checks if a package contains files in
+ <filename>/usr/libexec</filename>.
+ This check is not performed if the
+ <filename>libexecdir</filename> variable has been set
+ explicitly to <filename>/usr/libexec</filename>.
+ </para></listitem>
+ <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
+ Checks for the same package being listed multiple times through
+ the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
+ variable value.
+ Installing the package in this manner can cause errors during
+ packaging.
+ </para></listitem>
+ <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
+ Reports lines in <filename>fs-perms.txt</filename> that have
+ an invalid format.
+ </para></listitem>
+ <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
+ Reports lines in <filename>fs-perms.txt</filename> that have
+ an invalid format.
+ </para></listitem>
+ <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
+ Reports lines in <filename>fs-perms.txt</filename> that
+ specify 'link' where the specified target already exists.
+ </para></listitem>
+ <listitem><para><emphasis><filename>perms:</filename></emphasis>
+ Currently, this check is unused but reserved.
+ </para></listitem>
+ <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
+ Checks <filename>.pc</filename> files for any
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+ paths.
+ Any <filename>.pc</filename> file containing these paths is incorrect
+ since <filename>pkg-config</filename> itself adds the correct sysroot prefix
+ when the files are accessed.</para></listitem>
+ <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
+ Checks that all packages in
+ <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
+ have names that do not contain invalid characters (i.e.
+ characters other than 0-9, a-z, ., +, and -).
+ </para></listitem>
+ <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
+ Checks to see if the <filename>PKGV</filename> variable
+ is undefined during
+ <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
+ </para></listitem>
+ <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
+ Checks through the variables
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
+ <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
+ <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
+ <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
+ <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
+ <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
+ <link linkend='var-FILES'><filename>FILES</filename></link>,
+ <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
+ <filename>pkg_preinst</filename>,
+ <filename>pkg_postinst</filename>,
+ <filename>pkg_prerm</filename>
+ and <filename>pkg_postrm</filename>, and reports if there are
+ variable sets that are not package-specific.
+ Using these variables without a package suffix is bad practice,
+ and might unnecessarily complicate dependencies of other packages
+ within the same recipe or have other unintended consequences.
+ </para></listitem>
+ <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
+ Checks that a recipe does not have a name
+ (<link linkend='var-PN'><filename>PN</filename></link>) value
+ that appears in
+ <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
+ If a recipe is named such that its <filename>PN</filename>
+ value matches something already in
+ <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
+ happens to be the same as
+ <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
+ or
+ <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
+ it can have unexpected consequences.
+ For example, assignments such as
+ <filename>FILES_${PN} = "xyz"</filename> effectively turn into
+ <filename>FILES = "xyz"</filename>.
+ </para></listitem>
+ <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
+ Checks for rpaths in the binaries that contain build system paths such
+ as <filename>TMPDIR</filename>.
+ If this test fails, bad <filename>-rpath</filename> options are being
+ passed to the linker commands and your binaries have potential security
+ issues.</para></listitem>
+ <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
+ Reports that splitting or stripping debug symbols from binaries
+ has failed.
+ </para></listitem>
+ <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
+ Checks for static library files (<filename>*.a</filename>) in
+ non-<filename>staticdev</filename> packages.
+ </para></listitem>
+ <listitem><para><emphasis><filename>symlink-to-sysroot:</filename></emphasis>
+ Checks for symlinks in packages that point into
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+ on the host.
+ Such symlinks will work on the host, but are clearly invalid
+ when running on the target.
+ </para></listitem>
+ <listitem><para><emphasis><filename>textrel:</filename></emphasis>
+ Checks for ELF binaries that contain relocations in their
+ <filename>.text</filename> sections, which can result in a
+ performance impact at runtime.
+ See the explanation for the
+ <link linkend='qa-issue-textrel'><filename>ELF binary</filename></link>
+ message for more information regarding runtime performance issues.
+ </para></listitem>
+<!--
+This check was removed for YP 2.3 release
+
+ <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
+ Reports when a binary installed in
+ <filename>${base_libdir}</filename>,
+ <filename>${base_bindir}</filename>, or
+ <filename>${base_sbindir}</filename>, depends on another
+ binary installed under <filename>${exec_prefix}</filename>.
+ This dependency is a concern if you want the system to remain
+ basically operable if <filename>/usr</filename> is mounted
+ separately and is not mounted.
+ <note>
+ Defaults for binaries installed in
+ <filename>${base_libdir}</filename>,
+ <filename>${base_bindir}</filename>, and
+ <filename>${base_sbindir}</filename> are
+ <filename>/lib</filename>, <filename>/bin</filename>, and
+ <filename>/sbin</filename>, respectively.
+ The default for a binary installed
+ under <filename>${exec_prefix}</filename> is
+ <filename>/usr</filename>.
+ </note>
+ </para></listitem>
+-->
+ <listitem><para><emphasis><filename>unlisted-pkg-lics:</filename></emphasis>
+ Checks that all declared licenses applying for a package are also
+ declared on the recipe level (i.e. any license in
+ <filename>LICENSE_*</filename> should appear in
+ <link linkend='var-LICENSE'><filename>LICENSE</filename></link>).
+ </para></listitem>
+ <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
+ Checks for dynamic library load paths (rpaths) in the binaries that
+ by default on a standard system are searched by the linker (e.g.
+ <filename>/lib</filename> and <filename>/usr/lib</filename>).
+ While these paths will not cause any breakage, they do waste space and
+ are unnecessary.</para></listitem>
+ <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
+ Reports when variables fundamental to packaging (i.e.
+ <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
+ <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
+ <link linkend='var-D'><filename>D</filename></link>,
+ <link linkend='var-PN'><filename>PN</filename></link>, and
+ <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
+ undefined during
+ <link linkend='ref-tasks-package'><filename>do_package</filename></link>.
+ </para></listitem>
+ <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
+ If Build History is enabled, reports when a package
+ being written out has a lower version than the previously
+ written package under the same name.
+ If you are placing output packages into a feed and
+ upgrading packages on a target system using that feed, the
+ version of a package going backwards can result in the target
+ system not correctly upgrading to the "new" version of the
+ package.
+ <note>
+ If you are not using runtime package management on your
+ target system, then you do not need to worry about
+ this situation.
+ </note>
+ </para></listitem>
+ <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
+ Checks that all packages containing Xorg drivers have ABI
+ dependencies.
+ The <filename>xserver-xorg</filename> recipe provides driver
+ ABI names.
+ All drivers should depend on the ABI versions that they have
+ been built against.
+ Driver recipes that include
+ <filename>xorg-driver-input.inc</filename>
+ or <filename>xorg-driver-video.inc</filename> will
+ automatically get these versions.
+ Consequently, you should only need to explicitly add
+ dependencies to binary driver recipes.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='ref-classes-insserv'>
+ <title><filename>insserv.bbclass</filename></title>
+
+ <para>
+ The <filename>insserv</filename> class
+ uses the <filename>insserv</filename> utility to update the order of
+ symbolic links in <filename>/etc/rc?.d/</filename> within an image
+ based on dependencies specified by LSB headers in the
+ <filename>init.d</filename> scripts themselves.
+ </para>
+</section>
+
+<section id='ref-classes-kernel'>
+ <title><filename>kernel.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel</filename> class handles building Linux kernels.
+ The class contains code to build all kernel trees.
+ All needed headers are staged into the
+ <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
+ directory to allow out-of-tree module builds using
+ the
+ <link linkend='ref-classes-module'><filename>module</filename></link>
+ class.
+ </para>
+
+ <para>
+ This means that each built kernel module is packaged separately and
+ inter-module dependencies are created by parsing the
+ <filename>modinfo</filename> output.
+ If all modules are required, then installing the
+ <filename>kernel-modules</filename> package installs all packages with
+ modules and various other kernel packages such as
+ <filename>kernel-vmlinux</filename>.
+ </para>
+
+ <para>
+ The <filename>kernel</filename> class contains logic that allows
+ you to embed an initial RAM filesystem (initramfs) image when
+ you build the kernel image.
+ For information on how to build an initramfs, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image'>Building an Initial RAM Filesystem (initramfs) Image</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ Various other classes are used by the <filename>kernel</filename>
+ and <filename>module</filename> classes internally including the
+ <link linkend='ref-classes-kernel-arch'><filename>kernel-arch</filename></link>,
+ <link linkend='ref-classes-module-base'><filename>module-base</filename></link>,
+ and
+ <link linkend='ref-classes-linux-kernel-base'><filename>linux-kernel-base</filename></link>
+ classes.
+ </para>
+</section>
+
+<section id='ref-classes-kernel-arch'>
+ <title><filename>kernel-arch.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-arch</filename> class
+ sets the <filename>ARCH</filename> environment variable for Linux
+ kernel compilation (including modules).
+ </para>
+</section>
+
+<section id='ref-classes-kernel-devicetree'>
+ <title><filename>kernel-devicetree.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-devicetree</filename> class, which is inherited by
+ the
+ <link linkend='ref-classes-kernel'><filename>kernel</filename></link>
+ class, supports device tree generation.
+ </para>
+</section>
+
+<section id='ref-classes-kernel-fitimage'>
+ <title><filename>kernel-fitimage.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-fitimage</filename> class provides support to
+ pack a kernel Image, device trees and a RAM disk into a single
+ FIT image. In theory, a FIT image can support any number of kernels,
+ RAM disks and device-trees.
+ However, <filename>kernel-fitimage</filename> currently only supports
+ limited usescases: just one kernel image, an optional RAM disk, and
+ any number of device tree.
+ </para>
+
+ <para>
+ To create a FIT image, it is required that
+ <filename><link linkend='var-KERNEL_CLASSES'>KERNEL_CLASSES</link></filename>
+ is set to "kernel-fitimage" and
+ <filename><link linkend='var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</link></filename>
+ is set to "fitImage".
+ </para>
+
+ <para>
+ The options for the device tree compiler passed to mkimage -D feature
+ when creating the FIT image are specified using the
+ <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>
+ variable.
+ </para>
+
+ <para>
+ Only a single kernel can be added to the FIT image created by
+ <filename>kernel-fitimage</filename> and the kernel image in FIT is
+ mandatory.
+ The address where the kernel image is to be loaded by U-boot is
+ specified by
+ <filename><link linkend='var-UBOOT_LOADADDRESS'>UBOOT_LOADADDRESS</link></filename>
+ and the entrypoint by
+ <filename><link linkend='var-UBOOT_ENTRYPOINT'>UBOOT_ENTRYPOINT</link></filename>.
+ </para>
+
+ <para>
+ Multiple device trees can be added to the FIT image created by
+ <filename>kernel-fitimage</filename> and the device tree is optional.
+ The address where the device tree is to be loaded by U-boot is
+ specified by
+ <filename><link linkend='var-UBOOT_DTBO_LOADADDRESS'>UBOOT_DTBO_LOADADDRESS</link></filename>
+ for device tree overlays and by
+ <filename><link linkend='var-UBOOT_DTB_LOADADDRESS'>UBOOT_DTB_LOADADDRESS</link></filename>
+ for device tree binaries.
+ </para>
+
+ <para>
+ Only a single RAM disk can be added to the FIT image created by
+ <filename>kernel-fitimage</filename> and the RAM disk in FIT is
+ optional.
+ The address where the RAM disk image is to be loaded by U-boot
+ is specified by
+ <filename><link linkend='var-UBOOT_RD_LOADADDRESS'>UBOOT_RD_LOADADDRESS</link></filename>
+ and the entrypoint by
+ <filename><link linkend='var-UBOOT_RD_ENTRYPOINT'>UBOOT_RD_ENTRYPOINT</link></filename>.
+ The ramdisk is added to FIT image when
+ <filename><link linkend='var-INITRAMFS_IMAGE'>INITRAMFS_IMAGE</link></filename>
+ is specified.
+ </para>
+
+ <para>
+ The FIT image generated by <filename>kernel-fitimage</filename> class
+ is signed when the variables
+ <filename><link linkend='var-UBOOT_SIGN_ENABLE'>UBOOT_SIGN_ENABLE</link></filename>,
+ <filename><link linkend='var-UBOOT_MKIMAGE_DTCOPTS'>UBOOT_MKIMAGE_DTCOPTS</link></filename>,
+ <filename><link linkend='var-UBOOT_SIGN_KEYDIR'>UBOOT_SIGN_KEYDIR</link></filename>
+ and
+ <filename><link linkend='var-UBOOT_SIGN_KEYNAME'>UBOOT_SIGN_KEYNAME</link></filename>
+ are set appropriately.
+ The default values used for
+ <filename><link linkend='var-FIT_HASH_ALG'>FIT_HASH_ALG</link></filename>
+ and
+ <filename><link linkend='var-FIT_SIGN_ALG'>FIT_SIGN_ALG</link></filename>
+ in <filename>kernel-fitimage</filename> are "sha256" and "rsa2048"
+ respectively.
+ </para>
+
+</section>
+
+<section id='ref-classes-kernel-grub'>
+ <title><filename>kernel-grub.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-grub</filename> class updates the boot area and
+ the boot menu with the kernel as the priority boot mechanism while
+ installing a RPM to update the kernel on a deployed target.
+ </para>
+</section>
+
+<section id='ref-classes-kernel-module-split'>
+ <title><filename>kernel-module-split.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-module-split</filename> class
+ provides common functionality for splitting Linux kernel modules into
+ separate packages.
+ </para>
+</section>
+
+<section id='ref-classes-kernel-uboot'>
+ <title><filename>kernel-uboot.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-uboot</filename> class provides support for
+ building from vmlinux-style kernel sources.
+ </para>
+</section>
+
+<section id='ref-classes-kernel-uimage'>
+ <title><filename>kernel-uimage.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-uimage</filename> class provides support to
+ pack uImage.
+ </para>
+</section>
+
+<section id='ref-classes-kernel-yocto'>
+ <title><filename>kernel-yocto.bbclass</filename></title>
+
+ <para>
+ The <filename>kernel-yocto</filename> class
+ provides common functionality for building from linux-yocto style
+ kernel source repositories.
+ </para>
+</section>
+
+<section id='ref-classes-kernelsrc'>
+ <title><filename>kernelsrc.bbclass</filename></title>
+
+ <para>
+ The <filename>kernelsrc</filename> class sets the Linux kernel
+ source and version.
+ </para>
+</section>
+
+<section id='ref-classes-lib_package'>
+ <title><filename>lib_package.bbclass</filename></title>
+
+ <para>
+ The <filename>lib_package</filename> class
+ supports recipes that build libraries and produce executable
+ binaries, where those binaries should not be installed by default
+ along with the library.
+ Instead, the binaries are added to a separate
+ <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-bin</filename>
+ package to make their installation optional.
+ </para>
+</section>
+
+<section id='ref-classes-libc*'>
+ <title><filename>libc*.bbclass</filename></title>
+
+ <para>
+ The <filename>libc*</filename> classes support recipes that build
+ packages with <filename>libc</filename>:
+ <itemizedlist>
+ <listitem><para>The <filename>libc-common</filename> class
+ provides common support for building with
+ <filename>libc</filename>.
+ </para></listitem>
+ <listitem><para>The <filename>libc-package</filename> class
+ supports packaging up <filename>glibc</filename> and
+ <filename>eglibc</filename>.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='ref-classes-license'>
+ <title><filename>license.bbclass</filename></title>
+
+ <para>
+ The <filename>license</filename> class provides license
+ manifest creation and license exclusion.
+ This class is enabled by default using the default value for the
+ <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
+ variable.
+ </para>
+</section>
+
+<section id='ref-classes-linux-kernel-base'>
+ <title><filename>linux-kernel-base.bbclass</filename></title>
+
+ <para>
+ The <filename>linux-kernel-base</filename> class
+ provides common functionality for recipes that build out of the Linux
+ kernel source tree.
+ These builds goes beyond the kernel itself.
+ For example, the Perf recipe also inherits this class.
+ </para>
+</section>
+
+<section id='ref-classes-linuxloader'>
+ <title><filename>linuxloader.bbclass</filename></title>
+
+ <para>
+ Provides the function <filename>linuxloader()</filename>, which gives
+ the value of the dynamic loader/linker provided on the platform.
+ This value is used by a number of other classes.
+ </para>
+</section>
+
+<section id='ref-classes-logging'>
+ <title><filename>logging.bbclass</filename></title>
+
+ <para>
+ The <filename>logging</filename> class provides the standard
+ shell functions used to log messages for various BitBake severity levels
+ (i.e. <filename>bbplain</filename>, <filename>bbnote</filename>,
+ <filename>bbwarn</filename>, <filename>bberror</filename>,
+ <filename>bbfatal</filename>, and <filename>bbdebug</filename>).
+ </para>
+
+ <para>
+ This class is enabled by default since it is inherited by
+ the <filename>base</filename> class.
+ </para>
+</section>
+
+<section id='ref-classes-meta'>
+ <title><filename>meta.bbclass</filename></title>
+
+ <para>
+ The <filename>meta</filename> class is inherited by recipes
+ that do not build any output packages themselves, but act as a "meta"
+ target for building other recipes.
+ </para>
+</section>
+
+<section id='ref-classes-metadata_scm'>
+ <title><filename>metadata_scm.bbclass</filename></title>
+
+ <para>
+ The <filename>metadata_scm</filename> class provides functionality for
+ querying the branch and revision of a Source Code Manager (SCM)
+ repository.
+ </para>
+
+ <para>
+ The <link linkend='ref-classes-base'><filename>base</filename></link>
+ class uses this class to print the revisions of each layer before
+ starting every build.
+ The <filename>metadata_scm</filename> class is enabled by default
+ because it is inherited by the <filename>base</filename> class.
+ </para>
+</section>
+
+<section id='ref-classes-migrate_localcount'>
+ <title><filename>migrate_localcount.bbclass</filename></title>
+
+ <para>
+ The <filename>migrate_localcount</filename> class verifies a recipe's
+ localcount data and increments it appropriately.
+ </para>
+</section>
+
+<section id='ref-classes-mime'>
+ <title><filename>mime.bbclass</filename></title>
+
+ <para>
+ The <filename>mime</filename> class generates the proper
+ post-install and post-remove (postinst/postrm) scriptlets for packages
+ that install MIME type files.
+ These scriptlets call <filename>update-mime-database</filename> to add
+ the MIME types to the shared database.
+ </para>
+</section>
+
+<section id='ref-classes-mirrors'>
+ <title><filename>mirrors.bbclass</filename></title>
+
+ <para>
+ The <filename>mirrors</filename> class sets up some standard
+ <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link> entries
+ for source code mirrors.
+ These mirrors provide a fall-back path in case the upstream source
+ specified in
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+ within recipes is unavailable.
+ </para>
+
+ <para>
+ This class is enabled by default since it is inherited by the
+ <link linkend='ref-classes-base'><filename>base</filename></link> class.
+ </para>
+</section>
+
+<section id='ref-classes-module'>
+ <title><filename>module.bbclass</filename></title>
+
+ <para>
+ The <filename>module</filename> class provides support for building
+ out-of-tree Linux kernel modules.
+ The class inherits the
+ <link linkend='ref-classes-module-base'><filename>module-base</filename></link>
+ and
+ <link linkend='ref-classes-kernel-module-split'><filename>kernel-module-split</filename></link>
+ classes, and implements the
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ and
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ tasks.
+ The class provides everything needed to build and package a kernel
+ module.
+ </para>
+
+ <para>
+ For general information on out-of-tree Linux kernel modules, see the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
+ section in the Yocto Project Linux Kernel Development Manual.
+ </para>
+</section>
+
+<section id='ref-classes-module-base'>
+ <title><filename>module-base.bbclass</filename></title>
+
+ <para>
+ The <filename>module-base</filename> class provides the base
+ functionality for building Linux kernel modules.
+ Typically, a recipe that builds software that includes one or
+ more kernel modules and has its own means of building
+ the module inherits this class as opposed to inheriting the
+ <link linkend='ref-classes-module'><filename>module</filename></link>
+ class.
+ </para>
+</section>
+
+<section id='ref-classes-multilib*'>
+ <title><filename>multilib*.bbclass</filename></title>
+
+ <para>
+ The <filename>multilib*</filename> classes provide support
+ for building libraries with different target optimizations or target
+ architectures and installing them side-by-side in the same image.
+ </para>
+
+ <para>
+ For more information on using the Multilib feature, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image'>Combining Multiple Versions of Library Files into One Image</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='ref-classes-native'>
+ <title><filename>native.bbclass</filename></title>
+
+ <para>
+ The <filename>native</filename> class provides common
+ functionality for recipes that build tools to run on the
+ <link linkend='hardware-build-system-term'>build host</link>
+ (i.e. tools that use the compiler or other tools from the
+ build host).
+ </para>
+
+ <para>
+ You can create a recipe that builds tools that run natively on the
+ host a couple different ways:
+ <itemizedlist>
+ <listitem><para>
+ Create a
+ <replaceable>myrecipe</replaceable><filename>-native.bb</filename>
+ recipe that inherits the <filename>native</filename> class.
+ If you use this method, you must order the inherit statement
+ in the recipe after all other inherit statements so that the
+ <filename>native</filename> class is inherited last.
+ <note><title>Warning</title>
+ When creating a recipe this way, the recipe name must
+ follow this naming convention:
+ <literallayout class='monospaced'>
+ <replaceable>myrecipe</replaceable>-native.bb
+ </literallayout>
+ Not using this naming convention can lead to subtle
+ problems caused by existing code that depends on that
+ naming convention.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Create or modify a target recipe that contains the following:
+ <literallayout class='monospaced'>
+ <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native"
+ </literallayout>
+ Inside the recipe, use <filename>_class-native</filename> and
+ <filename>_class-target</filename> overrides to specify any
+ functionality specific to the respective native or target
+ case.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Although applied differently, the <filename>native</filename> class is
+ used with both methods.
+ The advantage of the second method is that you do not need to have two
+ separate recipes (assuming you need both) for native and target.
+ All common parts of the recipe are automatically shared.
+ </para>
+</section>
+
+<section id='ref-classes-nativesdk'>
+ <title><filename>nativesdk.bbclass</filename></title>
+
+ <para>
+ The <filename>nativesdk</filename> class provides common
+ functionality for recipes that wish to build tools to run as part of
+ an SDK (i.e. tools that run on
+ <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>).
+ </para>
+
+ <para>
+ You can create a recipe that builds tools that run on the SDK machine
+ a couple different ways:
+ <itemizedlist>
+ <listitem><para>Create a
+ <filename>nativesdk-</filename><replaceable>myrecipe</replaceable><filename>.bb</filename>
+ recipe that inherits the <filename>nativesdk</filename> class.
+ If you use this method, you must order the inherit statement
+ in the recipe after all other inherit statements so that the
+ <filename>nativesdk</filename> class is inherited last.
+ </para></listitem>
+ <listitem><para>Create a <filename>nativesdk</filename> variant
+ of any recipe by adding the following:
+ <literallayout class='monospaced'>
+ <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "nativesdk"
+ </literallayout>
+ Inside the recipe, use <filename>_class-nativesdk</filename> and
+ <filename>_class-target</filename> overrides to specify any
+ functionality specific to the respective SDK machine or target
+ case.</para></listitem>
+ </itemizedlist>
+ <note><title>Warning</title>
+ When creating a recipe, you must follow this naming convention:
+ <literallayout class='monospaced'>
+ nativesdk-<replaceable>myrecipe</replaceable>.bb
+ </literallayout>
+ Not doing so can lead to subtle problems because code exists
+ that depends on the naming convention.
+ </note>
+ </para>
+
+ <para>
+ Although applied differently, the <filename>nativesdk</filename> class
+ is used with both methods.
+ The advantage of the second method is that you do not need to have two
+ separate recipes (assuming you need both) for the SDK machine and the
+ target.
+ All common parts of the recipe are automatically shared.
+ </para>
+</section>
+
+<section id='ref-classes-nopackages'>
+ <title><filename>nopackages.bbclass</filename></title>
+
+ <para>
+ Disables packaging tasks for those recipes and classes where
+ packaging is not needed.
+ </para>
+</section>
+
+<section id='ref-classes-npm'>
+ <title><filename>npm.bbclass</filename></title>
+
+ <para>
+ Provides support for building Node.js software fetched using the
+ <ulink url='https://en.wikipedia.org/wiki/Npm_(software)'>node package manager (NPM)</ulink>.
+ <note>
+ Currently, recipes inheriting this class must use the
+ <filename>npm://</filename> fetcher to have dependencies fetched
+ and packaged automatically.
+ </note>
+ For information on how to create NPM packages, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-node-package-manager-npm-packages'>Creating Node Package Manager (NPM) Packages</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='ref-classes-oelint'>
+ <title><filename>oelint.bbclass</filename></title>
+
+ <para>
+ The <filename>oelint</filename> class is an
+ obsolete lint checking tool that exists in
+ <filename>meta/classes</filename> in the
+ <link linkend='source-directory'>Source Directory</link>.
+ </para>
+
+ <para>
+ A number of classes exist that could be generally useful in
+ OE-Core but are never actually used within OE-Core itself.
+ The <filename>oelint</filename> class is one such example.
+ However, being aware of this class can reduce the proliferation of
+ different versions of similar classes across multiple layers.
+ </para>
+</section>
+
+<section id='ref-classes-own-mirrors'>
+ <title><filename>own-mirrors.bbclass</filename></title>
+
+ <para>
+ The <filename>own-mirrors</filename> class makes it
+ easier to set up your own
+ <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
+ from which to first fetch source before attempting to fetch it from the
+ upstream specified in
+ <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+ within each recipe.
+ </para>
+
+ <para>
+ To use this class, inherit it globally and specify
+ <link linkend='var-SOURCE_MIRROR_URL'><filename>SOURCE_MIRROR_URL</filename></link>.
+ Here is an example:
+ <literallayout class='monospaced'>
+ INHERIT += "own-mirrors"
+ SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
+ </literallayout>
+ You can specify only a single URL in
+ <filename>SOURCE_MIRROR_URL</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-package'>
+ <title><filename>package.bbclass</filename></title>
+
+ <para>
+ The <filename>package</filename> class supports generating
+ packages from a build's output.
+ The core generic functionality is in
+ <filename>package.bbclass</filename>.
+ The code specific to particular package types resides in these
+ package-specific classes:
+ <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link>,
+ <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link>,
+ <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>,
+ and
+ <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>.
+ <note><title>Warning</title>
+ The <filename>package_tar</filename> class is broken and not
+ supported.
+ It is recommended that you do not use this class.
+ </note>
+ </para>
+
+ <para>
+ You can control the list of resulting package formats by using the
+ <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
+ variable defined in your <filename>conf/local.conf</filename>
+ configuration file, which is located in the
+ <link linkend='build-directory'>Build Directory</link>.
+ When defining the variable, you can specify one or more package types.
+ Since images are generated from packages, a packaging class is
+ needed to enable image generation.
+ The first class listed in this variable is used for image generation.
+ </para>
+
+ <para>
+ If you take the optional step to set up a repository (package feed)
+ on the development host that can be used by DNF, you can
+ install packages from the feed while you are running the image
+ on the target (i.e. runtime installation of packages).
+ For more information, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ The package-specific class you choose can affect build-time performance
+ and has space ramifications.
+ In general, building a package with IPK takes about thirty percent less
+ time as compared to using RPM to build the same or similar package.
+ This comparison takes into account a complete build of the package with
+ all dependencies previously built.
+ The reason for this discrepancy is because the RPM package manager
+ creates and processes more
+ <link linkend='metadata'>Metadata</link> than the
+ IPK package manager.
+ Consequently, you might consider setting
+ <filename>PACKAGE_CLASSES</filename> to "package_ipk" if you are
+ building smaller systems.
+ </para>
+
+ <para>
+ Before making your package manager decision, however, you should
+ consider some further things about using RPM:
+ <itemizedlist>
+ <listitem><para>
+ RPM starts to provide more abilities than IPK due to
+ the fact that it processes more Metadata.
+ For example, this information includes individual file types,
+ file checksum generation and evaluation on install, sparse file
+ support, conflict detection and resolution for Multilib systems,
+ ACID style upgrade, and repackaging abilities for rollbacks.
+ </para></listitem>
+ <listitem><para>
+ For smaller systems, the extra space used for the Berkeley
+ Database and the amount of metadata when using RPM can affect
+ your ability to perform on-device upgrades.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ You can find additional information on the effects of the package
+ class at these two Yocto Project mailing list links:
+ <itemizedlist>
+ <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
+ https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
+ <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
+ https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='ref-classes-package_deb'>
+ <title><filename>package_deb.bbclass</filename></title>
+
+ <para>
+ The <filename>package_deb</filename> class
+ provides support for creating packages that use the Debian
+ (i.e. <filename>.deb</filename>) file format.
+ The class ensures the packages are written out in a
+ <filename>.deb</filename> file format to the
+ <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename>
+ directory.
+ </para>
+
+ <para>
+ This class inherits the
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ class and is enabled through the
+ <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+ variable in the <filename>local.conf</filename> file.
+ </para>
+</section>
+
+<section id='ref-classes-package_ipk'>
+ <title><filename>package_ipk.bbclass</filename></title>
+
+ <para>
+ The <filename>package_ipk</filename> class
+ provides support for creating packages that use the IPK
+ (i.e. <filename>.ipk</filename>) file format.
+ The class ensures the packages are written out in a
+ <filename>.ipk</filename> file format to the
+ <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename>
+ directory.
+ </para>
+
+ <para>
+ This class inherits the
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ class and is enabled through the
+ <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+ variable in the <filename>local.conf</filename> file.
+ </para>
+</section>
+
+<section id='ref-classes-package_rpm'>
+ <title><filename>package_rpm.bbclass</filename></title>
+
+ <para>
+ The <filename>package_rpm</filename> class
+ provides support for creating packages that use the RPM
+ (i.e. <filename>.rpm</filename>) file format.
+ The class ensures the packages are written out in a
+ <filename>.rpm</filename> file format to the
+ <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename>
+ directory.
+ </para>
+
+ <para>
+ This class inherits the
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ class and is enabled through the
+ <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+ variable in the <filename>local.conf</filename> file.
+ </para>
+</section>
+
+<section id='ref-classes-package_tar'>
+ <title><filename>package_tar.bbclass</filename></title>
+
+ <para>
+ The <filename>package_tar</filename> class
+ provides support for creating tarballs.
+ The class ensures the packages are written out in a
+ tarball format to the
+ <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename>
+ directory.
+ </para>
+
+ <para>
+ This class inherits the
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ class and is enabled through the
+ <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+ variable in the <filename>local.conf</filename> file.
+ <note>
+ You cannot specify the <filename>package_tar</filename> class
+ first using the <filename>PACKAGE_CLASSES</filename> variable.
+ You must use <filename>.deb</filename>,
+ <filename>.ipk</filename>, or <filename>.rpm</filename> file
+ formats for your image or SDK.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-packagedata'>
+ <title><filename>packagedata.bbclass</filename></title>
+
+ <para>
+ The <filename>packagedata</filename> class provides
+ common functionality for reading <filename>pkgdata</filename> files
+ found in
+ <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
+ These files contain information about each output package produced by
+ the OpenEmbedded build system.
+ </para>
+
+ <para>
+ This class is enabled by default because it is inherited by the
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ class.
+ </para>
+</section>
+
+<section id='ref-classes-packagegroup'>
+ <title><filename>packagegroup.bbclass</filename></title>
+
+ <para>
+ The <filename>packagegroup</filename> class sets default values
+ appropriate for package group recipes (e.g.
+ <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
+ <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
+ <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
+ and so forth).
+ It is highly recommended that all package group recipes inherit this class.
+ </para>
+
+ <para>
+ For information on how to use this class, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+
+ <para>
+ Previously, this class was called the <filename>task</filename> class.
+ </para>
+</section>
+
+<section id='ref-classes-patch'>
+ <title><filename>patch.bbclass</filename></title>
+
+ <para>
+ The <filename>patch</filename> class provides all functionality for
+ applying patches during the
+ <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
+ task.
+ </para>
+
+ <para>
+ This class is enabled by default because it is inherited by the
+ <link linkend='ref-classes-base'><filename>base</filename></link>
+ class.
+ </para>
+</section>
+
+<section id='ref-classes-perlnative'>
+ <title><filename>perlnative.bbclass</filename></title>
+
+ <para>
+ When inherited by a recipe, the <filename>perlnative</filename> class
+ supports using the native version of Perl built by the build system
+ rather than using the version provided by the build host.
+ </para>
+</section>
+
+<section id='ref-classes-pixbufcache'>
+ <title><filename>pixbufcache.bbclass</filename></title>
+
+ <para>
+ The <filename>pixbufcache</filename> class generates the proper
+ post-install and post-remove (postinst/postrm) scriptlets for packages
+ that install pixbuf loaders, which are used with
+ <filename>gdk-pixbuf</filename>.
+ These scriptlets call <filename>update_pixbuf_cache</filename>
+ to add the pixbuf loaders to the cache.
+ Since the cache files are architecture-specific,
+ <filename>update_pixbuf_cache</filename> is run using QEMU if the
+ postinst scriptlets need to be run on the build host during image
+ creation.
+ </para>
+
+ <para>
+ If the pixbuf loaders being installed are in packages other
+ than the recipe's main package, set
+ <link linkend='var-PIXBUF_PACKAGES'><filename>PIXBUF_PACKAGES</filename></link>
+ to specify the packages containing the loaders.
+ </para>
+</section>
+
+<section id='ref-classes-pkgconfig'>
+ <title><filename>pkgconfig.bbclass</filename></title>
+
+ <para>
+ The <filename>pkgconfig</filename> class provides a standard way to get
+ header and library information by using <filename>pkg-config</filename>.
+ This class aims to smooth integration of
+ <filename>pkg-config</filename> into libraries that use it.
+ </para>
+
+ <para>
+ During staging, BitBake installs <filename>pkg-config</filename>
+ data into the <filename>sysroots/</filename> directory.
+ By making use of sysroot functionality within
+ <filename>pkg-config</filename>, the <filename>pkgconfig</filename>
+ class no longer has to manipulate the files.
+ </para>
+</section>
+
+<section id='ref-classes-populate-sdk'>
+ <title><filename>populate_sdk.bbclass</filename></title>
+
+ <para>
+ The <filename>populate_sdk</filename> class provides support for
+ SDK-only recipes.
+ For information on advantages gained when building a cross-development
+ toolchain using the
+ <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
+ task, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
+ section in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
+ </para>
+</section>
+
+<section id='ref-classes-populate-sdk-*'>
+ <title><filename>populate_sdk_*.bbclass</filename></title>
+
+ <para>
+ The <filename>populate_sdk_*</filename> classes support SDK creation
+ and consist of the following classes:
+ <itemizedlist>
+ <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis>
+ The base class supporting SDK creation under all package
+ managers (i.e. DEB, RPM, and opkg).</para></listitem>
+ <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis>
+ Supports creation of the SDK given the Debian package manager.
+ </para></listitem>
+ <listitem><para><emphasis><filename>populate_sdk_rpm</filename>:</emphasis>
+ Supports creation of the SDK given the RPM package manager.
+ </para></listitem>
+ <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis>
+ Supports creation of the SDK given the opkg (IPK format)
+ package manager.
+ </para></listitem>
+ <listitem><para><emphasis><filename>populate_sdk_ext</filename>:</emphasis>
+ Supports extensible SDK creation under all package managers.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The <filename>populate_sdk_base</filename> class inherits the
+ appropriate <filename>populate_sdk_*</filename> (i.e.
+ <filename>deb</filename>, <filename>rpm</filename>, and
+ <filename>ipk</filename>) based on
+ <link linkend='var-IMAGE_PKGTYPE'><filename>IMAGE_PKGTYPE</filename></link>.
+ </para>
+
+ <para>
+ The base class ensures all source and destination directories are
+ established and then populates the SDK.
+ After populating the SDK, the <filename>populate_sdk_base</filename>
+ class constructs two sysroots:
+ <filename>${</filename><link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>}-nativesdk</filename>,
+ which contains the cross-compiler and associated tooling, and the
+ target, which contains a target root filesystem that is configured for
+ the SDK usage.
+ These two images reside in
+ <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>,
+ which consists of the following:
+ <literallayout class='monospaced'>
+ ${SDK_OUTPUT}/${SDK_ARCH}<replaceable>-nativesdk-pkgs</replaceable>
+ ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/<replaceable>target-pkgs</replaceable>
+ </literallayout>
+ </para>
+
+ <para>
+ Finally, the base populate SDK class creates the toolchain
+ environment setup script, the tarball of the SDK, and the installer.
+ </para>
+
+ <para>
+ The respective <filename>populate_sdk_deb</filename>,
+ <filename>populate_sdk_rpm</filename>, and
+ <filename>populate_sdk_ipk</filename> classes each support the
+ specific type of SDK.
+ These classes are inherited by and used with the
+ <filename>populate_sdk_base</filename> class.
+ </para>
+
+ <para>
+ For more information on the cross-development toolchain
+ generation, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ For information on advantages gained when building a
+ cross-development toolchain using the
+ <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link>
+ task, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>"
+ section in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
+ </para>
+</section>
+
+<section id='ref-classes-prexport'>
+ <title><filename>prexport.bbclass</filename></title>
+
+ <para>
+ The <filename>prexport</filename> class provides functionality for
+ exporting
+ <link linkend='var-PR'><filename>PR</filename></link> values.
+ <note>
+ This class is not intended to be used directly.
+ Rather, it is enabled when using
+ "<filename>bitbake-prserv-tool export</filename>".
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-primport'>
+ <title><filename>primport.bbclass</filename></title>
+
+ <para>
+ The <filename>primport</filename> class provides functionality for
+ importing
+ <link linkend='var-PR'><filename>PR</filename></link> values.
+ <note>
+ This class is not intended to be used directly.
+ Rather, it is enabled when using
+ "<filename>bitbake-prserv-tool import</filename>".
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-prserv'>
+ <title><filename>prserv.bbclass</filename></title>
+
+ <para>
+ The <filename>prserv</filename> class provides functionality for
+ using a
+ <ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>PR service</ulink>
+ in order to automatically manage the incrementing of the
+ <link linkend='var-PR'><filename>PR</filename></link> variable for
+ each recipe.
+ </para>
+
+ <para>
+ This class is enabled by default because it is inherited by the
+ <link linkend='ref-classes-package'><filename>package</filename></link>
+ class.
+ However, the OpenEmbedded build system will not enable the
+ functionality of this class unless
+ <link linkend='var-PRSERV_HOST'><filename>PRSERV_HOST</filename></link>
+ has been set.
+ </para>
+</section>
+
+<section id='ref-classes-ptest'>
+ <title><filename>ptest.bbclass</filename></title>
+
+ <para>
+ The <filename>ptest</filename> class provides functionality for
+ packaging and installing runtime tests for recipes that build software
+ that provides these tests.
+ </para>
+
+ <para>
+ This class is intended to be inherited by individual recipes.
+ However, the class' functionality is largely disabled unless "ptest"
+ appears in
+ <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+ See the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
+ section in the Yocto Project Development Tasks Manual for more
+ information on ptest.
+ </para>
+</section>
+
+<section id='ref-classes-ptest-gnome'>
+ <title><filename>ptest-gnome.bbclass</filename></title>
+
+ <para>
+ Enables package tests (ptests) specifically for GNOME packages,
+ which have tests intended to be executed with
+ <filename>gnome-desktop-testing</filename>.
+ </para>
+
+ <para>
+ For information on setting up and running ptests, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='ref-classes-python-dir'>
+ <title><filename>python-dir.bbclass</filename></title>
+
+ <para>
+ The <filename>python-dir</filename> class provides the base version,
+ location, and site package location for Python.
+ </para>
+</section>
+
+<section id='ref-classes-python3native'>
+ <title><filename>python3native.bbclass</filename></title>
+
+ <para>
+ The <filename>python3native</filename> class supports using the
+ native version of Python 3 built by the build system rather than
+ support of the version provided by the build host.
+ </para>
+</section>
+
+<section id='ref-classes-pythonnative'>
+ <title><filename>pythonnative.bbclass</filename></title>
+
+ <para>
+ When inherited by a recipe, the <filename>pythonnative</filename> class
+ supports using the native version of Python built by the build system
+ rather than using the version provided by the build host.
+ </para>
+</section>
+
+<section id='ref-classes-qemu'>
+ <title><filename>qemu.bbclass</filename></title>
+
+ <para>
+ The <filename>qemu</filename> class provides functionality for recipes
+ that either need QEMU or test for the existence of QEMU.
+ Typically, this class is used to run programs for a target system on
+ the build host using QEMU's application emulation mode.
+ </para>
+</section>
+
+<section id='ref-classes-recipe_sanity'>
+ <title><filename>recipe_sanity.bbclass</filename></title>
+
+ <para>
+ The <filename>recipe_sanity</filename> class checks for the presence
+ of any host system recipe prerequisites that might affect the
+ build (e.g. variables that are set or software that is present).
+ </para>
+</section>
+
+<section id='ref-classes-relocatable'>
+ <title><filename>relocatable.bbclass</filename></title>
+
+ <para>
+ The <filename>relocatable</filename> class enables relocation of
+ binaries when they are installed into the sysroot.
+ </para>
+
+ <para>
+ This class makes use of the
+ <link linkend='ref-classes-chrpath'><filename>chrpath</filename></link>
+ class and is used by both the
+ <link linkend='ref-classes-cross'><filename>cross</filename></link>
+ and
+ <link linkend='ref-classes-native'><filename>native</filename></link>
+ classes.
+ </para>
+</section>
+
+<section id='ref-classes-remove-libtool'>
+ <title><filename>remove-libtool.bbclass</filename></title>
+
+ <para>
+ The <filename>remove-libtool</filename> class adds a post function
+ to the
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ task to remove all <filename>.la</filename> files installed by
+ <filename>libtool</filename>.
+ Removing these files results in them being absent from both the
+ sysroot and target packages.
+ </para>
+
+ <para>
+ If a recipe needs the <filename>.la</filename> files to be installed,
+ then the recipe can override the removal by setting
+ <filename>REMOVE_LIBTOOL_LA</filename> to "0" as follows:
+ <literallayout class='monospaced'>
+ REMOVE_LIBTOOL_LA = "0"
+ </literallayout>
+ <note>
+ The <filename>remove-libtool</filename> class is not enabled by
+ default.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-report-error'>
+ <title><filename>report-error.bbclass</filename></title>
+
+ <para>
+ The <filename>report-error</filename> class supports enabling the
+ <ulink url='&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool'>error reporting tool</ulink>,
+ which allows you to submit build error information to a central
+ database.
+ </para>
+
+ <para>
+ The class collects debug information for recipe, recipe version, task,
+ machine, distro, build system, target system, host distro, branch,
+ commit, and log.
+ From the information, report files using a JSON format are created and
+ stored in
+ <filename>${</filename><link linkend='var-LOG_DIR'><filename>LOG_DIR</filename></link><filename>}/error-report</filename>.
+ </para>
+</section>
+
+<section id='ref-classes-rm-work'>
+ <title><filename>rm_work.bbclass</filename></title>
+
+ <para>
+ The <filename>rm_work</filename> class supports deletion of temporary
+ workspace, which can ease your hard drive demands during builds.
+ </para>
+
+ <para>
+ The OpenEmbedded build system can use a substantial amount of disk
+ space during the build process.
+ A portion of this space is the work files under the
+ <filename>${TMPDIR}/work</filename> directory for each recipe.
+ Once the build system generates the packages for a recipe, the work
+ files for that recipe are no longer needed.
+ However, by default, the build system preserves these files
+ for inspection and possible debugging purposes.
+ If you would rather have these files deleted to save disk space
+ as the build progresses, you can enable <filename>rm_work</filename>
+ by adding the following to your <filename>local.conf</filename> file,
+ which is found in the
+ <link linkend='build-directory'>Build Directory</link>.
+ <literallayout class='monospaced'>
+ INHERIT += "rm_work"
+ </literallayout>
+ If you are modifying and building source code out of the work directory
+ for a recipe, enabling <filename>rm_work</filename> will potentially
+ result in your changes to the source being lost.
+ To exclude some recipes from having their work directories deleted by
+ <filename>rm_work</filename>, you can add the names of the recipe or
+ recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
+ variable, which can also be set in your <filename>local.conf</filename>
+ file.
+ Here is an example:
+ <literallayout class='monospaced'>
+ RM_WORK_EXCLUDE += "busybox glibc"
+ </literallayout>
+ </para>
+</section>
+
+<section id='ref-classes-rootfs*'>
+ <title><filename>rootfs*.bbclass</filename></title>
+
+ <para>
+ The <filename>rootfs*</filename> classes support creating
+ the root filesystem for an image and consist of the following classes:
+ <itemizedlist>
+ <listitem><para>
+ The <filename>rootfs-postcommands</filename> class, which
+ defines filesystem post-processing functions for image recipes.
+ </para></listitem>
+ <listitem><para>
+ The <filename>rootfs_deb</filename> class, which supports
+ creation of root filesystems for images built using
+ <filename>.deb</filename> packages.</para></listitem>
+ <listitem><para>
+ The <filename>rootfs_rpm</filename> class, which supports
+ creation of root filesystems for images built using
+ <filename>.rpm</filename> packages.</para></listitem>
+ <listitem><para>
+ The <filename>rootfs_ipk</filename> class, which supports
+ creation of root filesystems for images built using
+ <filename>.ipk</filename> packages.</para></listitem>
+ <listitem><para>
+ The <filename>rootfsdebugfiles</filename> class, which installs
+ additional files found on the build host directly into the
+ root filesystem.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The root filesystem is created from packages using one of the
+ <filename>rootfs*.bbclass</filename> files as determined by the
+ <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+ variable.
+ </para>
+
+ <para>
+ For information on how root filesystem images are created, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#image-generation-dev-environment'>Image Generation</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para>
+</section>
+
+<section id='ref-classes-sanity'>
+ <title><filename>sanity.bbclass</filename></title>
+
+ <para>
+ The <filename>sanity</filename> class checks to see if prerequisite
+ software is present on the host system so that users can be notified
+ of potential problems that might affect their build.
+ The class also performs basic user configuration checks from
+ the <filename>local.conf</filename> configuration file to
+ prevent common mistakes that cause build failures.
+ Distribution policy usually determines whether to include this class.
+ </para>
+</section>
+
+<section id='ref-classes-scons'>
+ <title><filename>scons.bbclass</filename></title>
+
+ <para>
+ The <filename>scons</filename> class supports recipes that need to
+ build software that uses the SCons build system.
+ You can use the
+ <link linkend='var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></link>
+ variable to specify additional configuration options you want to pass
+ SCons command line.
+ </para>
+</section>
+
+<section id='ref-classes-sdl'>
+ <title><filename>sdl.bbclass</filename></title>
+
+ <para>
+ The <filename>sdl</filename> class supports recipes that need to build
+ software that uses the Simple DirectMedia Layer (SDL) library.
+ </para>
+</section>
+
+<section id='ref-classes-setuptools'>
+ <title><filename>setuptools.bbclass</filename></title>
+
+ <para>
+ The <filename>setuptools</filename> class supports Python
+ version 2.x extensions that use build systems based on
+ <filename>setuptools</filename>.
+ If your recipe uses these build systems, the recipe needs to
+ inherit the <filename>setuptools</filename> class.
+ </para>
+</section>
+
+<section id='ref-classes-setuptools3'>
+ <title><filename>setuptools3.bbclass</filename></title>
+
+ <para>
+ The <filename>setuptools3</filename> class supports Python
+ version 3.x extensions that use build systems based on
+ <filename>setuptools3</filename>.
+ If your recipe uses these build systems, the recipe needs to
+ inherit the <filename>setuptools3</filename> class.
+ </para>
+</section>
+
+<section id='ref-classes-sign_rpm'>
+ <title><filename>sign_rpm.bbclass</filename></title>
+
+ <para>
+ The <filename>sign_rpm</filename> class supports generating signed
+ RPM packages.
+ </para>
+</section>
+
+<section id='ref-classes-sip'>
+ <title><filename>sip.bbclass</filename></title>
+
+ <para>
+ The <filename>sip</filename> class
+ supports recipes that build or package SIP-based Python bindings.
+ </para>
+</section>
+
+<section id='ref-classes-siteconfig'>
+ <title><filename>siteconfig.bbclass</filename></title>
+
+ <para>
+ The <filename>siteconfig</filename> class
+ provides functionality for handling site configuration.
+ The class is used by the
+ <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
+ class to accelerate the
+ <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
+ task.
+ </para>
+</section>
+
+<section id='ref-classes-siteinfo'>
+ <title><filename>siteinfo.bbclass</filename></title>
+
+ <para>
+ The <filename>siteinfo</filename> class provides information about
+ the targets that might be needed by other classes or recipes.
+ </para>
+
+ <para>
+ As an example, consider Autotools, which can require tests that must
+ execute on the target hardware.
+ Since this is not possible in general when cross compiling, site
+ information is used to provide cached test results so these tests can
+ be skipped over but still make the correct values available.
+ The
+ <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
+ contains test results sorted into different categories such as
+ architecture, endianness, and the <filename>libc</filename> used.
+ Site information provides a list of files containing data relevant to
+ the current build in the
+ <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
+ that Autotools automatically picks up.
+ </para>
+
+ <para>
+ The class also provides variables like
+ <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
+ and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
+ that can be used elsewhere in the metadata.
+ </para>
+</section>
+
+<section id='ref-classes-spdx'>
+ <title><filename>spdx.bbclass</filename></title>
+
+ <para>
+ The <filename>spdx</filename> class integrates real-time license
+ scanning, generation of SPDX standard output, and verification
+ of license information during the build.
+ <note>
+ This class is currently at the prototype stage in the 1.6
+ release.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-sstate'>
+ <title><filename>sstate.bbclass</filename></title>
+
+ <para>
+ The <filename>sstate</filename> class provides support for Shared
+ State (sstate).
+ By default, the class is enabled through the
+ <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link>
+ variable's default value.
+ </para>
+
+ <para>
+ For more information on sstate, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para>
+</section>
+
+<section id='ref-classes-staging'>
+ <title><filename>staging.bbclass</filename></title>
+
+ <para>
+ The <filename>staging</filename> class installs files into individual
+ recipe work directories for sysroots.
+ The class contains the following key tasks:
+ <itemizedlist>
+ <listitem><para>
+ The
+ <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>
+ task, which is responsible for handing the files that end up
+ in the recipe sysroots.
+ </para></listitem>
+ <listitem><para>
+ The
+ <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
+ task (a "partner" task to the
+ <filename>populate_sysroot</filename> task), which installs
+ the files into the individual recipe work directories (i.e.
+ <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The code in the <filename>staging</filename> class is complex and
+ basically works in two stages:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Stage One:</emphasis>
+ The first stage addresses recipes that have files they want
+ to share with other recipes that have dependencies on the
+ originating recipe.
+ Normally these dependencies are installed through the
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ task into
+ <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>.
+ The <filename>do_populate_sysroot</filename> task copies
+ a subset of these files into
+ <filename>${SYSROOT_DESTDIR}</filename>.
+ This subset of files is controlled by the
+ <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>,
+ <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>,
+ and
+ <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>
+ variables.
+ <note>
+ Additionally, a recipe can customize the files further by
+ declaring a processing function in the
+ <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>
+ variable.
+ </note>
+ </para>
+
+ <para>
+ A shared state (sstate) object is built from these files
+ and the files are placed into a subdirectory of
+ <link linkend='structure-build-tmp-sysroots-components'><filename>tmp/sysroots-components/</filename></link>.
+ The files are scanned for hardcoded paths to the original
+ installation location.
+ If the location is found in text files, the hardcoded
+ locations are replaced by tokens and a list of the files
+ needing such replacements is created.
+ These adjustments are referred to as "FIXMEs".
+ The list of files that are scanned for paths is controlled by
+ the
+ <link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Stage Two:</emphasis>
+ The second stage addresses recipes that want to use something
+ from another recipe and declare a dependency on that recipe
+ through the
+ <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+ variable.
+ The recipe will have a
+ <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>
+ task and when
+ this task executes, it creates the
+ <filename>recipe-sysroot</filename> and
+ <filename>recipe-sysroot-native</filename> in the recipe
+ work directory (i.e.
+ <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>).
+ The OpenEmbedded build system creates hard links to copies of the
+ relevant files from <filename>sysroots-components</filename>
+ into the recipe work directory.
+ <note>
+ If hard links are not possible, the build system uses
+ actual copies.
+ </note>
+ The build system then addresses any "FIXMEs" to paths as
+ defined from the list created in the first stage.
+ </para>
+
+ <para>
+ Finally, any files in <filename>${bindir}</filename>
+ within the sysroot that have the prefix
+ "<filename>postinst-</filename>" are executed.
+ <note>
+ Although such sysroot post installation scripts are not
+ recommended for general use, the files do allow some issues
+ such as user creation and module indexes to be addressed.
+ </note>
+ </para>
+
+ <para>
+ Because recipes can have other dependencies outside of
+ <filename>DEPENDS</filename> (e.g.
+ <filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>),
+ the sysroot creation function
+ <filename>extend_recipe_sysroot</filename> is also added as
+ a pre-function for those tasks whose dependencies are not
+ through <filename>DEPENDS</filename> but operate similarly.
+ </para>
+
+ <para>
+ When installing dependencies into the sysroot, the code
+ traverses the dependency graph and processes dependencies
+ in exactly the same way as the dependencies would or would not
+ be when installed from sstate.
+ This processing means, for example, a native tool would have
+ its native dependencies added but a target library would not
+ have its dependencies traversed or installed.
+ The same sstate dependency code is used so that
+ builds should be identical regardless of whether sstate
+ was used or not.
+ For a closer look, see the
+ <filename>setscene_depvalid()</filename> function in the
+ <link linkend='ref-classes-sstate'><filename>sstate</filename></link>
+ class.
+ </para>
+
+ <para>
+ The build system is careful to maintain manifests of the files
+ it installs so that any given dependency can be installed as
+ needed.
+ The sstate hash of the installed item is also stored so that
+ if it changes, the build system can reinstall it.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='ref-classes-syslinux'>
+ <title><filename>syslinux.bbclass</filename></title>
+
+ <para>
+ The <filename>syslinux</filename> class provides syslinux-specific
+ functions for building bootable images.
+ </para>
+
+ <para>
+ The class supports the following variables:
+ <itemizedlist>
+ <listitem><para><link linkend='var-INITRD'><filename>INITRD</filename></link>:
+ Indicates list of filesystem images to concatenate and use as
+ an initial RAM disk (initrd).
+ This variable is optional.</para></listitem>
+ <listitem><para><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:
+ Indicates a filesystem image to include as the root filesystem.
+ This variable is optional.</para></listitem>
+ <listitem><para><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>:
+ Enables creating an automatic menu when set to "1".
+ </para></listitem>
+ <listitem><para><link linkend='var-LABELS'><filename>LABELS</filename></link>:
+ Lists targets for automatic configuration.
+ </para></listitem>
+ <listitem><para><link linkend='var-APPEND'><filename>APPEND</filename></link>:
+ Lists append string overrides for each label.
+ </para></listitem>
+ <listitem><para><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>:
+ Lists additional options to add to the syslinux file.
+ Semicolon characters separate multiple options.
+ </para></listitem>
+ <listitem><para><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>:
+ Lists a background for the VGA boot menu when you are using the
+ boot menu.</para></listitem>
+ <listitem><para><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>:
+ Set to "console=ttyX" to change kernel boot default console.
+ </para></listitem>
+ <listitem><para><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>:
+ Sets an alternate serial port.
+ Or, turns off serial when the variable is set with an
+ empty string.</para></listitem>
+ <listitem><para><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>:
+ Sets an alternate "console=tty..." kernel boot argument.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='ref-classes-systemd'>
+ <title><filename>systemd.bbclass</filename></title>
+
+ <para>
+ The <filename>systemd</filename> class provides support for recipes
+ that install systemd unit files.
+ </para>
+
+ <para>
+ The functionality for this class is disabled unless you have "systemd"
+ in
+ <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+ </para>
+
+ <para>
+ Under this class, the recipe or Makefile (i.e. whatever the recipe is
+ calling during the
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ task) installs unit files into
+ <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}${systemd_unitdir}/system</filename>.
+ If the unit files being installed go into packages other than the
+ main package, you need to set
+ <link linkend='var-SYSTEMD_PACKAGES'><filename>SYSTEMD_PACKAGES</filename></link>
+ in your recipe to identify the packages in which the files will be
+ installed.
+ </para>
+
+ <para>
+ You should set
+ <link linkend='var-SYSTEMD_SERVICE'><filename>SYSTEMD_SERVICE</filename></link>
+ to the name of the service file.
+ You should also use a package name override to indicate the package
+ to which the value applies.
+ If the value applies to the recipe's main package, use
+ <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>.
+ Here is an example from the connman recipe:
+ <literallayout class='monospaced'>
+ SYSTEMD_SERVICE_${PN} = "connman.service"
+ </literallayout>
+ Services are set up to start on boot automatically unless
+ you have set
+ <link linkend='var-SYSTEMD_AUTO_ENABLE'><filename>SYSTEMD_AUTO_ENABLE</filename></link>
+ to "disable".
+ </para>
+
+ <para>
+ For more information on <filename>systemd</filename>, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager'>Selecting an Initialization Manager</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='ref-classes-systemd-boot'>
+ <title><filename>systemd-boot.bbclass</filename></title>
+
+ <para>
+ The <filename>systemd-boot</filename> class provides functions specific
+ to the systemd-boot bootloader for building bootable images.
+ This is an internal class and is not intended to be used directly.
+ <note>
+ The <filename>systemd-boot</filename> class is a result from
+ merging the <filename>gummiboot</filename> class used in previous
+ Yocto Project releases with the <filename>systemd</filename>
+ project.
+ </note>
+ Set the
+ <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link>
+ variable to "systemd-boot" to use this class.
+ Doing so creates a standalone EFI bootloader that is not dependent
+ on systemd.
+ </para>
+
+ <para>
+ For information on more variables used and supported in this class,
+ see the
+ <link linkend='var-SYSTEMD_BOOT_CFG'><filename>SYSTEMD_BOOT_CFG</filename></link>,
+ <link linkend='var-SYSTEMD_BOOT_ENTRIES'><filename>SYSTEMD_BOOT_ENTRIES</filename></link>,
+ and
+ <link linkend='var-SYSTEMD_BOOT_TIMEOUT'><filename>SYSTEMD_BOOT_TIMEOUT</filename></link>
+ variables.
+ </para>
+
+ <para>
+ You can also see the
+ <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>
+ for more information.
+ </para>
+</section>
+
+<section id='ref-classes-terminal'>
+ <title><filename>terminal.bbclass</filename></title>
+
+ <para>
+ The <filename>terminal</filename> class provides support for starting
+ a terminal session.
+ The
+ <link linkend='var-OE_TERMINAL'><filename>OE_TERMINAL</filename></link>
+ variable controls which terminal emulator is used for the session.
+ </para>
+
+ <para>
+ Other classes use the <filename>terminal</filename> class anywhere a
+ separate terminal session needs to be started.
+ For example, the
+ <link linkend='ref-classes-patch'><filename>patch</filename></link>
+ class assuming
+ <link linkend='var-PATCHRESOLVE'><filename>PATCHRESOLVE</filename></link>
+ is set to "user", the
+ <link linkend='ref-classes-cml1'><filename>cml1</filename></link>
+ class, and the
+ <link linkend='ref-classes-devshell'><filename>devshell</filename></link>
+ class all use the <filename>terminal</filename> class.
+ </para>
+</section>
+
+<section id='ref-classes-testimage*'>
+ <title><filename>testimage*.bbclass</filename></title>
+
+ <para>
+ The <filename>testimage*</filename> classes support running
+ automated tests against images using QEMU and on actual hardware.
+ The classes handle loading the tests and starting the image.
+ To use the classes, you need to perform steps to set up the
+ environment.
+ <note><title>Tip</title>
+ Best practices include using
+ <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
+ rather than
+ <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to
+ inherit the <filename>testimage</filename> class for automated
+ image testing.
+ </note>
+ </para>
+
+ <para>
+ The tests are commands that run on the target system over
+ <filename>ssh</filename>.
+ Each test is written in Python and makes use of the
+ <filename>unittest</filename> module.
+ </para>
+
+ <para>
+ The <filename>testimage.bbclass</filename> runs tests on an image
+ when called using the following:
+ <literallayout class='monospaced'>
+ $ bitbake -c testimage <replaceable>image</replaceable>
+ </literallayout>
+ The <filename>testimage-auto</filename> class runs tests on an image
+ after the image is constructed (i.e.
+ <link linkend='var-TESTIMAGE_AUTO'><filename>TESTIMAGE_AUTO</filename></link>
+ must be set to "1").
+ </para>
+
+ <para>
+ For information on how to enable, run, and create new tests, see the
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+ section in the Yocto Project Development Tasks Manual.
+ </para>
+</section>
+
+<section id='ref-classes-testsdk'>
+ <title><filename>testsdk.bbclass</filename></title>
+
+ <para>
+ This class supports running automated tests against
+ software development kits (SDKs).
+ The <filename>testsdk</filename> class runs tests on an SDK when
+ called using the following:
+ <literallayout class='monospaced'>
+ $ bitbake -c testsdk image
+ </literallayout>
+ <note><title>Tip</title>
+ Best practices include using
+ <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
+ rather than
+ <link linkend='var-INHERIT'><filename>INHERIT</filename></link> to
+ inherit the <filename>testsdk</filename> class for automated
+ SDK testing.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-texinfo'>
+ <title><filename>texinfo.bbclass</filename></title>
+
+ <para>
+ This class should be inherited by recipes whose upstream packages
+ invoke the <filename>texinfo</filename> utilities at build-time.
+ Native and cross recipes are made to use the dummy scripts provided
+ by <filename>texinfo-dummy-native</filename>, for improved performance.
+ Target architecture recipes use the genuine
+ Texinfo utilities.
+ By default, they use the Texinfo utilities on the host system.
+ <note>
+ If you want to use the Texinfo recipe shipped with the build
+ system, you can remove "texinfo-native" from
+ <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link>
+ and makeinfo from
+ <link linkend='var-SANITY_REQUIRED_UTILITIES'><filename>SANITY_REQUIRED_UTILITIES</filename></link>.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-tinderclient'>
+ <title><filename>tinderclient.bbclass</filename></title>
+
+ <para>
+ The <filename>tinderclient</filename> class submits build results to
+ an external Tinderbox instance.
+ <note>
+ This class is currently unmaintained.
+ </note>
+ </para>
+</section>
+
+<section id='ref-classes-toaster'>
+ <title><filename>toaster.bbclass</filename></title>
+
+ <para>
+ The <filename>toaster</filename> class collects information about
+ packages and images and sends them as events that the BitBake
+ user interface can receive.
+ The class is enabled when the Toaster user interface is running.
+ </para>
+
+ <para>
+ This class is not intended to be used directly.
+ </para>
+</section>
+
+<section id='ref-classes-toolchain-scripts'>
+ <title><filename>toolchain-scripts.bbclass</filename></title>
+
+ <para>
+ The <filename>toolchain-scripts</filename> class provides the scripts
+ used for setting up the environment for installed SDKs.
+ </para>
+</section>
+
+<section id='ref-classes-typecheck'>
+ <title><filename>typecheck.bbclass</filename></title>
+
+ <para>
+ The <filename>typecheck</filename> class provides support for
+ validating the values of variables set at the configuration level
+ against their defined types.
+ The OpenEmbedded build system allows you to define the type of a
+ variable using the "type" varflag.
+ Here is an example:
+ <literallayout class='monospaced'>
+ IMAGE_FEATURES[type] = "list"
+ </literallayout>
+ </para>
+</section>
+
+<section id='ref-classes-uboot-config'>
+ <title><filename>uboot-config.bbclass</filename></title>
+
+ <para>
+ The <filename>uboot-config</filename> class provides support for
+ U-Boot configuration for a machine.
+ Specify the machine in your recipe as follows:
+ <literallayout class='monospaced'>
+ UBOOT_CONFIG ??= <default>
+ UBOOT_CONFIG[foo] = "config,images"
+ </literallayout>
+ You can also specify the machine using this method:
+ <literallayout class='monospaced'>
+ UBOOT_MACHINE = "config"
+ </literallayout>
+ See the
+ <link linkend='var-UBOOT_CONFIG'><filename>UBOOT_CONFIG</filename></link>
+ and
+ <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link>
+ variables for additional information.
+ </para>
+</section>
+
+<section id='ref-classes-uninative'>
+ <title><filename>uninative.bbclass</filename></title>
+
+ <para>
+ Attempts to isolate the build system from the host
+ distribution's C library in order to make re-use of native shared state
+ artifacts across different host distributions practical.
+ With this class enabled, a tarball containing a pre-built C library
+ is downloaded at the start of the build.
+ In the Poky reference distribution this is enabled by default
+ through
+ <filename>meta/conf/distro/include/yocto-uninative.inc</filename>.
+ Other distributions that do not derive from poky can also
+ "<filename>require conf/distro/include/yocto-uninative.inc</filename>"
+ to use this.
+ Alternatively if you prefer, you can build the uninative-tarball recipe
+ yourself, publish the resulting tarball (e.g. via HTTP) and set
+ <filename>UNINATIVE_URL</filename> and
+ <filename>UNINATIVE_CHECKSUM</filename> appropriately.
+ For an example, see the
+ <filename>meta/conf/distro/include/yocto-uninative.inc</filename>.
+ </para>
+
+ <para>
+ The <filename>uninative</filename> class is also used unconditionally
+ by the extensible SDK.
+ When building the extensible SDK,
+ <filename>uninative-tarball</filename> is built and the resulting
+ tarball is included within the SDK.
+ </para>
+</section>
+
+<section id='ref-classes-update-alternatives'>
+ <title><filename>update-alternatives.bbclass</filename></title>
+
+ <para>
+ The <filename>update-alternatives</filename> class helps the
+ alternatives system when multiple sources provide the same command.
+ This situation occurs when several programs that have the same or
+ similar function are installed with the same name.
+ For example, the <filename>ar</filename> command is available from the
+ <filename>busybox</filename>, <filename>binutils</filename> and
+ <filename>elfutils</filename> packages.
+ The <filename>update-alternatives</filename> class handles
+ renaming the binaries so that multiple packages can be installed
+ without conflicts.
+ The <filename>ar</filename> command still works regardless of which
+ packages are installed or subsequently removed.
+ The class renames the conflicting binary in each package and symlinks
+ the highest priority binary during installation or removal of packages.
+ </para>
+
+ <para>
+ To use this class, you need to define a number of variables:
+ <itemizedlist>
+ <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
+ </para></listitem>
+ <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
+ </para></listitem>
+ <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
+ </para></listitem>
+ <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
+ </para></listitem>
+ </itemizedlist>
+ These variables list alternative commands needed by a package,
+ provide pathnames for links, default links for targets, and
+ so forth.
+ For details on how to use this class, see the comments in the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>
+ file.
+ </para>
+
+ <note>
+ You can use the <filename>update-alternatives</filename> command
+ directly in your recipes.
+ However, this class simplifies things in most cases.
+ </note>
+</section>
+
+<section id='ref-classes-update-rc.d'>
+ <title><filename>update-rc.d.bbclass</filename></title>
+
+ <para>
+ The <filename>update-rc.d</filename> class uses
+ <filename>update-rc.d</filename> to safely install an
+ initialization script on behalf of the package.
+ The OpenEmbedded build system takes care of details such as making
+ sure the script is stopped before a package is removed and started when
+ the package is installed.
+ </para>
+
+ <para>
+ Three variables control this class:
+ <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
+ <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
+ <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
+ See the variable links for details.
+ </para>
+</section>
+
+<section id='ref-classes-useradd'>
+ <title><filename>useradd*.bbclass</filename></title>
+
+ <para>
+ The <filename>useradd*</filename> classes support the addition of users
+ or groups for usage by the package on the target.
+ For example, if you have packages that contain system services that
+ should be run under their own user or group, you can use these classes
+ to enable creation of the user or group.
+ The
+ <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
+ recipe in the <link linkend='source-directory'>Source Directory</link>
+ provides a simple example that shows how to add three
+ users and groups to two packages.
+ See the <filename>useradd-example.bb</filename> recipe for more
+ information on how to use these classes.
+ </para>
+
+ <para>
+ The <filename>useradd_base</filename> class provides basic
+ functionality for user or groups settings.
+ </para>
+
+ <para>
+ The <filename>useradd*</filename> classes support the
+ <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>,
+ <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
+ <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,
+ and
+ <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
+ variables.
+ </para>
+
+ <para>
+ The <filename>useradd-staticids</filename> class supports the addition
+ of users or groups that have static user identification
+ (<filename>uid</filename>) and group identification
+ (<filename>gid</filename>) values.
+ </para>
+
+ <para>
+ The default behavior of the OpenEmbedded build system for assigning
+ <filename>uid</filename> and <filename>gid</filename> values when
+ packages add users and groups during package install time is to
+ add them dynamically.
+ This works fine for programs that do not care what the values of the
+ resulting users and groups become.
+ In these cases, the order of the installation determines the final
+ <filename>uid</filename> and <filename>gid</filename> values.
+ However, if non-deterministic
+ <filename>uid</filename> and <filename>gid</filename> values are a
+ problem, you can override the default, dynamic application of these
+ values by setting static values.
+ When you set static values, the OpenEmbedded build system looks in
+ <link linkend='var-BBPATH'><filename>BBPATH</filename></link> for
+ <filename>files/passwd</filename> and <filename>files/group</filename>
+ files for the values.
+ </para>
+
+ <para>
+ To use static <filename>uid</filename> and <filename>gid</filename>
+ values, you need to set some variables.
+ See the
+ <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link>,
+ <link linkend='var-USERADD_UID_TABLES'><filename>USERADD_UID_TABLES</filename></link>,
+ <link linkend='var-USERADD_GID_TABLES'><filename>USERADD_GID_TABLES</filename></link>,
+ and
+ <link linkend='var-USERADD_ERROR_DYNAMIC'><filename>USERADD_ERROR_DYNAMIC</filename></link>
+ variables.
+ You can also see the
+ <link linkend='ref-classes-useradd'><filename>useradd</filename></link>
+ class for additional information.
+ </para>
+
+ <note><title>Notes</title>
+ You do not use the <filename>useradd-staticids</filename>
+ class directly.
+ You either enable or disable the class by setting the
+ <filename>USERADDEXTENSION</filename> variable.
+ If you enable or disable the class in a configured system,
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+ might contain incorrect <filename>uid</filename> and
+ <filename>gid</filename> values.
+ Deleting the <filename>TMPDIR</filename> directory
+ will correct this condition.
+ </note>
+</section>
+
+<section id='ref-classes-utility-tasks'>
+ <title><filename>utility-tasks.bbclass</filename></title>
+
+ <para>
+ The <filename>utility-tasks</filename> class provides support for
+ various "utility" type tasks that are applicable to all recipes,
+ such as
+ <link linkend='ref-tasks-clean'><filename>do_clean</filename></link> and
+ <link linkend='ref-tasks-listtasks'><filename>do_listtasks</filename></link>.
+ </para>
+
+ <para>
+ This class is enabled by default because it is inherited by
+ the
+ <link linkend='ref-classes-base'><filename>base</filename></link>
+ class.
+ </para>
+</section>
+
+<section id='ref-classes-utils'>
+ <title><filename>utils.bbclass</filename></title>
+
+ <para>
+ The <filename>utils</filename> class provides some useful Python
+ functions that are typically used in inline Python expressions
+ (e.g. <filename>${@...}</filename>).
+ One example use is for <filename>bb.utils.contains()</filename>.
+ </para>
+
+ <para>
+ This class is enabled by default because it is inherited by the
+ <link linkend='ref-classes-base'><filename>base</filename></link>
+ class.
+ </para>
+</section>
+
+<section id='ref-classes-vala'>
+ <title><filename>vala.bbclass</filename></title>
+
+ <para>
+ The <filename>vala</filename> class supports recipes that need to
+ build software written using the Vala programming language.
+ </para>
+</section>
+
+<section id='ref-classes-waf'>
+ <title><filename>waf.bbclass</filename></title>
+
+ <para>
+ The <filename>waf</filename> class supports recipes that need to build
+ software that uses the Waf build system.
+ You can use the
+ <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
+ or
+ <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>
+ variables to specify additional configuration options to be passed on
+ the Waf command line.
+ </para>
+</section>
+
+<!-- Undocumented classes are:
+ image-empty.bbclass (possibly being dropped)
+ migrate_localcount.bbclass (still need a description)
+-->
+
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->