1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3*****************************
4QA Error and Warning Messages
5*****************************
6
7.. _qa-introduction:
8
9Introduction
10============
11
12When building a recipe, the OpenEmbedded build system performs various
13QA checks on the output to ensure that common issues are detected and
14reported. Sometimes when you create a new recipe to build new software,
15it will build with no problems. When this is not the case, or when you
16have QA issues building any software, it could take a little time to
17resolve them.
18
19While it is tempting to ignore a QA message or even to disable QA
20checks, it is best to try and resolve any reported QA issues. This
21chapter provides a list of the QA messages and brief explanations of the
22issues you could encounter so that you can properly resolve problems.
23
24The next section provides a list of all QA error and warning messages
25based on a default configuration. Each entry provides the message or
26error form along with an explanation.
27
28.. note::
29
30   -  At the end of each message, the name of the associated QA test (as
31      listed in the ":ref:`ref-classes-insane`"
32      section) appears within square brackets.
33
34   -  As mentioned, this list of error and warning messages is for QA
35      checks only. The list does not cover all possible build errors or
36      warnings you could encounter.
37
38   -  Because some QA checks are disabled by default, this list does not
39      include all possible QA check errors and warnings.
40
41.. _qa-errors-and-warnings:
42
43Errors and Warnings
44===================
45
46.. _qa-check-libexec:
47
48-  ``<packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]``
49
50   The specified package contains files in ``/usr/libexec`` when the
51   distro configuration uses a different path for ``<libexecdir>`` By
52   default, ``<libexecdir>`` is ``$prefix/libexec``. However, this
53   default can be changed (e.g. ``${libdir}``).
54
55    
56.. _qa-check-rpaths:
57
58-  ``package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]``
59
60   The specified binary produced by the recipe contains dynamic library
61   load paths (rpaths) that contain build system paths such as
62   :term:`TMPDIR`, which are incorrect for the target and
63   could potentially be a security issue. Check for bad ``-rpath``
64   options being passed to the linker in your
65   :ref:`ref-tasks-compile` log. Depending on the build
66   system used by the software being built, there might be a configure
67   option to disable rpath usage completely within the build of the
68   software.
69
70    
71.. _qa-check-useless-rpaths:
72
73-  ``<packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]``
74
75   The specified binary produced by the recipe contains dynamic library
76   load paths (rpaths) that on a standard system are searched by default
77   by the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths
78   will not cause any breakage, they do waste space and are unnecessary.
79   Depending on the build system used by the software being built, there
80   might be a configure option to disable rpath usage completely within
81   the build of the software.
82
83    
84.. _qa-check-file-rdeps:
85
86-  ``<packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]``
87
88   A file-level dependency has been identified from the specified
89   package on the specified files, but there is no explicit
90   corresponding entry in :term:`RDEPENDS`. If
91   particular files are required at runtime then :term:`RDEPENDS` should be
92   declared in the recipe to ensure the packages providing them are
93   built.
94
95    
96.. _qa-check-build-deps:
97
98-  ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]``
99
100   There is a runtime dependency between the two specified packages, but
101   there is nothing explicit within the recipe to enable the
102   OpenEmbedded build system to ensure that dependency is satisfied.
103   This condition is usually triggered by an
104   :term:`RDEPENDS` value being added at the packaging
105   stage rather than up front, which is usually automatic based on the
106   contents of the package. In most cases, you should change the recipe
107   to add an explicit :term:`RDEPENDS` for the dependency.
108
109    
110.. _qa-check-dev-so:
111
112-  ``non -dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]``
113
114   Symlink ``.so`` files are for development only, and should therefore
115   go into the ``-dev`` package. This situation might occur if you add
116   ``*.so*`` rather than ``*.so.*`` to a non-dev package. Change
117   :term:`FILES` (and possibly
118   :term:`PACKAGES`) such that the specified ``.so``
119   file goes into an appropriate ``-dev`` package.
120
121    
122.. _qa-check-staticdev:
123
124-  ``non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]``
125
126   Static ``.a`` library files should go into a ``-staticdev`` package.
127   Change :term:`FILES` (and possibly
128   :term:`PACKAGES`) such that the specified ``.a`` file
129   goes into an appropriate ``-staticdev`` package.
130
131    
132.. _qa-check-libdir:
133
134-  ``<packagename>: found library in wrong location [libdir]``
135
136   The specified file may have been installed into an incorrect
137   (possibly hardcoded) installation path. For example, this test will
138   catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
139   "lib32". Another example is when recipes install
140   ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". False
141   positives occasionally exist. For these cases add "libdir" to
142   :term:`INSANE_SKIP` for the package.
143
144    
145.. _qa-check-debug-files:
146
147-  ``non debug package contains .debug directory: <packagename> path <path> [debug-files]``
148
149   The specified package contains a ``.debug`` directory, which should
150   not appear in anything but the ``-dbg`` package. This situation might
151   occur if you add a path which contains a ``.debug`` directory and do
152   not explicitly add the ``.debug`` directory to the ``-dbg`` package.
153   If this is the case, add the ``.debug`` directory explicitly to
154   ``FILES:${PN}-dbg``. See :term:`FILES` for additional
155   information on :term:`FILES`.
156
157.. _qa-check-empty-dirs:
158
159-  ``<packagename> installs files in <path>, but it is expected to be empty [empty-dirs]``
160
161   The specified package is installing files into a directory that is
162   normally expected to be empty (such as ``/tmp``). These files may
163   be more appropriately installed to a different location, or
164   perhaps alternatively not installed at all, usually by updating the
165   :ref:`ref-tasks-install` task/function.
166
167.. _qa-check-arch:
168
169-  ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]``
170
171   By default, the OpenEmbedded build system checks the Executable and
172   Linkable Format (ELF) type, bit size, and endianness of any binaries
173   to ensure they match the target architecture. This test fails if any
174   binaries do not match the type since there would be an
175   incompatibility. The test could indicate that the wrong compiler or
176   compiler options have been used. Sometimes software, like
177   bootloaders, might need to bypass this check. If the file you receive
178   the error for is firmware that is not intended to be executed within
179   the target operating system or is intended to run on a separate
180   processor within the device, you can add "arch" to
181   :term:`INSANE_SKIP` for the package. Another
182   option is to check the :ref:`ref-tasks-compile` log
183   and verify that the compiler options being used are correct.
184
185    
186
187-  ``Bit size did not match (<file_bits>, expected <machine_bits>) in <file> [arch]``
188
189   By default, the OpenEmbedded build system checks the Executable and
190   Linkable Format (ELF) type, bit size, and endianness of any binaries
191   to ensure they match the target architecture. This test fails if any
192   binaries do not match the type since there would be an
193   incompatibility. The test could indicate that the wrong compiler or
194   compiler options have been used. Sometimes software, like
195   bootloaders, might need to bypass this check. If the file you receive
196   the error for is firmware that is not intended to be executed within
197   the target operating system or is intended to run on a separate
198   processor within the device, you can add "arch" to
199   :term:`INSANE_SKIP` for the package. Another
200   option is to check the :ref:`ref-tasks-compile` log
201   and verify that the compiler options being used are correct.
202
203    
204
205-  ``Endianness did not match (<file_endianness>, expected <machine_endianness>) in <file> [arch]``
206
207   By default, the OpenEmbedded build system checks the Executable and
208   Linkable Format (ELF) type, bit size, and endianness of any binaries
209   to ensure they match the target architecture. This test fails if any
210   binaries do not match the type since there would be an
211   incompatibility. The test could indicate that the wrong compiler or
212   compiler options have been used. Sometimes software, like
213   bootloaders, might need to bypass this check. If the file you receive
214   the error for is firmware that is not intended to be executed within
215   the target operating system or is intended to run on a separate
216   processor within the device, you can add "arch" to
217   :term:`INSANE_SKIP` for the package. Another
218   option is to check the :ref:`ref-tasks-compile` log
219   and verify that the compiler options being used are correct.
220
221    
222.. _qa-check-textrel:
223
224-  ``ELF binary '<file>' has relocations in .text [textrel]``
225
226   The specified ELF binary contains relocations in its ``.text``
227   sections. This situation can result in a performance impact at
228   runtime.
229
230   Typically, the way to solve this performance issue is to add "-fPIC"
231   or "-fpic" to the compiler command-line options. For example, given
232   software that reads :term:`CFLAGS` when you build it,
233   you could add the following to your recipe::
234
235      CFLAGS:append = " -fPIC "
236
237   For more information on text relocations at runtime, see
238   https://www.akkadia.org/drepper/textrelocs.html.
239
240    
241.. _qa-check-ldflags:
242
243-  ``File '<file>' in package '<package>' doesn't have GNU_HASH (didn't pass LDFLAGS?) [ldflags]``
244
245   This indicates that binaries produced when building the recipe have
246   not been linked with the :term:`LDFLAGS` options
247   provided by the build system. Check to be sure that the :term:`LDFLAGS`
248   variable is being passed to the linker command. A common workaround
249   for this situation is to pass in :term:`LDFLAGS` using
250   :term:`TARGET_CC_ARCH` within the recipe as
251   follows::
252
253      TARGET_CC_ARCH += "${LDFLAGS}"
254
255    
256.. _qa-check-xorg-driver-abi:
257
258-  ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]``
259
260   The specified package contains an Xorg driver, but does not have a
261   corresponding ABI package dependency. The xserver-xorg recipe
262   provides driver ABI names. All drivers should depend on the ABI
263   versions that they have been built against. Driver recipes that
264   include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
265   automatically get these versions. Consequently, you should only need
266   to explicitly add dependencies to binary driver recipes.
267
268    
269.. _qa-check-infodir:
270
271-  ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]``
272
273   The ``/usr/share/info/dir`` should not be packaged. Add the following
274   line to your :ref:`ref-tasks-install` task or to your
275   ``do_install:append`` within the recipe as follows::
276
277      rm ${D}${infodir}/dir
278   
279
280.. _qa-check-symlink-to-sysroot:
281
282-  ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
283
284   The specified symlink points into :term:`TMPDIR` on the
285   host. Such symlinks will work on the host. However, they are clearly
286   invalid when running on the target. You should either correct the
287   symlink to use a relative path or remove the symlink.
288
289    
290.. _qa-check-la:
291
292-  ``<file> failed sanity test (workdir) in path <path> [la]``
293
294   The specified ``.la`` file contains :term:`TMPDIR`
295   paths. Any ``.la`` file containing these paths is incorrect since
296   ``libtool`` adds the correct sysroot prefix when using the files
297   automatically itself.
298
299    
300.. _qa-check-pkgconfig:
301
302-  ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]``
303
304   The specified ``.pc`` file contains
305   :term:`TMPDIR`\ ``/``\ :term:`WORKDIR`
306   paths. Any ``.pc`` file containing these paths is incorrect since
307   ``pkg-config`` itself adds the correct sysroot prefix when the files
308   are accessed.
309
310    
311.. _qa-check-debug-deps:
312
313-  ``<packagename> rdepends on <debug_packagename> [debug-deps]``
314
315   There is a dependency between the specified non-dbg package (i.e. a
316   package whose name does not end in ``-dbg``) and a package that is a
317   ``dbg`` package. The ``dbg`` packages contain debug symbols and are
318   brought in using several different methods:
319
320   -  Using the ``dbg-pkgs``
321      :term:`IMAGE_FEATURES` value.
322
323   -  Using :term:`IMAGE_INSTALL`.
324
325   -  As a dependency of another ``dbg`` package that was brought in
326      using one of the above methods.
327
328   The dependency might have been automatically added because the
329   ``dbg`` package erroneously contains files that it should not contain
330   (e.g. a non-symlink ``.so`` file) or it might have been added
331   manually (e.g. by adding to :term:`RDEPENDS`).
332
333    
334.. _qa-check-dev-deps:
335
336-  ``<packagename> rdepends on <dev_packagename> [dev-deps]``
337
338   There is a dependency between the specified non-dev package (a package
339   whose name does not end in ``-dev``) and a package that is a ``dev``
340   package. The ``dev`` packages contain development headers and are
341   usually brought in using several different methods:
342
343   -  Using the ``dev-pkgs``
344      :term:`IMAGE_FEATURES` value.
345
346   -  Using :term:`IMAGE_INSTALL`.
347
348   -  As a dependency of another ``dev`` package that was brought in
349      using one of the above methods.
350
351   The dependency might have been automatically added (because the
352   ``dev`` package erroneously contains files that it should not have
353   (e.g. a non-symlink ``.so`` file) or it might have been added
354   manually (e.g. by adding to :term:`RDEPENDS`).
355
356    
357.. _qa-check-dep-cmp:
358
359-  ``<var>:<packagename> is invalid: <comparison> (<value>)   only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
360
361   If you are adding a versioned dependency relationship to one of the
362   dependency variables (:term:`RDEPENDS`,
363   :term:`RRECOMMENDS`,
364   :term:`RSUGGESTS`,
365   :term:`RPROVIDES`,
366   :term:`RREPLACES`, or
367   :term:`RCONFLICTS`), you must only use the named
368   comparison operators. Change the versioned dependency values you are
369   adding to match those listed in the message.
370
371    
372.. _qa-check-compile-host-path:
373
374-  ``<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]``
375
376   The log for the :ref:`ref-tasks-compile` task
377   indicates that paths on the host were searched for files, which is
378   not appropriate when cross-compiling. Look for "is unsafe for
379   cross-compilation" or "CROSS COMPILE Badness" in the specified log
380   file.
381
382    
383.. _qa-check-install-host-path:
384
385-  ``<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]``
386
387   The log for the :ref:`ref-tasks-install` task
388   indicates that paths on the host were searched for files, which is
389   not appropriate when cross-compiling. Look for "is unsafe for
390   cross-compilation" or "CROSS COMPILE Badness" in the specified log
391   file.
392
393    
394.. _qa-check-configure-unsafe:
395
396-  ``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]``
397
398   The log for the :ref:`ref-tasks-configure` task
399   indicates that paths on the host were searched for files, which is
400   not appropriate when cross-compiling. Look for "is unsafe for
401   cross-compilation" or "CROSS COMPILE Badness" in the specified log
402   file.
403
404    
405.. _qa-check-pkgname:
406
407-  ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]``
408
409   The convention within the OpenEmbedded build system (sometimes
410   enforced by the package manager itself) is to require that package
411   names are all lower case and to allow a restricted set of characters.
412   If your recipe name does not match this, or you add packages to
413   :term:`PACKAGES` that do not conform to the
414   convention, then you will receive this error. Rename your recipe. Or,
415   if you have added a non-conforming package name to :term:`PACKAGES`,
416   change the package name appropriately.
417
418    
419.. _qa-check-unknown-configure-option:
420
421-  ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]``
422
423   The configure script is reporting that the specified options are
424   unrecognized. This situation could be because the options were
425   previously valid but have been removed from the configure script. Or,
426   there was a mistake when the options were added and there is another
427   option that should be used instead. If you are unsure, consult the
428   upstream build documentation, the ``./configure --help`` output, and
429   the upstream change log or release notes. Once you have worked out
430   what the appropriate change is, you can update
431   :term:`EXTRA_OECONF`,
432   :term:`PACKAGECONFIG_CONFARGS`, or the
433   individual :term:`PACKAGECONFIG` option values
434   accordingly.
435
436    
437.. _qa-check-pn-overrides:
438
439-  ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]``
440
441   The specified recipe has a name (:term:`PN`) value that
442   appears in :term:`OVERRIDES`. If a recipe is named
443   such that its :term:`PN` value matches something already in :term:`OVERRIDES`
444   (e.g. :term:`PN` happens to be the same as :term:`MACHINE`
445   or :term:`DISTRO`), it can have unexpected
446   consequences. For example, assignments such as
447   ``FILES:${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
448   Rename your recipe (or if :term:`PN` is being set explicitly, change the
449   :term:`PN` value) so that the conflict does not occur. See
450   :term:`FILES` for additional information.
451
452    
453.. _qa-check-pkgvarcheck:
454
455-  ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]``
456
457   Certain variables (:term:`RDEPENDS`,
458   :term:`RRECOMMENDS`,
459   :term:`RSUGGESTS`,
460   :term:`RCONFLICTS`,
461   :term:`RPROVIDES`,
462   :term:`RREPLACES`, :term:`FILES`,
463   ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
464   :term:`ALLOW_EMPTY`) should always be set specific
465   to a package (i.e. they should be set with a package name override
466   such as ``RDEPENDS:${PN} = "value"`` rather than
467   ``RDEPENDS = "value"``). If you receive this error, correct any
468   assignments to these variables within your recipe.
469
470
471- ``recipe uses DEPENDS:${PN}, should use DEPENDS [pkgvarcheck]``
472
473   This check looks for instances of setting ``DEPENDS:${PN}``
474   which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus
475   it is not correct to specify it for a particular package, nor will such
476   an assignment actually work.) Set :term:`DEPENDS` instead.
477
478
479.. _qa-check-already-stripped:
480
481-  ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]``
482
483   Produced binaries have already been stripped prior to the build
484   system extracting debug symbols. It is common for upstream software
485   projects to default to stripping debug symbols for output binaries.
486   In order for debugging to work on the target using ``-dbg`` packages,
487   this stripping must be disabled.
488
489   Depending on the build system used by the software being built,
490   disabling this stripping could be as easy as specifying an additional
491   configure option. If not, disabling stripping might involve patching
492   the build scripts. In the latter case, look for references to "strip"
493   or "STRIP", or the "-s" or "-S" command-line options being specified
494   on the linker command line (possibly through the compiler command
495   line if preceded with "-Wl,").
496
497   .. note::
498
499      Disabling stripping here does not mean that the final packaged
500      binaries will be unstripped. Once the OpenEmbedded build system
501      splits out debug symbols to the ``-dbg`` package, it will then
502      strip the symbols from the binaries.
503
504    
505.. _qa-check-packages-list:
506
507-  ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]``
508
509   Package names must appear only once in the
510   :term:`PACKAGES` variable. You might receive this
511   error if you are attempting to add a package to :term:`PACKAGES` that is
512   already in the variable's value.
513
514    
515.. _qa-check-files-invalid:
516
517-  ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]``
518
519   The string "//" is invalid in a Unix path. Correct all occurrences
520   where this string appears in a :term:`FILES` variable so
521   that there is only a single "/".
522
523    
524.. _qa-check-installed-vs-shipped:
525
526-  ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]``
527
528   Files have been installed within the
529   :ref:`ref-tasks-install` task but have not been
530   included in any package by way of the :term:`FILES`
531   variable. Files that do not appear in any package cannot be present
532   in an image later on in the build process. You need to do one of the
533   following:
534
535   -  Add the files to :term:`FILES` for the package you want them to appear
536      in (e.g. ``FILES:${``\ :term:`PN`\ ``}`` for the main
537      package).
538
539   -  Delete the files at the end of the :ref:`ref-tasks-install` task if the
540      files are not needed in any package.
541
542    
543
544-  ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later``
545
546   This message means that both ``<oldpackage>`` and ``<newpackage>``
547   provide the specified shared library. You can expect this message
548   when a recipe has been renamed. However, if that is not the case, the
549   message might indicate that a private version of a library is being
550   erroneously picked up as the provider for a common library. If that
551   is the case, you should add the library's ``.so`` filename to
552   :term:`PRIVATE_LIBS` in the recipe that provides
553   the private version of the library.
554
555
556.. _qa-check-unlisted-pkg-lics:
557
558-  ``LICENSE:<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
559
560   The :term:`LICENSE` of the recipe should be a superset
561   of all the licenses of all packages produced by this recipe. In other
562   words, any license in ``LICENSE:*`` should also appear in
563   :term:`LICENSE`.
564
565
566.. _qa-check-configure-gettext:
567
568-  ``AM_GNU_GETTEXT used but no inherit gettext [configure-gettext]``
569
570    If a recipe is building something that uses automake and the automake
571    files contain an ``AM_GNU_GETTEXT`` directive then this check will fail
572    if there is no ``inherit gettext`` statement in the recipe to ensure
573    that gettext is available during the build. Add ``inherit gettext`` to
574    remove the warning.
575
576
577.. _qa-check-mime:
578
579- ``package contains mime types but does not inherit mime: <packagename> path '<file>' [mime]``
580
581   The specified package contains mime type files (``.xml`` files in
582   ``${datadir}/mime/packages``) and yet does not inherit the
583   :ref:`ref-classes-mime` class which will ensure that these get
584   properly installed. Either add ``inherit mime`` to the recipe or remove the
585   files at the :ref:`ref-tasks-install` step if they are not needed.
586
587
588.. _qa-check-mime-xdg:
589
590- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]``
591
592    The specified package contains a .desktop file with a 'MimeType' key
593    present, but does not inherit the :ref:`ref-classes-mime-xdg`
594    class that is required in order for that to be activated. Either add
595    ``inherit mime`` to the recipe or remove the files at the
596    :ref:`ref-tasks-install` step if they are not needed.
597
598
599.. _qa-check-src-uri-bad:
600
601- ``<recipename>: SRC_URI uses unstable GitHub archives [src-uri-bad]``
602
603    GitHub provides "archive" tarballs, however these can be re-generated
604    on the fly and thus the file's signature will not necessarily match that
605    in the :term:`SRC_URI` checksums in future leading to build failures. It is
606    recommended that you use an official release tarball or switch to
607    pulling the corresponding revision in the actual git repository instead.
608
609
610- ``SRC_URI uses PN not BPN [src-uri-bad]``
611
612    If some part of :term:`SRC_URI` needs to reference the recipe name, it should do
613    so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change
614    for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND`
615    or multilib are being used. This check will fail if a reference to ``${PN}``
616    is found within the :term:`SRC_URI` value --- change it to ``${BPN}`` instead.
617
618
619.. _qa-check-unhandled-features-check:
620
621- ``<recipename>: recipe doesn't inherit features_check [unhandled-features-check]``
622
623    This check ensures that if one of the variables that the
624    :ref:`ref-classes-features_check` class supports (e.g.
625    :term:`REQUIRED_DISTRO_FEATURES`) is used, then the recipe
626    inherits :ref:`ref-classes-features_check` in order for
627    the requirement to actually work. If you are seeing this message, either
628    add ``inherit features_check`` to your recipe or remove the reference to
629    the variable if it is not needed.
630
631
632.. _qa-check-missing-update-alternatives:
633
634- ``<recipename>: recipe defines ALTERNATIVE:<packagename> but doesn't inherit update-alternatives. This might fail during do_rootfs later! [missing-update-alternatives]``
635
636    This check ensures that if a recipe sets the :term:`ALTERNATIVE` variable that the
637    recipe also inherits :ref:`ref-classes-update-alternatives` such
638    that the alternative will be correctly set up. If you are seeing this message, either
639    add ``inherit update-alternatives`` to your recipe or remove the reference to the variable
640    if it is not needed.
641
642
643.. _qa-check-shebang-size:
644
645- ``<packagename>: <file> maximum shebang size exceeded, the maximum size is 128. [shebang-size]``
646
647    This check ensures that the shebang line (``#!`` in the first line) for a script
648    is not longer than 128 characters, which can cause an error at runtime depending
649    on the operating system. If you are seeing this message then the specified script
650    may need to be patched to have a shorter in order to avoid runtime problems.
651
652
653.. _qa-check-perllocalpod:
654
655- ``<packagename> contains perllocal.pod (<files>), should not be installed [perllocalpod]``
656
657    ``perllocal.pod`` is an index file of locally installed modules and so shouldn't be
658    installed by any distribution packages. The :ref:`ref-classes-cpan` class
659    already sets ``NO_PERLLOCAL`` to stop this file being generated by most Perl recipes,
660    but if a recipe is using ``MakeMaker`` directly then they might not be doing this
661    correctly. This check ensures that perllocal.pod is not in any package in order to
662    avoid multiple packages shipping this file and thus their packages conflicting
663    if installed together.
664
665
666.. _qa-check-usrmerge:
667
668- ``<packagename> package is not obeying usrmerge distro feature. /<path> should be relocated to /usr. [usrmerge]``
669
670    If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package
671    installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this
672    message, it indicates that the :ref:`ref-tasks-install` step (or perhaps the build process that
673    :ref:`ref-tasks-install` is calling into, e.g. ``make install`` is using hardcoded paths instead
674    of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be
675    changed so that it does.
676
677
678.. _qa-check-patch-fuzz:
679
680- ``Fuzz detected: <patch output> [patch-fuzz]``
681
682    This check looks for evidence of "fuzz" when applying patches within the :ref:`ref-tasks-patch`
683    task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context
684    lines in order to apply the patch. Consider this example:
685
686    Patch to be applied::
687
688        --- filename
689        +++ filename
690         context line 1
691         context line 2
692         context line 3
693        +newly added line
694         context line 4
695         context line 5
696         context line 6
697
698    Original source code::
699
700        different context line 1
701        different context line 2
702        context line 3
703        context line 4
704        different context line 5
705        different context line 6
706
707    Outcome (after applying patch with fuzz)::
708
709        different context line 1
710        different context line 2
711        context line 3
712        newly added line
713        context line 4
714        different context line 5
715        different context line 6
716
717    Chances are, the newly added line was actually added in a completely
718    wrong location, or it was already in the original source and was added
719    for the second time. This is especially possible if the context line 3
720    and 4 are blank or have only generic things in them, such as ``#endif`` or ``}``.
721    Depending on the patched code, it is entirely possible for an incorrectly
722    patched file to still compile without errors.
723
724    *How to eliminate patch fuzz warnings*
725
726    Use the ``devtool`` command as explained by the warning. First, unpack the
727    source into devtool workspace::
728
729            devtool modify <recipe>
730
731    This will apply all of the patches, and create new commits out of them in
732    the workspace --- with the patch context updated.
733
734    Then, replace the patches in the recipe layer::
735
736            devtool finish --force-patch-refresh <recipe> <layer_path>
737
738    The patch updates then need be reviewed (preferably with a side-by-side diff
739    tool) to ensure they are indeed doing the right thing i.e.:
740
741    #. they are applied in the correct location within the file;
742    #. they do not introduce duplicate lines, or otherwise do things that
743       are no longer necessary.
744
745    To confirm these things, you can also review the patched source code in
746    devtool's workspace, typically in ``<build_dir>/workspace/sources/<recipe>/``
747
748    Once the review is done, you can create and publish a layer commit with
749    the patch updates that modify the context. Devtool may also refresh
750    other things in the patches, those can be discarded.
751
752
753.. _qa-check-patch-status:
754
755- ``Missing Upstream-Status in patch <patchfile> Please add according to <url> [patch-status-core/patch-status-noncore]``
756
757    The ``Upstream-Status`` value is missing in the specified patch file's header.
758    This value is intended to track whether or not the patch has been sent
759    upstream, whether or not it has been merged, etc.
760
761    There are two options for this same check - ``patch-status-core`` (for
762    recipes in OE-Core) and ``patch-status-noncore`` (for recipes in any other
763    layer).
764
765    For more information, see the
766    ":ref:`contributor-guide/recipe-style-guide:patch upstream status`"
767    section in the Yocto Project and OpenEmbedded Contributor Guide.
768
769- ``Malformed Upstream-Status in patch <patchfile> Please correct according to <url> [patch-status-core/patch-status-noncore]``
770
771    The ``Upstream-Status`` value in the specified patch file's header is invalid -
772    it must be a specific format. See the "Missing Upstream-Status" entry above
773    for more information.
774
775
776.. _qa-check-buildpaths:
777
778- ``File <filename> in package <packagename> contains reference to TMPDIR [buildpaths]``
779
780    This check ensures that build system paths (including :term:`TMPDIR`) do not
781    appear in output files, which not only leaks build system configuration into
782    the target, but also hinders binary reproducibility as the output will change
783    if the build system configuration changes.
784
785    Typically these paths will enter the output through some mechanism in the
786    configuration or compilation of the software being built by the recipe. To
787    resolve this issue you will need to determine how the detected path is
788    entering the output. Sometimes it may require adjusting scripts or code to
789    use a relative path rather than an absolute one, or to pick up the path from
790    runtime configuration or environment variables.
791
792.. _qa-check-unimplemented-ptest:
793
794- ``<tool> tests detected [unimplemented-ptest]``
795
796    This check will detect if the source of the package contains some
797    upstream-provided tests and, if so, that ptests are implemented for this
798    recipe.  See the ":ref:`dev-manual/packages:testing packages with ptest`"
799    section in the Yocto Project Development Tasks Manual. See also the
800    ":ref:`ref-classes-ptest`" section.
801
802.. _qa-check-virtual-slash:
803
804- ``<variable> is set to <value> but the substring 'virtual/' holds no meaning in this context. It only works for build time dependencies, not runtime ones. It is suggested to use 'VIRTUAL-RUNTIME_' variables instead.``
805
806    ``virtual/`` is a convention intended for use in the build context
807    (i.e. :term:`PROVIDES` and :term:`DEPENDS`) rather than the runtime
808    context (i.e. :term:`RPROVIDES` and :term:`RDEPENDS`). Use
809    :term:`VIRTUAL-RUNTIME` variables instead for the latter.
810
811
812Configuring and Disabling QA Checks
813===================================
814
815You can configure the QA checks globally so that specific check failures
816either raise a warning or an error message, using the
817:term:`WARN_QA` and :term:`ERROR_QA`
818variables, respectively. You can also disable checks within a particular
819recipe using :term:`INSANE_SKIP`. For information on
820how to work with the QA checks, see the
821":ref:`ref-classes-insane`" section.
822
823.. note::
824
825   Please keep in mind that the QA checks are meant to detect real
826   or potential problems in the packaged output. So exercise caution
827   when disabling these checks.
828