From 209aa9805aa8e6eaa37ada2e705608e6719c4341 Mon Sep 17 00:00:00 2001 From: Paul Eggleton Date: Tue, 27 Oct 2020 18:18:31 -0700 Subject: ref-manual: QA check updates * Update for changes to messages * Add missing QA checks - some added recently, others several releases ago Some of this was borrowed from commit messages (with editing) - in particular thanks to Alexander Kanavin for the writeup on patch-fuzz. (From yocto-docs rev: 6a5e846a92068758e49d1810789638b6990bf83d) Signed-off-by: Paul Eggleton Signed-off-by: Richard Purdie --- documentation/ref-manual/ref-qa-checks.rst | 207 ++++++++++++++++++++++++++++- 1 file changed, 200 insertions(+), 7 deletions(-) (limited to 'documentation/ref-manual') diff --git a/documentation/ref-manual/ref-qa-checks.rst b/documentation/ref-manual/ref-qa-checks.rst index 228b4fd538..54977dcb21 100644 --- a/documentation/ref-manual/ref-qa-checks.rst +++ b/documentation/ref-manual/ref-qa-checks.rst @@ -157,7 +157,7 @@ Errors and Warnings   .. _qa-check-arch: -- ``Architecture did not match ( to ) on [arch]`` +- ``Architecture did not match (, expected ) in [arch]`` By default, the OpenEmbedded build system checks the Executable and Linkable Format (ELF) type, bit size, and endianness of any binaries @@ -175,7 +175,7 @@ Errors and Warnings   -- ``Bit size did not match ( to ) on [arch]`` +- ``Bit size did not match (, expected ) in [arch]`` By default, the OpenEmbedded build system checks the Executable and Linkable Format (ELF) type, bit size, and endianness of any binaries @@ -193,7 +193,7 @@ Errors and Warnings   -- ``Endianness did not match ( to ) on [arch]`` +- ``Endianness did not match (, expected ) in [arch]`` By default, the OpenEmbedded build system checks the Executable and Linkable Format (ELF) type, bit size, and endianness of any binaries @@ -232,7 +232,7 @@ Errors and Warnings   .. _qa-check-ldflags: -- ``No GNU_HASH in the elf binary: '' [ldflags]`` +- ``File '' in 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 @@ -387,7 +387,7 @@ Errors and Warnings   .. _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 ''`` +- ``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 @@ -461,7 +461,15 @@ 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 '' from was already stripped, this will prevent future debugging! [already-stripped]`` @@ -548,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: path '' [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: path '' [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: + +- ``: 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: + +- ``: recipe doesn't inherit features_check [unhandled-features-check]`` + + This check ensures that if one of the variables that the :ref:`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: + +- ``: recipe defines ALTERNATIVE_ 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 ` 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: + +- ``: 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: + +- `` contains perllocal.pod (), 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 ` 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: + +- `` package is not obeying usrmerge distro feature. / 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-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 + + 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 + + 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 ``/workspace/sources//`` + + 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 =================================== -- cgit v1.2.3-54-g00ecf