diff options
Diffstat (limited to 'poky/documentation/ref-manual/ref-qa-checks.rst')
| -rw-r--r-- | poky/documentation/ref-manual/ref-qa-checks.rst | 243 |
1 files changed, 236 insertions, 7 deletions
diff --git a/poky/documentation/ref-manual/ref-qa-checks.rst b/poky/documentation/ref-manual/ref-qa-checks.rst index 5b9f92d35..54977dcb2 100644 --- a/poky/documentation/ref-manual/ref-qa-checks.rst +++ b/poky/documentation/ref-manual/ref-qa-checks.rst @@ -43,6 +43,8 @@ error form along with an explanation. Errors and Warnings =================== +.. _qa-check-libexec: + - ``<packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]`` The specified package contains files in ``/usr/libexec`` when the @@ -51,6 +53,7 @@ Errors and Warnings default can be changed (e.g. ``${libdir}``). +.. _qa-check-rpaths: - ``package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]`` @@ -65,6 +68,7 @@ Errors and Warnings software. +.. _qa-check-useless-rpaths: - ``<packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]`` @@ -77,6 +81,7 @@ Errors and Warnings the build of the software. +.. _qa-check-file-rdeps: - ``<packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]`` @@ -88,6 +93,7 @@ Errors and Warnings built. +.. _qa-check-build-deps: - ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]`` @@ -101,6 +107,7 @@ Errors and Warnings to add an explicit ``RDEPENDS`` for the dependency. +.. _qa-check-dev-so: - ``non -dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]`` @@ -112,6 +119,7 @@ Errors and Warnings file goes into an appropriate ``-dev`` package. +.. _qa-check-staticdev: - ``non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]`` @@ -121,6 +129,7 @@ Errors and Warnings goes into an appropriate ``-staticdev`` package. +.. _qa-check-libdir: - ``<packagename>: found library in wrong location [libdir]`` @@ -133,6 +142,7 @@ Errors and Warnings :term:`INSANE_SKIP` for the package. +.. _qa-check-debug-files: - ``non debug package contains .debug directory: <packagename> path <path> [debug-files]`` @@ -145,8 +155,9 @@ Errors and Warnings information on ``FILES``. +.. _qa-check-arch: -- ``Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]`` +- ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]`` By default, the OpenEmbedded build system checks the Executable and Linkable Format (ELF) type, bit size, and endianness of any binaries @@ -164,7 +175,7 @@ Errors and Warnings -- ``Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]`` +- ``Bit size did not match (<file_bits>, expected <machine_bits>) in <file> [arch]`` By default, the OpenEmbedded build system checks the Executable and Linkable Format (ELF) type, bit size, and endianness of any binaries @@ -182,7 +193,7 @@ Errors and Warnings -- ``Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]`` +- ``Endianness did not match (<file_endianness>, expected <machine_endianness>) in <file> [arch]`` By default, the OpenEmbedded build system checks the Executable and Linkable Format (ELF) type, bit size, and endianness of any binaries @@ -199,6 +210,7 @@ Errors and Warnings and verify that the compiler options being used are correct. +.. _qa-check-textrel: - ``ELF binary '<file>' has relocations in .text [textrel]`` @@ -218,8 +230,9 @@ Errors and Warnings http://www.akkadia.org/drepper/textrelocs.html. +.. _qa-check-ldflags: -- ``No GNU_HASH in the elf binary: '<file>' [ldflags]`` +- ``File '<file>' in package '<package>' doesn't have GNU_HASH (didn't pass LDFLAGS?) [ldflags]`` This indicates that binaries produced when building the recipe have not been linked with the :term:`LDFLAGS` options @@ -233,6 +246,7 @@ Errors and Warnings TARGET_CC_ARCH += "${LDFLAGS}" +.. _qa-check-xorg-driver-abi: - ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]`` @@ -245,6 +259,7 @@ Errors and Warnings to explicitly add dependencies to binary driver recipes. +.. _qa-check-infodir: - ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]`` @@ -256,6 +271,8 @@ Errors and Warnings rm ${D}${infodir}/dir +.. _qa-check-symlink-to-sysroot: + - ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]`` The specified symlink points into :term:`TMPDIR` on the @@ -264,6 +281,7 @@ Errors and Warnings symlink to use a relative path or remove the symlink. +.. _qa-check-la: - ``<file> failed sanity test (workdir) in path <path> [la]`` @@ -273,6 +291,7 @@ Errors and Warnings automatically itself. +.. _qa-check-pkgconfig: - ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]`` @@ -283,6 +302,7 @@ Errors and Warnings are accessed. +.. _qa-check-debug-deps: - ``<packagename> rdepends on <debug_packagename> [debug-deps]`` @@ -305,6 +325,7 @@ Errors and Warnings manually (e.g. by adding to :term:`RDEPENDS`). +.. _qa-check-dev-deps: - ``<packagename> rdepends on <dev_packagename> [dev-deps]`` @@ -327,6 +348,7 @@ Errors and Warnings manually (e.g. by adding to :term:`RDEPENDS`). +.. _qa-check-dep-cmp: - ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]`` @@ -341,6 +363,7 @@ Errors and Warnings adding to match those listed in the message. +.. _qa-check-compile-host-path: - ``<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]`` @@ -351,6 +374,7 @@ Errors and Warnings file. +.. _qa-check-install-host-path: - ``<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]`` @@ -361,8 +385,9 @@ Errors and Warnings file. +.. _qa-check-configure-unsafe: -- ``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>'`` +- ``This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. [configure-unsafe]`` The log for the :ref:`ref-tasks-configure` task indicates that paths on the host were searched for files, which is @@ -371,6 +396,7 @@ Errors and Warnings file. +.. _qa-check-pkgname: - ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]`` @@ -384,6 +410,7 @@ Errors and Warnings change the package name appropriately. +.. _qa-check-unknown-configure-option: - ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]`` @@ -401,6 +428,7 @@ Errors and Warnings accordingly. +.. _qa-check-pn-overrides: - ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]`` @@ -416,6 +444,7 @@ Errors and Warnings :term:`FILES` for additional information. +.. _qa-check-pkgvarcheck: - ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]`` @@ -432,7 +461,16 @@ Errors and Warnings ``RDEPENDS = "value"``). If you receive this error, correct any assignments to these variables within your recipe. - + +- ``recipe uses DEPENDS_${PN}, should use DEPENDS [pkgvarcheck]`` + + This check looks for instances of setting ``DEPENDS_${PN}`` + which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus + it is not correct to specify it for a particular package, nor will such + an assignment actually work.) Set ``DEPENDS`` instead. + + +.. _qa-check-already-stripped: - ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]`` @@ -458,6 +496,7 @@ Errors and Warnings strip the symbols from the binaries. +.. _qa-check-packages-list: - ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]`` @@ -467,6 +506,7 @@ Errors and Warnings already in the variable's value. +.. _qa-check-files-invalid: - ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]`` @@ -475,6 +515,7 @@ Errors and Warnings that there is only a single "/". +.. _qa-check-installed-vs-shipped: - ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]`` @@ -505,6 +546,9 @@ Errors and Warnings :term:`PRIVATE_LIBS` in the recipe that provides the private version of the library. + +.. _qa-check-unlisted-pkg-lics: + - ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]`` The :term:`LICENSE` of the recipe should be a superset @@ -512,7 +556,192 @@ Errors and Warnings words, any license in ``LICENSE_*`` should also appear in :term:`LICENSE`. - + +.. _qa-check-configure-gettext: + +- ``AM_GNU_GETTEXT used but no inherit gettext [configure-gettext]`` + + If a recipe is building something that uses automake and the automake + files contain an ``AM_GNU_GETTEXT`` directive then this check will fail + if there is no ``inherit gettext`` statement in the recipe to ensure + that gettext is available during the build. Add ``inherit gettext`` to + remove the warning. + + +.. _qa-check-mime: + +- ``package contains mime types but does not inherit mime: <packagename> path '<file>' [mime]`` + + The specified package contains mime type files (``.xml`` files in + ``${datadir}/mime/packages``) and yet does not inherit the mime + class which will ensure that these get properly installed. Either + add ``inherit mime`` to the recipe or remove the files at the + ``do_install`` step if they are not needed. + + +.. _qa-check-mime-xdg: + +- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]`` + + The specified package contains a .desktop file with a 'MimeType' key + present, but does not inherit the mime-xdg class that is required in + order for that to be activated. Either add ``inherit mime`` to the + recipe or remove the files at the ``do_install`` step if they are not + needed. + + +.. _qa-check-src-uri-bad: + +- ``<recipename>: SRC_URI uses unstable GitHub archives [src-uri-bad]`` + + GitHub provides "archive" tarballs, however these can be re-generated + on the fly and thus the file's signature will not necessarily match that + in the SRC_URI checksums in future leading to build failures. It is + recommended that you use an official release tarball or switch to + pulling the corresponding revision in the actual git repository instead. + + +- ``SRC_URI uses PN not BPN [src-uri-bad]`` + + If some part of :term:`SRC_URI` needs to reference the recipe name, it should do + so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change + for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND` + or multilib are being used. This check will fail if a reference to ``${PN}`` + is found within the ``SRC_URI`` value - change it to ``${BPN}`` instead. + + +.. _qa-check-unhandled-features-check: + +- ``<recipename>: recipe doesn't inherit features_check [unhandled-features-check]`` + + This check ensures that if one of the variables that the :ref:`features_check <ref-classes-features_check>` + class supports (e.g. :term:`REQUIRED_DISTRO_FEATURES`) is used, then the recipe + inherits ``features_check`` in order for the requirement to actually work. If + you are seeing this message, either add ``inherit features_check`` to your recipe + or remove the reference to the variable if it is not needed. + + +.. _qa-check-missing-update-alternatives: + +- ``<recipename>: recipe defines ALTERNATIVE_<packagename> but doesn't inherit update-alternatives. This might fail during do_rootfs later! [missing-update-alternatives]`` + + This check ensures that if a recipe sets the :term:`ALTERNATIVE` variable that the + recipe also inherits :ref:`update-alternatives <ref-classes-update-alternatives>` such + that the alternative will be correctly set up. If you are seeing this message, either + add ``inherit update-alternatives`` to your recipe or remove the reference to the variable + if it is not needed. + + +.. _qa-check-shebang-size: + +- ``<packagename>: <file> maximum shebang size exceeded, the maximum size is 128. [shebang-size]`` + + This check ensures that the shebang line (``#!`` in the first line) for a script + is not longer than 128 characters, which can cause an error at runtime depending + on the operating system. If you are seeing this message then the specified script + may need to be patched to have a shorter in order to avoid runtime problems. + + +.. _qa-check-perllocalpod: + +- ``<packagename> contains perllocal.pod (<files>), should not be installed [perllocalpod]`` + + ``perllocal.pod`` is an index file of locally installed modules and so shouldn't be + installed by any distribution packages. The :ref:`cpan <ref-classes-cpan>` class + already sets ``NO_PERLLOCAL`` to stop this file being generated by most Perl recipes, + but if a recipe is using ``MakeMaker`` directly then they might not be doing this + correctly. This check ensures that perllocal.pod is not in any package in order to + avoid multiple packages shipping this file and thus their packages conflicting + if installed together. + + +.. _qa-check-usrmerge: + +- ``<packagename> package is not obeying usrmerge distro feature. /<path> should be relocated to /usr. [usrmerge]`` + + If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package + installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this + message, it indicates that the ``do_install`` step (or perhaps the build process that + ``do_install`` is calling into, e.g. ``make install`` is using hardcoded paths instead + of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be + changed so that it does. + + +.. _qa-check-patch-fuzz: + +- ``Fuzz detected: <patch output> [patch-fuzz]`` + + This check looks for evidence of "fuzz" when applying patches within the ``do_patch`` + task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context + lines in order to apply the patch. Consider this example: + + Patch to be applied: :: + + --- filename + +++ filename + context line 1 + context line 2 + context line 3 + +newly added line + context line 4 + context line 5 + context line 6 + + Original source code: :: + + different context line 1 + different context line 2 + context line 3 + context line 4 + different context line 5 + different context line 6 + + Outcome (after applying patch with fuzz): :: + + different context line 1 + different context line 2 + context line 3 + newly added line + context line 4 + different context line 5 + different context line 6 + + Chances are, the newly added line was actually added in a completely + wrong location, or it was already in the original source and was added + for the second time. This is especially possible if the context line 3 + and 4 are blank or have only generic things in them, such as ``#endif`` or ``}``. + Depending on the patched code, it is entirely possible for an incorrectly + patched file to still compile without errors. + + *How to eliminate patch fuzz warnings* + + Use the ``devtool`` command as explained by the warning. First, unpack the + source into devtool workspace: :: + + devtool modify <recipe> + + This will apply all of the patches, and create new commits out of them in + the workspace - with the patch context updated. + + Then, replace the patches in the recipe layer: :: + + devtool finish --force-patch-refresh <recipe> <layer_path> + + The patch updates then need be reviewed (preferably with a side-by-side diff + tool) to ensure they are indeed doing the right thing i.e.: + + #. they are applied in the correct location within the file; + #. they do not introduce duplicate lines, or otherwise do things that + are no longer necessary. + + To confirm these things, you can also review the patched source code in + devtool's workspace, typically in ``<build_dir>/workspace/sources/<recipe>/`` + + Once the review is done, you can create and publish a layer commit with + the patch updates that modify the context. Devtool may also refresh + other things in the patches, those can be discarded. + + Configuring and Disabling QA Checks =================================== |