Gitiles
Code Review Sign In
gerrit.openbmc.org / openbmc / openbmc / 4873add6e11c1bd421c83cd08df589f1184aa673 / . / poky / documentation / ref-manual / ref-qa-checks.xml
blob: 0071e4a55d963ba3c35a13749970cb050c721eb1 [file] [log] [blame]
<!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>
&lt;packagename&gt;: &lt;path&gt; is using libexec please relocate to &lt;libexecdir&gt; [libexec]
</code>
</para>
<para>
The specified package contains files in
<filename>/usr/libexec</filename> when the distro
configuration uses a different path for
<filename>&lt;libexecdir&gt;</filename>
By default, <filename>&lt;libexecdir&gt;</filename> is
<filename>$prefix/libexec</filename>.
However, this default can be changed (e.g.
<filename>${libdir}</filename>).
</para>
<para>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-rpaths'>
<code>
package &lt;packagename&gt; contains bad RPATH &lt;rpath&gt; in file &lt;file&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-useless-rpaths'>
<code>
&lt;packagename&gt;: &lt;file&gt; contains probably-redundant RPATH &lt;rpath&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-file-rdeps'>
<code>
&lt;packagename&gt; requires &lt;files&gt;, 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-build-deps'>
<code>
&lt;packagename1&gt; rdepends on &lt;packagename2&gt;, 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-dev-so'>
<code>
non -dev/-dbg/nativesdk- package contains symlink .so: &lt;packagename&gt; path '&lt;path&gt;' [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-staticdev'>
<code>
non -staticdev package contains static .a library: &lt;packagename&gt; path '&lt;path&gt;' [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-libdir'>
<code>
&lt;packagename&gt;: 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-debug-files'>
<code>
non debug package contains .debug directory: &lt;packagename&gt; path &lt;path&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-arch'>
<code>
Architecture did not match (&lt;machine_arch&gt; to &lt;file_arch&gt;) on &lt;file&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-arch-bit-size-no-match'>
<code>
Bit size did not match (&lt;machine_bits&gt; to &lt;file_bits&gt;) &lt;recipe&gt; on &lt;file&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-arch-endianness-no-match'>
<code>
Endianness did not match (&lt;machine_endianness&gt; to &lt;file_endianness&gt;) on &lt;file&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-textrel'>
<code>
ELF binary '&lt;file&gt;' 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-ldflags'>
<code>
No GNU_HASH in the elf binary: '&lt;file&gt;' [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-xorg-driver-abi'>
<code>
Package &lt;packagename&gt; contains Xorg driver (&lt;driver&gt;) 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>
&nbsp;
</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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-symlink-to-sysroot'>
<code>
Symlink &lt;path&gt; in &lt;packagename&gt; 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-la'>
<code>
&lt;file&gt; failed sanity test (workdir) in path &lt;path&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-pkgconfig'>
<code>
&lt;file&gt; failed sanity test (tmpdir) in path &lt;path&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-debug-deps'>
<code>
&lt;packagename&gt; rdepends on &lt;debug_packagename&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-dev-deps'>
<code>
&lt;packagename&gt; rdepends on &lt;dev_packagename&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-dep-cmp'>
<code>
&lt;var&gt;_&lt;packagename&gt; is invalid: &lt;comparison&gt; (&lt;value&gt;) only comparisons &lt;, =, &gt;, &lt;=, and &gt;= 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-compile-host-path'>
<code>
&lt;recipename&gt;: The compile log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-install-host-path'>
<code>
&lt;recipename&gt;: The install log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' 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>
&nbsp;
</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 '&lt;path&gt;'
</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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-pkgname'>
<code>
&lt;packagename&gt; 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-unknown-configure-option'>
<code>
&lt;recipe&gt;: configure was passed unrecognized options: &lt;options&gt; [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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-pn-overrides'>
<code>
Recipe &lt;recipefile&gt; has PN of "&lt;recipename&gt;" 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-pkgvarcheck'>
<code>
&lt;recipefile&gt;: Variable &lt;variable&gt; 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-already-stripped'>
<code>
File '&lt;file&gt;' from &lt;recipename&gt; 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-packages-list'>
<code>
&lt;packagename&gt; 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-files-invalid'>
<code>
FILES variable for package &lt;packagename&gt; 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-installed-vs-shipped'>
<code>
&lt;recipename&gt;: 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>
&nbsp;
</para>
</listitem>
</itemizedlist>
</para>
<para>
<itemizedlist>
<listitem>
<para id='qa-issue-old-and-new-package-and-version-names'>
<code>
&lt;oldpackage&gt;-&lt;oldpkgversion&gt; was registered as shlib provider for &lt;library&gt;, changing it to &lt;newpackage&gt;-&lt;newpkgversion&gt; because it was built later
</code>
</para>
<para>
This message means that both
<filename>&lt;oldpackage&gt;</filename> and
<filename>&lt;newpackage&gt;</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_&lt;packagename&gt; includes licenses (&lt;licenses&gt;) 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>
&nbsp;
</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
-->