summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorPaul Eggleton <paul.eggleton@microsoft.com>2020-10-27 18:18:31 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-30 12:09:21 +0000
commit209aa9805aa8e6eaa37ada2e705608e6719c4341 (patch)
tree9aa801f4957fde7651b1400da4534ffd93922a5f /documentation
parent249e789fedff88ecb16175d823fa8bc0d4383181 (diff)
downloadpoky-209aa9805aa8e6eaa37ada2e705608e6719c4341.tar.gz
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 <paul.eggleton@microsoft.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/ref-manual/ref-qa-checks.rst207
1 files changed, 200 insertions, 7 deletions
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
157   157  
158.. _qa-check-arch: 158.. _qa-check-arch:
159 159
160- ``Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]`` 160- ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]``
161 161
162 By default, the OpenEmbedded build system checks the Executable and 162 By default, the OpenEmbedded build system checks the Executable and
163 Linkable Format (ELF) type, bit size, and endianness of any binaries 163 Linkable Format (ELF) type, bit size, and endianness of any binaries
@@ -175,7 +175,7 @@ Errors and Warnings
175 175
176   176  
177 177
178- ``Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]`` 178- ``Bit size did not match (<file_bits>, expected <machine_bits>) in <file> [arch]``
179 179
180 By default, the OpenEmbedded build system checks the Executable and 180 By default, the OpenEmbedded build system checks the Executable and
181 Linkable Format (ELF) type, bit size, and endianness of any binaries 181 Linkable Format (ELF) type, bit size, and endianness of any binaries
@@ -193,7 +193,7 @@ Errors and Warnings
193 193
194   194  
195 195
196- ``Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]`` 196- ``Endianness did not match (<file_endianness>, expected <machine_endianness>) in <file> [arch]``
197 197
198 By default, the OpenEmbedded build system checks the Executable and 198 By default, the OpenEmbedded build system checks the Executable and
199 Linkable Format (ELF) type, bit size, and endianness of any binaries 199 Linkable Format (ELF) type, bit size, and endianness of any binaries
@@ -232,7 +232,7 @@ Errors and Warnings
232   232  
233.. _qa-check-ldflags: 233.. _qa-check-ldflags:
234 234
235- ``No GNU_HASH in the elf binary: '<file>' [ldflags]`` 235- ``File '<file>' in package '<package>' doesn't have GNU_HASH (didn't pass LDFLAGS?) [ldflags]``
236 236
237 This indicates that binaries produced when building the recipe have 237 This indicates that binaries produced when building the recipe have
238 not been linked with the :term:`LDFLAGS` options 238 not been linked with the :term:`LDFLAGS` options
@@ -387,7 +387,7 @@ Errors and Warnings
387   387  
388.. _qa-check-configure-unsafe: 388.. _qa-check-configure-unsafe:
389 389
390- ``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>'`` 390- ``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]``
391 391
392 The log for the :ref:`ref-tasks-configure` task 392 The log for the :ref:`ref-tasks-configure` task
393 indicates that paths on the host were searched for files, which is 393 indicates that paths on the host were searched for files, which is
@@ -461,7 +461,15 @@ Errors and Warnings
461 ``RDEPENDS = "value"``). If you receive this error, correct any 461 ``RDEPENDS = "value"``). If you receive this error, correct any
462 assignments to these variables within your recipe. 462 assignments to these variables within your recipe.
463 463
464   464
465- ``recipe uses DEPENDS_${PN}, should use DEPENDS [pkgvarcheck]``
466
467 This check looks for instances of setting ``DEPENDS_${PN}``
468 which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus
469 it is not correct to specify it for a particular package, nor will such
470 an assignment actually work.) Set ``DEPENDS`` instead.
471
472
465.. _qa-check-already-stripped: 473.. _qa-check-already-stripped:
466 474
467- ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]`` 475- ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]``
@@ -548,7 +556,192 @@ Errors and Warnings
548 words, any license in ``LICENSE_*`` should also appear in 556 words, any license in ``LICENSE_*`` should also appear in
549 :term:`LICENSE`. 557 :term:`LICENSE`.
550 558
551   559
560.. _qa-check-configure-gettext:
561
562- ``AM_GNU_GETTEXT used but no inherit gettext [configure-gettext]``
563
564 If a recipe is building something that uses automake and the automake
565 files contain an ``AM_GNU_GETTEXT`` directive then this check will fail
566 if there is no ``inherit gettext`` statement in the recipe to ensure
567 that gettext is available during the build. Add ``inherit gettext`` to
568 remove the warning.
569
570
571.. _qa-check-mime:
572
573- ``package contains mime types but does not inherit mime: <packagename> path '<file>' [mime]``
574
575 The specified package contains mime type files (``.xml`` files in
576 ``${datadir}/mime/packages``) and yet does not inherit the mime
577 class which will ensure that these get properly installed. Either
578 add ``inherit mime`` to the recipe or remove the files at the
579 ``do_install`` step if they are not needed.
580
581
582.. _qa-check-mime-xdg:
583
584- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]``
585
586 The specified package contains a .desktop file with a 'MimeType' key
587 present, but does not inherit the mime-xdg class that is required in
588 order for that to be activated. Either add ``inherit mime`` to the
589 recipe or remove the files at the ``do_install`` step if they are not
590 needed.
591
592
593.. _qa-check-src-uri-bad:
594
595- ``<recipename>: SRC_URI uses unstable GitHub archives [src-uri-bad]``
596
597 GitHub provides "archive" tarballs, however these can be re-generated
598 on the fly and thus the file's signature will not necessarily match that
599 in the SRC_URI checksums in future leading to build failures. It is
600 recommended that you use an official release tarball or switch to
601 pulling the corresponding revision in the actual git repository instead.
602
603
604- ``SRC_URI uses PN not BPN [src-uri-bad]``
605
606 If some part of :term:`SRC_URI` needs to reference the recipe name, it should do
607 so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change
608 for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND`
609 or multilib are being used. This check will fail if a reference to ``${PN}``
610 is found within the ``SRC_URI`` value - change it to ``${BPN}`` instead.
611
612
613.. _qa-check-unhandled-features-check:
614
615- ``<recipename>: recipe doesn't inherit features_check [unhandled-features-check]``
616
617 This check ensures that if one of the variables that the :ref:`features_check <ref-classes-features_check>`
618 class supports (e.g. :term:`REQUIRED_DISTRO_FEATURES`) is used, then the recipe
619 inherits ``features_check`` in order for the requirement to actually work. If
620 you are seeing this message, either add ``inherit features_check`` to your recipe
621 or remove the reference to the variable if it is not needed.
622
623
624.. _qa-check-missing-update-alternatives:
625
626- ``<recipename>: recipe defines ALTERNATIVE_<packagename> but doesn't inherit update-alternatives. This might fail during do_rootfs later! [missing-update-alternatives]``
627
628 This check ensures that if a recipe sets the :term:`ALTERNATIVE` variable that the
629 recipe also inherits :ref:`update-alternatives <ref-classes-update-alternatives>` such
630 that the alternative will be correctly set up. If you are seeing this message, either
631 add ``inherit update-alternatives`` to your recipe or remove the reference to the variable
632 if it is not needed.
633
634
635.. _qa-check-shebang-size:
636
637- ``<packagename>: <file> maximum shebang size exceeded, the maximum size is 128. [shebang-size]``
638
639 This check ensures that the shebang line (``#!`` in the first line) for a script
640 is not longer than 128 characters, which can cause an error at runtime depending
641 on the operating system. If you are seeing this message then the specified script
642 may need to be patched to have a shorter in order to avoid runtime problems.
643
644
645.. _qa-check-perllocalpod:
646
647- ``<packagename> contains perllocal.pod (<files>), should not be installed [perllocalpod]``
648
649 ``perllocal.pod`` is an index file of locally installed modules and so shouldn't be
650 installed by any distribution packages. The :ref:`cpan <ref-classes-cpan>` class
651 already sets ``NO_PERLLOCAL`` to stop this file being generated by most Perl recipes,
652 but if a recipe is using ``MakeMaker`` directly then they might not be doing this
653 correctly. This check ensures that perllocal.pod is not in any package in order to
654 avoid multiple packages shipping this file and thus their packages conflicting
655 if installed together.
656
657
658.. _qa-check-usrmerge:
659
660- ``<packagename> package is not obeying usrmerge distro feature. /<path> should be relocated to /usr. [usrmerge]``
661
662 If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package
663 installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this
664 message, it indicates that the ``do_install`` step (or perhaps the build process that
665 ``do_install`` is calling into, e.g. ``make install`` is using hardcoded paths instead
666 of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be
667 changed so that it does.
668
669
670.. _qa-check-patch-fuzz:
671
672- ``Fuzz detected: <patch output> [patch-fuzz]``
673
674 This check looks for evidence of "fuzz" when applying patches within the ``do_patch``
675 task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context
676 lines in order to apply the patch. Consider this example:
677
678 Patch to be applied: ::
679
680 --- filename
681 +++ filename
682 context line 1
683 context line 2
684 context line 3
685 +newly added line
686 context line 4
687 context line 5
688 context line 6
689
690 Original source code: ::
691
692 different context line 1
693 different context line 2
694 context line 3
695 context line 4
696 different context line 5
697 different context line 6
698
699 Outcome (after applying patch with fuzz): ::
700
701 different context line 1
702 different context line 2
703 context line 3
704 newly added line
705 context line 4
706 different context line 5
707 different context line 6
708
709 Chances are, the newly added line was actually added in a completely
710 wrong location, or it was already in the original source and was added
711 for the second time. This is especially possible if the context line 3
712 and 4 are blank or have only generic things in them, such as ``#endif`` or ``}``.
713 Depending on the patched code, it is entirely possible for an incorrectly
714 patched file to still compile without errors.
715
716 *How to eliminate patch fuzz warnings*
717
718 Use the ``devtool`` command as explained by the warning. First, unpack the
719 source into devtool workspace: ::
720
721 devtool modify <recipe>
722
723 This will apply all of the patches, and create new commits out of them in
724 the workspace - with the patch context updated.
725
726 Then, replace the patches in the recipe layer: ::
727
728 devtool finish --force-patch-refresh <recipe> <layer_path>
729
730 The patch updates then need be reviewed (preferably with a side-by-side diff
731 tool) to ensure they are indeed doing the right thing i.e.:
732
733 #. they are applied in the correct location within the file;
734 #. they do not introduce duplicate lines, or otherwise do things that
735 are no longer necessary.
736
737 To confirm these things, you can also review the patched source code in
738 devtool's workspace, typically in ``<build_dir>/workspace/sources/<recipe>/``
739
740 Once the review is done, you can create and publish a layer commit with
741 the patch updates that modify the context. Devtool may also refresh
742 other things in the patches, those can be discarded.
743
744
552 745
553Configuring and Disabling QA Checks 746Configuring and Disabling QA Checks
554=================================== 747===================================