diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml | 1237 |
1 files changed, 1237 insertions, 0 deletions
diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml new file mode 100644 index 000000000..4fcf1db61 --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml @@ -0,0 +1,1237 @@ +<!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; ] > + +<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> + 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 [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> + +<!-- +Here are some messages that might be documented in the future. +Right now we are not documenting them because the QA checks are not +enabled by default: + + <para> + <itemizedlist> + <listitem><para> + <literallayout class='monospaced'> + Desktop file issue: <error> [desktop] + </literallayout> + NEED A DESCRIPTION AND SOLUTION + </para></listitem> + </itemizedlist> + </para> + + <para> + <itemizedlist> + <listitem><para> + <literallayout class='monospaced'> + <packagename>: <file>, installed in the base_prefix, requires a shared library under exec_prefix (<exec_prefix&t;g) [unsafe-references-in-binaries] + </literallayout> + NEED A DESCRIPTION AND SOLUTION + </para></listitem> + </itemizedlist> + </para> + + <para> + <itemizedlist> + <listitem><para> + <literallayout class='monospaced'> + <packagename>: Found a reference to <exec_prefix>/ in <path> - Shell scripts in base_bindir and base_sbindir should not reference anything in exec_prefix [unsafe-references-in-scripts] + </literallayout> + NEED A DESCRIPTION AND SOLUTION + </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 +--> |
