diff options
| author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-05-23 18:35:56 +0300 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-05-30 16:32:15 +0100 |
| commit | 3dd477c469af888cb222c160a5fda0f335c97acd (patch) | |
| tree | 8e6e5be746e92d59aab215bbb409042f6750d6c2 /documentation/ref-manual/ref-qa-checks.xml | |
| parent | 594833891de88c057e8c39eb648996bb757cbaed (diff) | |
| download | ast2050-yocto-poky-3dd477c469af888cb222c160a5fda0f335c97acd.zip ast2050-yocto-poky-3dd477c469af888cb222c160a5fda0f335c97acd.tar.gz | |
ref-manual: Applied review edits to QA messages and insane.bbclass.
Fixes [YOCTO #6159]
Edits from Paul Eggleton included some reformatting, some minor
wording tweaks, and edits to a couple tests as described in the
insane.bbclass.
(From yocto-docs rev: b42ef1bd51cb20f6bbb6bf812999e3a35b332339)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-qa-checks.xml')
| -rw-r--r-- | documentation/ref-manual/ref-qa-checks.xml | 1370 |
1 files changed, 860 insertions, 510 deletions
diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml index 16203e6..c31f9c7 100644 --- a/documentation/ref-manual/ref-qa-checks.xml +++ b/documentation/ref-manual/ref-qa-checks.xml @@ -9,10 +9,19 @@ <title>Introduction</title> <para> - Fixing QA issues in your recipes can take significant time and effort - when writing new recipes. - Sometimes you might be tempted to ignore a QA message or even to - disable these QA checks. + When building a recipe, the OpenEmbedded build system performs + various QA checks on the output to ensure that common issues are + detected and reported. + Some software builds that use new recipes complete with no problems. + However, some do not. + When issues are reported, 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. @@ -21,11 +30,18 @@ <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. + 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 offending + 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 @@ -45,700 +61,1013 @@ <para> <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <packagename>: <path> is using libexec please relocate to <libexecdir> [libexec] - </literallayout> - The specified package contains files in - <filename>/usr/libexec</filename>. - By default, <filename>libexecdir</filename> is set to - "${libdir}/${BPN}" rather than to "/usr/libexec". - Thus, installing to <filename>/usr/libexec</filename> - is likely not desirable. - </para></listitem> + </code> + </para> + + <para> + The specified package contains files in + <filename>/usr/libexec</filename>. + By default, <filename>libexecdir</filename> is set to + "${libdir}/${BPN}" rather than to "/usr/libexec". + Thus, installing to <filename>/usr/libexec</filename> + is likely not desirable. + </para> + + <para> + + </para> + </listitem> </itemizedlist> </para> <para> <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> + <listitem> + <para> + <code> package <packagename> contains bad RPATH <rpath> in file <file> [rpaths] - </literallayout> - 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 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> non -dev/-dbg/-nativesdk package contains symlink .so: <packagename> path '<path>' [dev-so] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <packagename>: found library in wrong location [libdir] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> non debug package contains .debug directory: <packagename> path <path> [debug-files] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> Architecture did not match (<machine_arch> to <file_arch>) on <file> - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> ELF binary '<file>' has relocations in .text [textrel] - </literallayout> - The specified ELF binary contains relocations in its - <filename>.text</filename> sections. - This situation can result in a performance impact at runtime. - <note> - A bug currently exists that causes this warning to appear - erroneously. - See - <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=6104'></ulink> - for more information. - </note> - </para></listitem> + </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. + <note> + A bug currently exists that causes this + warning to appear erroneously. + See + <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=6104'></ulink> + for more information. + </note> + </para> + + <para> + + </para> + </listitem> </itemizedlist> </para> <para> <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> + <listitem> + <para> + <code> No GNU_HASH in the elf binary: '<file>' [ldflags] - </literallayout> - 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'> + </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></listitem> + </literallayout> + </para> + + <para> + + </para> + </listitem> </itemizedlist> </para> <para> <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> + <listitem> + <para> + <code> Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir] - </literallayout> - 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'> + </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></listitem> + </literallayout> + </para> + + <para> + + </para> + </listitem> </itemizedlist> </para> <para> <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> + <listitem> + <para> + <code> Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <file> failed sanity test (workdir) in path <path> [la] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <file> failed sanity test (tmpdir) in path <path> [pkgconfig] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <packagename> rdepends on <debug_packagename> [debug-deps] - </literallayout> - A dependency exists between the specified non-dbg package - (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 usually brought in using the dbg-pkgs - <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> - value or explicitly brought into the image using - <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link> - (or as a dependency of another <filename>dbg</filename> - package brought in using either method). - 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></listitem> + </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 + that are brought in a number of ways: + <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> + Using either of the previous methods + as a dependency of another + <filename>dbg</filename> package. + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <packagename> rdepends on <dev_packagename> [dev-deps] - </literallayout> - 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 the dev-pkgs - <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> - value or explicitly brought into the image using - <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link> - (or as a dependency of another <filename>dev</filename> - package brought in using either method). - 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></listitem> + </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 the + <filename>dev-pkgs</filename> + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> + value or explicitly brought into the image using + <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link> + (or as a dependency of another <filename>dev</filename> + package brought in using either method). + 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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <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] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <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] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <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>' - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname] - </literallayout> - The convention within the OpenEmbedded build system is for - package names (sometimes enforced by the package manager itself) - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <recipe>: configure was passed unrecognized options: <options> [unknown-configure-option] - </literallayout> - 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. - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped] - </literallayout> - 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. - 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. - </para></listitem> + </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. + 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. + <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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid] - </literallayout> - 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></listitem> + </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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <recipename>: Files/directories were installed but not shipped [installed-vs-shipped] - </literallayout> - 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 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></listitem> + </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 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> - <literallayout class='monospaced'> + <listitem> + <para> + <code> <oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later - </literallayout> - 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> + </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> @@ -782,6 +1111,27 @@ enabled by default: --> </section> +<section id='configuring-and-disabling-qa-checks'> + <title>Configuring and Disabling QA Checks</title> + + <para> + You can configure the sanity checks so that specific test failures + either raise a warning or an error message. + You can also use the + <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and + <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link> + variables to configure warning and error reporting. + 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 |
