initial commit of Enea Linux 3.1HEADmaster

Migrated from the internal git server on the dora-enea branch

Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>

1 files changed, 1104 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
new file mode 100644
index 0000000..27edfde
--- /dev/null
+++ b/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,1104 @@
+<!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; ] >
+
+<chapter id='ref-classes'>
+<title>Classes</title>
+
+<para>
+    Class files are used to abstract common functionality and share it amongst multiple
+    <filename>.bb</filename> files.
+    Any <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> usually
+    found in a <filename>.bb</filename> file 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
+    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+    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>
+    In most cases inheriting the class is enough to enable its features, although
+    for some classes you might need to set variables or override some of the
+    default behavior.
+</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
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        You can reference the <filename>.bbclass</filename> files directly
+        for more information.
+</para>
+
+<section id='ref-classes-base'>
+    <title>The base Class - <filename>base.bbclass</filename></title>
+
+    <para>
+        The base class is special in that every <filename>.bb</filename>
+        file inherits it automatically.
+        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 <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>.
+        The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
+    </para>
+</section>
+
+<section id='ref-classes-autotools'>
+    <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
+
+    <para>
+        Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
+        and <filename>libtool</filename>) bring standardization.
+        This class defines a set of tasks (configure, compile etc.) that
+        work for all Autotooled packages.
+        It should usually be enough to define a few standard variables
+        and then simply <filename>inherit autotools</filename>.
+        This class can also work with software that emulates Autotools.
+        For more information, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+
+    <para>
+        It's useful to have some idea of how the tasks defined by this class work
+        and what they do behind the scenes.
+        <itemizedlist>
+            <listitem><para><filename>do_configure</filename> &dash; 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> variable.
+                </para></listitem>
+            <listitem><para><filename>do_compile</filename> &dash; 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><filename>do_install</filename> &dash; 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-update-alternatives'>
+    <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
+
+    <para>
+        This 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.bbclass</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>.
+    </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>Initscripts - <filename>update-rc.d.bbclass</filename></title>
+
+    <para>
+        This 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.
+        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-binconfig'>
+    <title><filename>binconfig.bbclass</filename></title>
+
+    <para>
+        This 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-debian'>
+    <title>Debian Renaming - <filename>debian.bbclass</filename></title>
+
+    <para>
+        This class renames packages so that they follow the Debian naming
+        policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename>
+        and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>.)
+    </para>
+</section>
+
+<section id='ref-classes-pkgconfig'>
+    <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
+
+    <para>
+        <filename>pkg-config</filename> provides a standard way to get
+        header and library information.
+        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>,
+        this class no longer has to manipulate the files.
+    </para>
+</section>
+
+<section id='ref-classes-archiver'>
+    <title>Archiving Sources - <filename>archive*.bbclass</filename></title>
+
+    <para>
+        Many software licenses require that source code and other materials be
+        released with the binaries.
+        To help with that task, the following classes are provided:
+        <itemizedlist>
+            <listitem><filename>archive-original-sources.bbclass</filename></listitem>
+            <listitem><filename>archive-patched-sources.bbclass</filename></listitem>
+            <listitem><filename>archive-configured-sources.bbclass</filename></listitem>
+            <listitem><filename>archiver.bbclass</filename></listitem>
+        </itemizedlist>
+    </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 Manual.
+    </para>
+</section>
+
+<section id='ref-classes-perl'>
+    <title>Perl Modules - <filename>cpan.bbclass</filename></title>
+
+    <para>
+        Recipes for Perl modules are simple.
+        These recipes usually only need to point to the source's archive and then inherit the
+        proper <filename>.bbclass</filename> 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>
+    </para>
+</section>
+
+<section id='ref-classes-distutils'>
+    <title>Python Extensions - <filename>distutils.bbclass</filename></title>
+
+    <para>
+        Recipes for Python extensions are simple.
+        These recipes usually only need to point to the source's archive and then inherit
+        the proper <filename>.bbclass</filename> file.
+        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
+                <filename>distutils</filename>-based
+                <filename>.bbclasse</filename> files in their recipes.
+                </para></listitem>
+            <listitem><para>Extensions that use
+                <filename>distutils</filename>-based build systems require
+                <filename>distutils.bbclass</filename> in their recipes.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-devshell'>
+    <title>Developer Shell - <filename>devshell.bbclass</filename></title>
+
+    <para>
+        This class adds the <filename>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 Manual for more information about using <filename>devshell</filename>.
+    </para>
+</section>
+
+<section id='ref-classes-packagegroup'>
+    <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
+
+    <para>
+        This 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 Manual.
+    </para>
+    <para>
+        Previously, this class was named <filename>task.bbclass</filename>.
+    </para>
+</section>
+
+
+<section id='ref-classes-package'>
+    <title>Packaging - <filename>package*.bbclass</filename></title>
+
+    <para>
+        The packaging classes add support for generating packages from a build's
+        output.
+        The core generic functionality is in <filename>package.bbclass</filename>.
+        The code specific to particular package types is contained in various sub-classes such as
+        <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
+        and <filename>package_rpm.bbclass</filename>.
+        Most users will want one or more of these classes.
+    </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 the <filename>local.conf</filename> configuration file,
+        which is located in the <filename>conf</filename> folder of the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        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 Smart, 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 Manual.
+    </para>
+
+    <para>
+        The package 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
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> 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 decision on package manager, 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 Berkley
+                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-kernel'>
+    <title>Building Kernels - <filename>kernel.bbclass</filename></title>
+
+    <para>
+        This 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 <filename>module.bbclass</filename>.
+    </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>
+        Various other classes are used by the kernel and module classes internally including
+        <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
+        <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
+    </para>
+</section>
+
+<section id='ref-classes-image'>
+    <title>Creating Images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
+
+    <para>
+        These classes add support for creating images in several 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 the image is 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>
+    </para>
+</section>
+
+<section id='ref-classes-sanity'>
+    <title>Host System Sanity Checks - <filename>sanity.bbclass</filename></title>
+
+    <para>
+        This 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-insane'>
+<title><filename>insane.bbclass</filename></title>
+
+    <para>
+        This 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.
+    </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>ldflags:</filename></emphasis>
+                Ensures that the binaries were linked with the
+                <filename>LDFLAGS</filename> 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>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>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>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>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>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 don't match the type since there would be an
+                incompatibility.
+                Sometimes software, like bootloaders, might need to bypass this check.
+                </para></listitem>
+            <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
+                Checks that <filename>-dbg</filename> packages only depend on other
+                <filename>-dbg</filename> packages and not on any other types of packages,
+                which would cause a packaging bug.</para></listitem>
+            <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
+                Checks that <filename>-dev</filename> packages only depend on other
+                <filename>-dev</filename> packages and not on any other types of packages,
+                which would be a packaging bug.</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>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.</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>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>
+            <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>staticdev:</filename></emphasis>
+                Checks for static library files (<filename>*.a</filename>) in
+                non-<filename>staticdev</filename> packages.
+                </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>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>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>split-strip:</filename></emphasis>
+                Reports that splitting or stripping debug symbols from binaries
+                has failed.
+                </para></listitem>
+            <listitem><para><emphasis><filename>arch:</filename></emphasis>
+                Checks to ensure the architecture, bit size, and endianness
+                of all output binaries matches that of the target.
+                This test can detect when the wrong compiler or compiler options
+                have been used.
+                </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>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>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><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>compile-host-path:</filename></emphasis>
+                Checks the <filename>do_compile</filename> 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>install-host-path:</filename></emphasis>
+                Checks the <filename>do_install</filename> 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>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>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>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>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>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>unsafe-references-in-scripts:</filename></emphasis>
+                Reports when a script file installed in
+                <filename>${base_libdir}</filename>,
+                <filename>${base_bindir}</filename>, or
+                <filename>${base_sbindir}</filename>, depends on files
+                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>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 <filename>do_package</filename>.
+                </para></listitem>
+            <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
+                Checks to see if the <filename>PKGV</filename> variable
+                is undefined during <filename>do_package</filename>.
+                </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>perms:</filename></emphasis>
+                Currently, this check is unused but reserved.
+                </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>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-rm-work'>
+    <title>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></title>
+
+    <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
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+        <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 eglibc"
+        </literallayout>
+    </para>
+</section>
+
+
+<section id='ref-classes-siteinfo'>
+    <title>Autotools Configuration Data Cache - <filename>siteinfo.bbclass</filename></title>
+
+    <para>
+        Autotools 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>
+
+    <para>
+        Because this class is included from <filename>base.bbclass</filename>, it is always active.
+    </para>
+</section>
+
+<section id='ref-classes-useradd'>
+    <title>Adding Users - <filename>useradd.bbclass</filename></title>
+
+    <para>
+        If you have packages that install files that are owned by custom users or groups,
+        you can use this class to specify those packages and associate the users and groups
+        with those packages.
+        The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
+        recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+        provides a simple example that shows how to add three
+        users and groups to two packages.
+        See the <filename>useradd-example.bb</filename> for more information on how to
+        use this class.
+    </para>
+</section>
+
+<section id='ref-classes-externalsrc'>
+    <title><filename>externalsrc.bbclass</filename></title>
+
+    <para>
+        You can use this class to build 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 <filename>externalsrc.bbclass</filename>,
+        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 the glossary entries for the
+        <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
+        <link linkend='var-BPN'><filename>BPN</filename></link>,
+        <link linkend='var-PV'><filename>PV</filename></link>,
+    </para>
+
+    <para>
+        For more information on
+        <filename>externalsrc.bbclass</filename>, see the comments in
+        <filename>meta/classes/externalsrc.bbclass</filename> in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        For information on how to use <filename>externalsrc.bbclass</filename>,
+        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 Manual.
+    </para>
+</section>
+
+<section id='ref-classes-testimage'>
+    <title><filename>testimage.bbclass</filename></title>
+
+    <para>
+        You can use this class to enable running a series of automated tests
+        for images.
+        The class handles loading the tests and starting the image.
+        <note>
+            Currently, there is only support for running these tests
+            under QEMU.
+        </note>
+    </para>
+
+    <para>
+        To use the class, you need to perform steps to set up the
+        environment.
+        The tests are commands that run on the target system over
+        <filename>ssh</filename>.
+        they are written in Python and make use of the
+        <filename>unittest</filename> module.
+    </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.
+    </para>
+</section>
+
+<section id='ref-classes-others'>
+    <title>Other Classes</title>
+
+    <para>
+        Thus far, this chapter has discussed only the most useful and important
+        classes.
+        However, other classes exist within the <filename>meta/classes</filename> directory
+        in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        You can examine the <filename>.bbclass</filename> files directly for more
+        information.
+    </para>
+</section>
+
+<!-- Undocumented classes are:
+        allarch.bbclass
+        archive*.bbclass
+        binconfig.bbclass
+        bin_package.bbclass
+        blacklist.bbclass
+        bootimg.bbclass
+        boot-directdisk.bbclass
+        bugzilla.bbclass
+        buildhistory.bbclass
+        buildstats.bbclass
+        ccache.bbclass
+        chrpath.bbclass
+        clutter.bbclass
+        cmake.bbclass
+        cml1.bbclass
+        copyleft_compliance.bbclass
+        core-image.bbclass
+        cross.bbclass
+        cross-canadian.bbclass
+        crosssdk.bbclass
+        deploy.bbclass
+        distrodata.bbclass
+        distro_features_check.bbclass
+        dummy.bbclass
+        extrausers.bbclass
+        fontcache.bbclass
+        gconf.bbclass
+        gettext.bbclass
+        gnomebase.bbclass
+        gnome.bbclass
+        grub-efi.bbclass
+        gsettings.bbclass
+        gtk-doc.bbclass
+        gtk-icon-cache.bbclass
+        gtk-immodules-cache.bbclass
+        gzipnative.bbclass
+        icecc.bbclass
+        image-empty.bbclass
+        image-live.bbclass
+        image-vmdk.bbclass
+        image-mklibs.bbclass
+        image-prelink.bbclass
+        image-swab.bbclass
+        image_types.bbclass
+        image_types_uboot.bbclass
+        insserv.bbclass
+        kernel-arch.bbclass
+        kernel-module-split.bbclass
+        kernel-yocto.bbclass
+        lib_package.bbclass
+        linux-kernel-base.bbclass
+        license.bbclass
+        logging.bbclass
+        meta.bbclass
+        metadata_scm.bbclass
+        migrate_localcount.bbclass
+        mime.bbclass
+        mirrors.bbclass
+        multilib*.bbclass
+        native.bbclass
+        nativesdk.bbclass
+        oelint.bbclass
+        own-mirrors.bbclass
+        packagedata.bbclass
+        packageinfo.bbclass
+        patch.bbclass
+        perlnative.bbclass
+        pixbufcache.bbclass
+        pkg_distribute.bbclass
+        pkg_metainfo.bbclass
+        populate_sdk*.bbclass
+        prexport.bbclass
+        primport.bbclass
+        prserv.bbclass
+        ptest.bbclass
+        python-dir.bbclass
+        pythonnative.bbclass
+        qemu.bbclass
+        qmake*.bbclass
+        qt4*.bbclass
+        recipe_sanity.bbclass
+        relocatable.bbclass
+        scons.bbclass
+        sdl.bbclass
+        setuptools.bbclass
+        sip.bbclass
+        siteconfig.bbclass
+        sourcepkg.bbclass
+        spdx.bbclass
+        sstate.bbclass
+        staging.bbclass
+        syslinux.bbclass
+        systemd.bbclass
+        terminal.bbclass
+        tinderclient.bbclass
+        toolchain-scripts.bbclass
+        typecheck.bbclass
+        uboot-config.bbclass
+        utility-tasks.bbclass
+        utils.bbclass
+        vala.bbclass
+        waf.bbclass
+-->
+
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->