ref-manual: Added more QA checks to the insane.bbclass.

Fixes [YOCTO #4788]

Added a bunch of new checks to the list of checks in this
class.  I also recast the section head to just have the
class file as the section heading.  This resulted in a link
that needed changed.

(From yocto-docs rev: 4a4df80c0b6012ad09ea526d2893e729aa06965b)

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

2 files changed, 193 insertions, 7 deletions

diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index d230ddd935..93c5d78bc2 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -454,11 +454,12 @@
 </section>
 
 <section id='ref-classes-insane'>
-<title>Generated Output Quality Assurance Checks - <filename>insane.bbclass</filename></title>
+<title><filename>insane.bbclass</filename></title>
 
     <para>
-        This class adds a step to the package generation process that sanity checks the
-        packages generated by the OpenEmbedded build system.
+        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.
@@ -588,9 +589,194 @@
                 <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>
+                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 that is easier.
+                </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
+                <filename>INCOMPATIBLE_LICENSE</filename>.
+                </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
+                <filename>PKGD</filename>) 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>
         </itemizedlist>
     </para>
     <note>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 2ae476239a..7b88ffe5ca 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -2116,7 +2116,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
                     </literallayout>
                 </para>
                 <para>
-                    See the "<link linkend='ref-classes-insane'>Generated Output Quality Assurance Checks - <filename>insane.bbclass</filename></link>"
+                    See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
                     section for a list of the valid QA checks you can
                     specify using this variable.
                 </para>