Revert "poky: subtree update:b23aa6b753..ad30a6d470"
This reverts commit af5e4ef732faedf66c6dc1756432e9de2ac72988.
This commit introduced openbmc/openbmc#3720 and no solution has been
forthcoming. Revert until we can get to the bottom of this.
Change-Id: I2fb0d81eb26cf3dadb2f2abdd1a1bb7a95eaf03c
diff --git a/poky/documentation/ref-manual/ref-qa-checks.xml b/poky/documentation/ref-manual/ref-qa-checks.xml
new file mode 100644
index 0000000..0071e4a
--- /dev/null
+++ b/poky/documentation/ref-manual/ref-qa-checks.xml
@@ -0,0 +1,1225 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='ref-qa-checks'>
+<title>QA Error and Warning Messages</title>
+
+<section id='qa-introduction'>
+ <title>Introduction</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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>
+ <title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ At the end of each message, the name of the associated
+ QA test (as listed in the
+ "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
+ section) appears within square brackets.
+ </para></listitem>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ <listitem><para>
+ Because some QA checks are disabled by default, this list
+ does not include all possible QA check errors and warnings.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+</section>
+
+<section id='qa-errors-and-warnings'>
+ <title>Errors and Warnings</title>
+
+<!--
+This section uses the <para><code> construct to enable permalinks for the
+various QA issue and warning messages. The file templates/qa-code-permalinks.xsl
+is used to locate the construct and generate the permalink. This solution
+leverages the fact that right now this section in the ref-manual is the only
+place is all the YP docs that uses the <para><code> construct. If, in the
+future, that construct were to appear in the ref-manual, a generic permalink
+would be generated for the text between <code></code>. If a better solution
+can be found then it should be implemented. I can't find one at the moment.
+-->
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-libexec'>
+ <code>
+ <packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]
+ </code>
+ </para>
+
+ <para>
+ The specified package contains files in
+ <filename>/usr/libexec</filename> when the distro
+ configuration uses a different path for
+ <filename><libexecdir></filename>
+ By default, <filename><libexecdir></filename> is
+ <filename>$prefix/libexec</filename>.
+ However, this default can be changed (e.g.
+ <filename>${libdir}</filename>).
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-rpaths'>
+ <code>
+ package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]
+ </code>
+ </para>
+
+ <para>
+ The specified binary produced by the recipe contains dynamic
+ library load paths (rpaths) that contain build system paths
+ such as
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
+ which are incorrect for the target and could potentially
+ be a security issue.
+ Check for bad <filename>-rpath</filename> options being
+ passed to the linker in your
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ 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.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-useless-rpaths'>
+ <code>
+ <packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]
+ </code>
+ </para>
+
+ <para>
+ 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.
+ <filename>/lib</filename> and <filename>/usr/lib</filename>).
+ 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.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-file-rdeps'>
+ <code>
+ <packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]
+ </code>
+ </para>
+
+ <para>
+ A file-level dependency has been identified from the
+ specified package on the specified files, but there is
+ no explicit corresponding entry in
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
+ If particular files are required at runtime then
+ <filename>RDEPENDS</filename> should be declared in the
+ recipe to ensure the packages providing them are built.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-build-deps'>
+ <code>
+ <packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+ 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 <filename>RDEPENDS</filename> for the dependency.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-dev-so'>
+ <code>
+ non -dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]
+ </code>
+ </para>
+
+ <para>
+ Symlink <filename>.so</filename> files are for development
+ only, and should therefore go into the
+ <filename>-dev</filename> package.
+ This situation might occur if you add
+ <filename>*.so*</filename> rather than
+ <filename>*.so.*</filename> to a non-dev package.
+ Change
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ (and possibly
+ <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
+ such that the specified <filename>.so</filename> file goes
+ into an appropriate <filename>-dev</filename> package.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-staticdev'>
+ <code>
+ non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]
+ </code>
+ </para>
+
+ <para>
+ Static <filename>.a</filename> library files should go into
+ a <filename>-staticdev</filename> package.
+ Change
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ (and possibly
+ <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
+ such that the specified <filename>.a</filename> file goes
+ into an appropriate <filename>-staticdev</filename> package.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-libdir'>
+ <code>
+ <packagename>: found library in wrong location [libdir]
+ </code>
+ </para>
+
+ <para>
+ The specified file may have been installed into an incorrect
+ (possibly hardcoded) installation path.
+ 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".
+ False positives occasionally exist.
+ For these cases add "libdir" to
+ <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
+ for the package.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-debug-files'>
+ <code>
+ non debug package contains .debug directory: <packagename> path <path> [debug-files]
+ </code>
+ </para>
+
+ <para>
+ The specified package contains a
+ <filename>.debug</filename> directory, which should not
+ appear in anything but the <filename>-dbg</filename>
+ package.
+ This situation might occur if you add a path which contains
+ a <filename>.debug</filename> directory and do not
+ explicitly add the <filename>.debug</filename> directory
+ to the <filename>-dbg</filename> package.
+ If this is the case, add the <filename>.debug</filename>
+ directory explicitly to
+ <filename>FILES_${PN}-dbg</filename>.
+ See
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ for additional information on <filename>FILES</filename>.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-arch'>
+ <code>
+ Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
+ for the package.
+ Another option is to check the
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ log and verify that the compiler options being used
+ are correct.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-arch-bit-size-no-match'>
+ <code>
+ Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
+ for the package.
+ Another option is to check the
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ log and verify that the compiler options being used are
+ correct.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-arch-endianness-no-match'>
+ <code>
+ Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
+ for the package.
+ Another option is to check the
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ log and verify that the compiler options being used
+ are correct.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-textrel'>
+ <code>
+ ELF binary '<file>' has relocations in .text [textrel]
+ </code>
+ </para>
+
+ <para>
+ The specified ELF binary contains relocations in its
+ <filename>.text</filename> sections.
+ This situation can result in a performance impact
+ at runtime.
+ </para>
+
+ <para>
+ 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
+ <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
+ when you build it, you could add the following to your
+ recipe:
+ <literallayout class='monospaced'>
+ CFLAGS_append = " -fPIC "
+ </literallayout>
+ </para>
+
+ <para>
+ For more information on text relocations at runtime, see
+ <ulink url='http://www.akkadia.org/drepper/textrelocs.html'></ulink>.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-ldflags'>
+ <code>
+ No GNU_HASH in the elf binary: '<file>' [ldflags]
+ </code>
+ </para>
+
+ <para>
+ This indicates that binaries produced when building the
+ recipe have not been linked with the
+ <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
+ options provided by the build system.
+ Check to be sure that the <filename>LDFLAGS</filename>
+ variable is being passed to the linker command.
+ A common workaround for this situation is to pass in
+ <filename>LDFLAGS</filename> using
+ <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
+ within the recipe as follows:
+ <literallayout class='monospaced'>
+ TARGET_CC_ARCH += "${LDFLAGS}"
+ </literallayout>
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-xorg-driver-abi'>
+ <code>
+ Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <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>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-infodir'>
+ <code>
+ The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]
+ </code>
+ </para>
+
+ <para>
+ The <filename>/usr/share/info/dir</filename> should not be
+ packaged.
+ Add the following line to your
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ task or to your <filename>do_install_append</filename>
+ within the recipe as follows:
+ <literallayout class='monospaced'>
+ rm ${D}${infodir}/dir
+ </literallayout>
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-symlink-to-sysroot'>
+ <code>
+ Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]
+ </code>
+ </para>
+
+ <para>
+ The specified symlink points into
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+ 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.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-la'>
+ <code>
+ <file> failed sanity test (workdir) in path <path> [la]
+ </code>
+ </para>
+
+ <para>
+ The specified <filename>.la</filename> file contains
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+ 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>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-pkgconfig'>
+ <code>
+ <file> failed sanity test (tmpdir) in path <path> [pkgconfig]
+ </code>
+ </para>
+
+ <para>
+ The specified <filename>.pc</filename> file contains
+ <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/</filename><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>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-debug-deps'>
+ <code>
+ <packagename> rdepends on <debug_packagename> [debug-deps]
+ </code>
+ </para>
+
+ <para>
+ A dependency exists between the specified non-dbg package
+ (i.e. a package whose name does not end in
+ <filename>-dbg</filename>) and a package that is a
+ <filename>dbg</filename> package.
+ The <filename>dbg</filename> packages contain
+ debug symbols and are brought in using several
+ different methods:
+ <itemizedlist>
+ <listitem><para>
+ Using the <filename>dbg-pkgs</filename>
+ <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
+ value.
+ </para></listitem>
+ <listitem><para>
+ Using
+ <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
+ </para></listitem>
+ <listitem><para>
+ As a dependency of another
+ <filename>dbg</filename> package that was brought
+ in using one of the above methods.
+ </para></listitem>
+ </itemizedlist>
+ The dependency might have been automatically added
+ because the <filename>dbg</filename> package erroneously
+ contains files that it should not contain (e.g. a
+ non-symlink <filename>.so</filename> file) or it might
+ have been added manually (e.g. by adding to
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-dev-deps'>
+ <code>
+ <packagename> rdepends on <dev_packagename> [dev-deps]
+ </code>
+ </para>
+
+ <para>
+ A dependency exists between the specified non-dev package
+ (a package whose name does not end in
+ <filename>-dev</filename>) and a package that is a
+ <filename>dev</filename> package.
+ The <filename>dev</filename> packages contain development
+ headers and are usually brought in using several different
+ methods:
+ <itemizedlist>
+ <listitem><para>
+ Using the <filename>dev-pkgs</filename>
+ <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
+ value.
+ </para></listitem>
+ <listitem><para>
+ Using
+ <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
+ </para></listitem>
+ <listitem><para>
+ As a dependency of another
+ <filename>dev</filename> package that was brought
+ in using one of the above methods.
+ </para></listitem>
+ </itemizedlist>
+ The dependency might have been automatically added (because
+ the <filename>dev</filename> package erroneously contains
+ files that it should not have (e.g. a non-symlink
+ <filename>.so</filename> file) or it might have been added
+ manually (e.g. by adding to
+ <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-dep-cmp'>
+ <code>
+ <var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]
+ </code>
+ </para>
+
+ <para>
+ If you are adding a versioned dependency relationship to one
+ of the dependency 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-RPROVIDES'><filename>RPROVIDES</filename></link>,
+ <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
+ or
+ <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>),
+ you must only use the named comparison operators.
+ Change the versioned dependency values you are adding
+ to match those listed in the message.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-compile-host-path'>
+ <code>
+ <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]
+ </code>
+ </para>
+
+ <para>
+ The log for the
+ <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
+ 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.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-install-host-path'>
+ <code>
+ <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]
+ </code>
+ </para>
+
+ <para>
+ The log for the
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ 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.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-autoconf-log'>
+ <code>
+ 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>'
+ </code>
+ </para>
+
+ <para>
+ The log for the
+ <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
+ 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.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-pkgname'>
+ <code>
+ <packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
+ 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
+ <filename>PACKAGES</filename>, change the package name
+ appropriately.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-unknown-configure-option'>
+ <code>
+ <recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <filename>./configure --help</filename> output,
+ and the upstream change log or release notes.
+ Once you have worked out what the appropriate
+ change is, you can update
+ <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>,
+ <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>,
+ or the individual
+ <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
+ option values accordingly.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-pn-overrides'>
+ <code>
+ Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]
+ </code>
+ </para>
+
+ <para>
+ The specified recipe has 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>.
+ Rename your recipe (or if <filename>PN</filename> is being
+ set explicitly, change the <filename>PN</filename> value) so
+ that the conflict does not occur.
+ See
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ for additional information.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-pkgvarcheck'>
+ <code>
+ <recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]
+ </code>
+ </para>
+
+ <para>
+ Certain 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>,
+ <filename>pkg_preinst</filename>,
+ <filename>pkg_postinst</filename>,
+ <filename>pkg_prerm</filename>,
+ <filename>pkg_postrm</filename>, and
+ <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>)
+ should always be set specific to a package (i.e. they
+ should be set with a package name override such as
+ <filename>RDEPENDS_${PN} = "value"</filename> rather than
+ <filename>RDEPENDS = "value"</filename>).
+ If you receive this error, correct any assignments to these
+ variables within your recipe.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-already-stripped'>
+ <code>
+ File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]
+ </code>
+ </para>
+
+ <para>
+ 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
+ <filename>-dbg</filename> packages, this stripping must be
+ disabled.
+ </para>
+
+ <para>
+ 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 <filename>-dbg</filename> package,
+ it will then strip the symbols from the binaries.
+ </note>
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-packages-list'>
+ <code>
+ <packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]
+ </code>
+ </para>
+
+ <para>
+ Package names must appear only once in the
+ <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
+ variable.
+ You might receive this error if you are attempting to add a
+ package to <filename>PACKAGES</filename> that is
+ already in the variable's value.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-files-invalid'>
+ <code>
+ FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]
+ </code>
+ </para>
+
+ <para>
+ The string "//" is invalid in a Unix path.
+ Correct all occurrences where this string appears in a
+ <link linkend='var-FILES'><filename>FILES</filename></link>
+ variable so that there is only a single "/".
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-installed-vs-shipped'>
+ <code>
+ <recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]
+ </code>
+ </para>
+
+ <para>
+ Files have been installed within the
+ <link linkend='ref-tasks-install'><filename>do_install</filename></link>
+ task 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.
+ You need to do one of the following:
+ <itemizedlist>
+ <listitem><para>
+ Add the files to <filename>FILES</filename> for the
+ package you want them to appear in (e.g.
+ <filename>FILES_${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> for the main
+ package).
+ </para></listitem>
+ <listitem><para>
+ Delete the files at the end of the
+ <filename>do_install</filename> task if the files
+ are not needed in any package.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-old-and-new-package-and-version-names'>
+ <code>
+ <oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later
+ </code>
+ </para>
+
+ <para>
+ This message means that both
+ <filename><oldpackage></filename> and
+ <filename><newpackage></filename> 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
+ <filename>.so</filename> file name to
+ <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
+ in the recipe that provides
+ the private version of the library.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para id='qa-issue-unlisted-pkg-lics'>
+ <code>
+ LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]
+ </code>
+ </para>
+
+ <para>
+ The <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
+ of the recipe should be a superset of all the licenses of
+ all packages produced by this recipe.
+ In other words, any license in <filename>LICENSE_*</filename>
+ should also appear in
+ <link linkend='var-LICENSE'><filename>LICENSE</filename></link>.
+ </para>
+
+ <para>
+
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+</section>
+
+<section id='configuring-and-disabling-qa-checks'>
+ <title>Configuring and Disabling QA Checks</title>
+
+ <para>
+ You can configure the QA checks globally so that specific check
+ failures either raise a warning or an error message, using the
+ <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
+ <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
+ variables, respectively.
+ You can also disable checks within a particular recipe using
+ <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
+ For information on how to work with the QA checks, see the
+ "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
+ section.
+ <note><title>Tip</title>
+ 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.
+ </note>
+ </para>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->