1 files changed, 524 insertions, 0 deletions

diff --git a/documentation/ref-manual/ref-qa-checks.rst b/documentation/ref-manual/ref-qa-checks.rst
new file mode 100644
index 0000000000..a8b9ef60e4
--- /dev/null
+++ b/documentation/ref-manual/ref-qa-checks.rst
@@ -0,0 +1,524 @@
+*****************************
+QA Error and Warning Messages
+*****************************
+
+.. _qa-introduction:
+
+Introduction
+============
+
+When building a recipe, the OpenEmbedded build system performs various
+QA checks on the output to ensure that common issues are detected and
+reported. Sometimes when you create a new recipe to build new software,
+it will build with no problems. When this is not the case, or when you
+have QA issues building any software, it could take a little time to
+resolve them.
+
+While it is tempting to ignore a QA message or even to disable QA
+checks, it is best to try and resolve any reported QA issues. This
+chapter provides a list of the QA messages and brief explanations of the
+issues you could encounter so that you can properly resolve problems.
+
+The next section provides a list of all QA error and warning messages
+based on a default configuration. Each entry provides the message or
+error form along with an explanation.
+
+.. note::
+
+   -  At the end of each message, the name of the associated QA test (as
+      listed in the "```insane.bbclass`` <#ref-classes-insane>`__"
+      section) appears within square brackets.
+
+   -  As mentioned, this list of error and warning messages is for QA
+      checks only. The list does not cover all possible build errors or
+      warnings you could encounter.
+
+   -  Because some QA checks are disabled by default, this list does not
+      include all possible QA check errors and warnings.
+
+.. _qa-errors-and-warnings:
+
+Errors and Warnings
+===================
+
+-  ``<packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]``
+
+   The specified package contains files in ``/usr/libexec`` when the
+   distro configuration uses a different path for ``<libexecdir>`` By
+   default, ``<libexecdir>`` is ``$prefix/libexec``. However, this
+   default can be changed (e.g. ``${libdir}``).
+
+    
+
+-  ``package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]``
+
+   The specified binary produced by the recipe contains dynamic library
+   load paths (rpaths) that contain build system paths such as
+   ```TMPDIR`` <#var-TMPDIR>`__, which are incorrect for the target and
+   could potentially be a security issue. Check for bad ``-rpath``
+   options being passed to the linker in your
+   ```do_compile`` <#ref-tasks-compile>`__ log. Depending on the build
+   system used by the software being built, there might be a configure
+   option to disable rpath usage completely within the build of the
+   software.
+
+    
+
+-  ``<packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]``
+
+   The specified binary produced by the recipe contains dynamic library
+   load paths (rpaths) that on a standard system are searched by default
+   by the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths
+   will not cause any breakage, they do waste space and are unnecessary.
+   Depending on the build system used by the software being built, there
+   might be a configure option to disable rpath usage completely within
+   the build of the software.
+
+    
+
+-  ``<packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]``
+
+   A file-level dependency has been identified from the specified
+   package on the specified files, but there is no explicit
+   corresponding entry in ```RDEPENDS`` <#var-RDEPENDS>`__. If
+   particular files are required at runtime then ``RDEPENDS`` should be
+   declared in the recipe to ensure the packages providing them are
+   built.
+
+    
+
+-  ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]``
+
+   A runtime dependency exists between the two specified packages, but
+   there is nothing explicit within the recipe to enable the
+   OpenEmbedded build system to ensure that dependency is satisfied.
+   This condition is usually triggered by an
+   ```RDEPENDS`` <#var-RDEPENDS>`__ value being added at the packaging
+   stage rather than up front, which is usually automatic based on the
+   contents of the package. In most cases, you should change the recipe
+   to add an explicit ``RDEPENDS`` for the dependency.
+
+    
+
+-  ``non -dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]``
+
+   Symlink ``.so`` files are for development only, and should therefore
+   go into the ``-dev`` package. This situation might occur if you add
+   ``*.so*`` rather than ``*.so.*`` to a non-dev package. Change
+   ```FILES`` <#var-FILES>`__ (and possibly
+   ```PACKAGES`` <#var-PACKAGES>`__) such that the specified ``.so``
+   file goes into an appropriate ``-dev`` package.
+
+    
+
+-  ``non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]``
+
+   Static ``.a`` library files should go into a ``-staticdev`` package.
+   Change ```FILES`` <#var-FILES>`__ (and possibly
+   ```PACKAGES`` <#var-PACKAGES>`__) such that the specified ``.a`` file
+   goes into an appropriate ``-staticdev`` package.
+
+    
+
+-  ``<packagename>: found library in wrong location [libdir]``
+
+   The specified file may have been installed into an incorrect
+   (possibly hardcoded) installation path. For example, this test will
+   catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
+   "lib32". Another example is when recipes install
+   ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". False
+   positives occasionally exist. For these cases add "libdir" to
+   ```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package.
+
+    
+
+-  ``non debug package contains .debug directory: <packagename> path <path> [debug-files]``
+
+   The specified package contains a ``.debug`` directory, which should
+   not appear in anything but the ``-dbg`` package. This situation might
+   occur if you add a path which contains a ``.debug`` directory and do
+   not explicitly add the ``.debug`` directory to the ``-dbg`` package.
+   If this is the case, add the ``.debug`` directory explicitly to
+   ``FILES_${PN}-dbg``. See ```FILES`` <#var-FILES>`__ for additional
+   information on ``FILES``.
+
+    
+
+-  ``Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]``
+
+   By default, the OpenEmbedded build system checks the Executable and
+   Linkable Format (ELF) type, bit size, and endianness of any binaries
+   to ensure they match the target architecture. This test fails if any
+   binaries do not match the type since there would be an
+   incompatibility. The test could indicate that the wrong compiler or
+   compiler options have been used. Sometimes software, like
+   bootloaders, might need to bypass this check. If the file you receive
+   the error for is firmware that is not intended to be executed within
+   the target operating system or is intended to run on a separate
+   processor within the device, you can add "arch" to
+   ```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package. Another
+   option is to check the ```do_compile`` <#ref-tasks-compile>`__ log
+   and verify that the compiler options being used are correct.
+
+    
+
+-  ``Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]``
+
+   By default, the OpenEmbedded build system checks the Executable and
+   Linkable Format (ELF) type, bit size, and endianness of any binaries
+   to ensure they match the target architecture. This test fails if any
+   binaries do not match the type since there would be an
+   incompatibility. The test could indicate that the wrong compiler or
+   compiler options have been used. Sometimes software, like
+   bootloaders, might need to bypass this check. If the file you receive
+   the error for is firmware that is not intended to be executed within
+   the target operating system or is intended to run on a separate
+   processor within the device, you can add "arch" to
+   ```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package. Another
+   option is to check the ```do_compile`` <#ref-tasks-compile>`__ log
+   and verify that the compiler options being used are correct.
+
+    
+
+-  ``Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]``
+
+   By default, the OpenEmbedded build system checks the Executable and
+   Linkable Format (ELF) type, bit size, and endianness of any binaries
+   to ensure they match the target architecture. This test fails if any
+   binaries do not match the type since there would be an
+   incompatibility. The test could indicate that the wrong compiler or
+   compiler options have been used. Sometimes software, like
+   bootloaders, might need to bypass this check. If the file you receive
+   the error for is firmware that is not intended to be executed within
+   the target operating system or is intended to run on a separate
+   processor within the device, you can add "arch" to
+   ```INSANE_SKIP`` <#var-INSANE_SKIP>`__ for the package. Another
+   option is to check the ```do_compile`` <#ref-tasks-compile>`__ log
+   and verify that the compiler options being used are correct.
+
+    
+
+-  ``ELF binary '<file>' has relocations in .text [textrel]``
+
+   The specified ELF binary contains relocations in its ``.text``
+   sections. This situation can result in a performance impact at
+   runtime.
+
+   Typically, the way to solve this performance issue is to add "-fPIC"
+   or "-fpic" to the compiler command-line options. For example, given
+   software that reads ```CFLAGS`` <#var-CFLAGS>`__ when you build it,
+   you could add the following to your recipe: CFLAGS_append = " -fPIC "
+
+   For more information on text relocations at runtime, see
+   ` <http://www.akkadia.org/drepper/textrelocs.html>`__.
+
+    
+
+-  ``No GNU_HASH in the elf binary: '<file>' [ldflags]``
+
+   This indicates that binaries produced when building the recipe have
+   not been linked with the ```LDFLAGS`` <#var-LDFLAGS>`__ options
+   provided by the build system. Check to be sure that the ``LDFLAGS``
+   variable is being passed to the linker command. A common workaround
+   for this situation is to pass in ``LDFLAGS`` using
+   ```TARGET_CC_ARCH`` <#var-TARGET_CC_ARCH>`__ within the recipe as
+   follows: TARGET_CC_ARCH += "${LDFLAGS}"
+
+    
+
+-  ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]``
+
+   The specified package contains an Xorg driver, but does not have a
+   corresponding ABI package dependency. The xserver-xorg recipe
+   provides driver ABI names. All drivers should depend on the ABI
+   versions that they have been built against. Driver recipes that
+   include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
+   automatically get these versions. Consequently, you should only need
+   to explicitly add dependencies to binary driver recipes.
+
+    
+
+-  ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]``
+
+   The ``/usr/share/info/dir`` should not be packaged. Add the following
+   line to your ```do_install`` <#ref-tasks-install>`__ task or to your
+   ``do_install_append`` within the recipe as follows: rm
+   ${D}${infodir}/dir
+
+    
+
+-  ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
+
+   The specified symlink points into ```TMPDIR`` <#var-TMPDIR>`__ on the
+   host. Such symlinks will work on the host. However, they are clearly
+   invalid when running on the target. You should either correct the
+   symlink to use a relative path or remove the symlink.
+
+    
+
+-  ``<file> failed sanity test (workdir) in path <path> [la]``
+
+   The specified ``.la`` file contains ```TMPDIR`` <#var-TMPDIR>`__
+   paths. Any ``.la`` file containing these paths is incorrect since
+   ``libtool`` adds the correct sysroot prefix when using the files
+   automatically itself.
+
+    
+
+-  ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]``
+
+   The specified ``.pc`` file contains
+   ```TMPDIR`` <#var-TMPDIR>`__\ ``/``\ ```WORKDIR`` <#var-WORKDIR>`__
+   paths. Any ``.pc`` file containing these paths is incorrect since
+   ``pkg-config`` itself adds the correct sysroot prefix when the files
+   are accessed.
+
+    
+
+-  ``<packagename> rdepends on <debug_packagename> [debug-deps]``
+
+   A dependency exists between the specified non-dbg package (i.e. a
+   package whose name does not end in ``-dbg``) and a package that is a
+   ``dbg`` package. The ``dbg`` packages contain debug symbols and are
+   brought in using several different methods:
+
+   -  Using the ``dbg-pkgs``
+      ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ value.
+
+   -  Using ```IMAGE_INSTALL`` <#var-IMAGE_INSTALL>`__.
+
+   -  As a dependency of another ``dbg`` package that was brought in
+      using one of the above methods.
+
+   The dependency might have been automatically added because the
+   ``dbg`` package erroneously contains files that it should not contain
+   (e.g. a non-symlink ``.so`` file) or it might have been added
+   manually (e.g. by adding to ```RDEPENDS`` <#var-RDEPENDS>`__).
+
+    
+
+-  ``<packagename> rdepends on <dev_packagename> [dev-deps]``
+
+   A dependency exists between the specified non-dev package (a package
+   whose name does not end in ``-dev``) and a package that is a ``dev``
+   package. The ``dev`` packages contain development headers and are
+   usually brought in using several different methods:
+
+   -  Using the ``dev-pkgs``
+      ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ value.
+
+   -  Using ```IMAGE_INSTALL`` <#var-IMAGE_INSTALL>`__.
+
+   -  As a dependency of another ``dev`` package that was brought in
+      using one of the above methods.
+
+   The dependency might have been automatically added (because the
+   ``dev`` package erroneously contains files that it should not have
+   (e.g. a non-symlink ``.so`` file) or it might have been added
+   manually (e.g. by adding to ```RDEPENDS`` <#var-RDEPENDS>`__).
+
+    
+
+-  ``<var>_<packagename> is invalid: <comparison> (<value>)   only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
+
+   If you are adding a versioned dependency relationship to one of the
+   dependency variables (```RDEPENDS`` <#var-RDEPENDS>`__,
+   ```RRECOMMENDS`` <#var-RRECOMMENDS>`__,
+   ```RSUGGESTS`` <#var-RSUGGESTS>`__,
+   ```RPROVIDES`` <#var-RPROVIDES>`__,
+   ```RREPLACES`` <#var-RREPLACES>`__, or
+   ```RCONFLICTS`` <#var-RCONFLICTS>`__), you must only use the named
+   comparison operators. Change the versioned dependency values you are
+   adding to match those listed in the message.
+
+    
+
+-  ``<recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path]``
+
+   The log for the ```do_compile`` <#ref-tasks-compile>`__ task
+   indicates that paths on the host were searched for files, which is
+   not appropriate when cross-compiling. Look for "is unsafe for
+   cross-compilation" or "CROSS COMPILE Badness" in the specified log
+   file.
+
+    
+
+-  ``<recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path]``
+
+   The log for the ```do_install`` <#ref-tasks-install>`__ task
+   indicates that paths on the host were searched for files, which is
+   not appropriate when cross-compiling. Look for "is unsafe for
+   cross-compilation" or "CROSS COMPILE Badness" in the specified log
+   file.
+
+    
+
+-  ``This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>'``
+
+   The log for the ```do_configure`` <#ref-tasks-configure>`__ task
+   indicates that paths on the host were searched for files, which is
+   not appropriate when cross-compiling. Look for "is unsafe for
+   cross-compilation" or "CROSS COMPILE Badness" in the specified log
+   file.
+
+    
+
+-  ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]``
+
+   The convention within the OpenEmbedded build system (sometimes
+   enforced by the package manager itself) is to require that package
+   names are all lower case and to allow a restricted set of characters.
+   If your recipe name does not match this, or you add packages to
+   ```PACKAGES`` <#var-PACKAGES>`__ that do not conform to the
+   convention, then you will receive this error. Rename your recipe. Or,
+   if you have added a non-conforming package name to ``PACKAGES``,
+   change the package name appropriately.
+
+    
+
+-  ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]``
+
+   The configure script is reporting that the specified options are
+   unrecognized. This situation could be because the options were
+   previously valid but have been removed from the configure script. Or,
+   there was a mistake when the options were added and there is another
+   option that should be used instead. If you are unsure, consult the
+   upstream build documentation, the ``./configure --help`` output, and
+   the upstream change log or release notes. Once you have worked out
+   what the appropriate change is, you can update
+   ```EXTRA_OECONF`` <#var-EXTRA_OECONF>`__,
+   ```PACKAGECONFIG_CONFARGS`` <#var-PACKAGECONFIG_CONFARGS>`__, or the
+   individual ```PACKAGECONFIG`` <#var-PACKAGECONFIG>`__ option values
+   accordingly.
+
+    
+
+-  ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]``
+
+   The specified recipe has a name (```PN`` <#var-PN>`__) value that
+   appears in ```OVERRIDES`` <#var-OVERRIDES>`__. If a recipe is named
+   such that its ``PN`` value matches something already in ``OVERRIDES``
+   (e.g. ``PN`` happens to be the same as ```MACHINE`` <#var-MACHINE>`__
+   or ```DISTRO`` <#var-DISTRO>`__), it can have unexpected
+   consequences. For example, assignments such as
+   ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
+   Rename your recipe (or if ``PN`` is being set explicitly, change the
+   ``PN`` value) so that the conflict does not occur. See
+   ```FILES`` <#var-FILES>`__ for additional information.
+
+    
+
+-  ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]``
+
+   Certain variables (```RDEPENDS`` <#var-RDEPENDS>`__,
+   ```RRECOMMENDS`` <#var-RRECOMMENDS>`__,
+   ```RSUGGESTS`` <#var-RSUGGESTS>`__,
+   ```RCONFLICTS`` <#var-RCONFLICTS>`__,
+   ```RPROVIDES`` <#var-RPROVIDES>`__,
+   ```RREPLACES`` <#var-RREPLACES>`__, ```FILES`` <#var-FILES>`__,
+   ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
+   ```ALLOW_EMPTY`` <#var-ALLOW_EMPTY>`__) should always be set specific
+   to a package (i.e. they should be set with a package name override
+   such as ``RDEPENDS_${PN} = "value"`` rather than
+   ``RDEPENDS = "value"``). If you receive this error, correct any
+   assignments to these variables within your recipe.
+
+    
+
+-  ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]``
+
+   Produced binaries have 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 ``-dbg`` packages,
+   this stripping must be disabled.
+
+   Depending on the build system used by the software being built,
+   disabling this stripping could be as easy as specifying an additional
+   configure option. If not, disabling stripping might involve patching
+   the build scripts. In the latter case, look for references to "strip"
+   or "STRIP", or the "-s" or "-S" command-line options being specified
+   on the linker command line (possibly through the compiler command
+   line if preceded with "-Wl,").
+
+   .. note::
+
+      Disabling stripping here does not mean that the final packaged
+      binaries will be unstripped. Once the OpenEmbedded build system
+      splits out debug symbols to the
+      -dbg
+      package, it will then strip the symbols from the binaries.
+
+    
+
+-  ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]``
+
+   Package names must appear only once in the
+   ```PACKAGES`` <#var-PACKAGES>`__ variable. You might receive this
+   error if you are attempting to add a package to ``PACKAGES`` that is
+   already in the variable's value.
+
+    
+
+-  ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]``
+
+   The string "//" is invalid in a Unix path. Correct all occurrences
+   where this string appears in a ```FILES`` <#var-FILES>`__ variable so
+   that there is only a single "/".
+
+    
+
+-  ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]``
+
+   Files have been installed within the
+   ```do_install`` <#ref-tasks-install>`__ task but have not been
+   included in any package by way of the ```FILES`` <#var-FILES>`__
+   variable. Files that do not appear in any package cannot be present
+   in an image later on in the build process. You need to do one of the
+   following:
+
+   -  Add the files to ``FILES`` for the package you want them to appear
+      in (e.g. ``FILES_${``\ ```PN`` <#var-PN>`__\ ``}`` for the main
+      package).
+
+   -  Delete the files at the end of the ``do_install`` task if the
+      files are not needed in any package.
+
+    
+
+-  ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later``
+
+   This message means that both ``<oldpackage>`` and ``<newpackage>``
+   provide the specified shared library. You can expect this message
+   when a recipe has been renamed. However, if that is not the case, the
+   message might indicate that a private version of a library is being
+   erroneously picked up as the provider for a common library. If that
+   is the case, you should add the library's ``.so`` file name to
+   ```PRIVATE_LIBS`` <#var-PRIVATE_LIBS>`__ in the recipe that provides
+   the private version of the library.
+
+-  ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
+
+   The ```LICENSE`` <#var-LICENSE>`__ of the recipe should be a superset
+   of all the licenses of all packages produced by this recipe. In other
+   words, any license in ``LICENSE_*`` should also appear in
+   ```LICENSE`` <#var-LICENSE>`__.
+
+    
+
+Configuring and Disabling QA Checks
+===================================
+
+You can configure the QA checks globally so that specific check failures
+either raise a warning or an error message, using the
+```WARN_QA`` <#var-WARN_QA>`__ and ```ERROR_QA`` <#var-ERROR_QA>`__
+variables, respectively. You can also disable checks within a particular
+recipe using ```INSANE_SKIP`` <#var-INSANE_SKIP>`__. For information on
+how to work with the QA checks, see the
+"```insane.bbclass`` <#ref-classes-insane>`__" section.
+
+.. note::
+
+   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.