ref-manual: Edits to icecc class and re-order of "I" classes.

(From yocto-docs rev: 643ccc4ac495e0dc88de20012d4843d2a402b507)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 420 insertions, 400 deletions

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index da47d51fd6..f36c80d6f3 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -824,9 +824,8 @@
     <title><filename>icecc.bbclass</filename></title>
 
     <para>
-        The Icecream distributed compile support (<filename>icecc</filename>)
-        class stages directories with symlinks from
-        <filename>gcc</filename> and <filename>g++</filename> to
+        The <filename>icecc</filename> 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
@@ -892,26 +891,69 @@
     </para>
 </section>
 
-<section id='ref-classes-image-live'>
-    <title><filename>image-live.bbclass</filename></title>
+<section id='ref-classes-image'>
+    <title>Creating Images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
 
     <para>
-        The live image (<filename>image-live</filename>) class
-        supports building "live" images.
-        Normally, you do not use this class directly.
-        Instead, you add "live" to
-        <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
+        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-image-vmdk'>
-    <title><filename>image-vmdk.bbclass</filename></title>
+<section id='ref-classes-image_types'>
+    <title><filename>image_types.bbclass</filename></title>
 
     <para>
-        The Virtual Machine Disk image (<filename>image-vmdk</filename>) class
-        supports building VMware VMDK images.
+        The image types (<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, this class is enabled through the
+        <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
+        variable in
+        <link linkend='ref-classes-image'><filename>image.bbclass</filename></link>.
+        If you define your own image types using a custom BitBake class and
+        then use <filename>IMAGE_CLASSES</filename> to enable it, the custom
+        class must either inherit <filename>image_types</filename> or
+        <filename>image_types</filename> must also appear in
+        <filename>IMAGE_CLASSES</filename>.
+    </para>
+</section>
+
+<section id='ref-classes-image_types_uboot'>
+    <title><filename>image_types_uboot.bbclass</filename></title>
+
+    <para>
+        The U-Boot image types (<filename>image_types_uboot</filename>) class
+        defines additional image types specifically for the U-Boot bootloader.
+    </para>
+</section>
+
+<section id='ref-classes-image-live'>
+    <title><filename>image-live.bbclass</filename></title>
+
+    <para>
+        The live image (<filename>image-live</filename>) class
+        supports building "live" images.
         Normally, you do not use this class directly.
-        Instead, you add "vmdk" to
+        Instead, you add "live" to
         <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
     </para>
 </section>
@@ -979,37 +1021,378 @@
     </para>
 </section>
 
-<section id='ref-classes-image_types'>
-    <title><filename>image_types.bbclass</filename></title>
+<section id='ref-classes-image-vmdk'>
+    <title><filename>image-vmdk.bbclass</filename></title>
 
     <para>
-        The image types (<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.
+        The Virtual Machine Disk image (<filename>image-vmdk</filename>) class
+        supports building VMware VMDK images.
+        Normally, you do not use this class directly.
+        Instead, you add "vmdk" to
+        <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
     </para>
+</section>
+
+<section id='ref-classes-insane'>
+<title><filename>insane.bbclass</filename></title>
 
     <para>
-        By default, this class is enabled through the
-        <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
-        variable in
-        <link linkend='ref-classes-image'><filename>image.bbclass</filename></link>.
-        If you define your own image types using a custom BitBake class and
-        then use <filename>IMAGE_CLASSES</filename> to enable it, the custom
-        class must either inherit <filename>image_types</filename> or
-        <filename>image_types</filename> must also appear in
-        <filename>IMAGE_CLASSES</filename>.
+        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>
-</section>
 
-<section id='ref-classes-image_types_uboot'>
-    <title><filename>image_types_uboot.bbclass</filename></title>
+    <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>
-        The U-Boot image types (<filename>image_types_uboot</filename>) class
-        defines additional image types specifically for the U-Boot bootloader.
+        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>
 
@@ -2112,369 +2495,6 @@
     </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>