summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-qa-checks.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-qa-checks.rst')
-rw-r--r--documentation/ref-manual/ref-qa-checks.rst761
1 files changed, 0 insertions, 761 deletions
diff --git a/documentation/ref-manual/ref-qa-checks.rst b/documentation/ref-manual/ref-qa-checks.rst
deleted file mode 100644
index 54977dcb21..0000000000
--- a/documentation/ref-manual/ref-qa-checks.rst
+++ /dev/null
@@ -1,761 +0,0 @@
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:`insane.bbclass <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 ``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 A runtime dependency exists 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 ``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 ``FILES``.
156
157  
158.. _qa-check-arch:
159
160- ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]``
161
162 By default, the OpenEmbedded build system checks the Executable and
163 Linkable Format (ELF) type, bit size, and endianness of any binaries
164 to ensure they match the target architecture. This test fails if any
165 binaries do not match the type since there would be an
166 incompatibility. The test could indicate that the wrong compiler or
167 compiler options have been used. Sometimes software, like
168 bootloaders, might need to bypass this check. If the file you receive
169 the error for is firmware that is not intended to be executed within
170 the target operating system or is intended to run on a separate
171 processor within the device, you can add "arch" to
172 :term:`INSANE_SKIP` for the package. Another
173 option is to check the :ref:`ref-tasks-compile` log
174 and verify that the compiler options being used are correct.
175
176  
177
178- ``Bit size did not match (<file_bits>, expected <machine_bits>) in <file> [arch]``
179
180 By default, the OpenEmbedded build system checks the Executable and
181 Linkable Format (ELF) type, bit size, and endianness of any binaries
182 to ensure they match the target architecture. This test fails if any
183 binaries do not match the type since there would be an
184 incompatibility. The test could indicate that the wrong compiler or
185 compiler options have been used. Sometimes software, like
186 bootloaders, might need to bypass this check. If the file you receive
187 the error for is firmware that is not intended to be executed within
188 the target operating system or is intended to run on a separate
189 processor within the device, you can add "arch" to
190 :term:`INSANE_SKIP` for the package. Another
191 option is to check the :ref:`ref-tasks-compile` log
192 and verify that the compiler options being used are correct.
193
194  
195
196- ``Endianness did not match (<file_endianness>, expected <machine_endianness>) in <file> [arch]``
197
198 By default, the OpenEmbedded build system checks the Executable and
199 Linkable Format (ELF) type, bit size, and endianness of any binaries
200 to ensure they match the target architecture. This test fails if any
201 binaries do not match the type since there would be an
202 incompatibility. The test could indicate that the wrong compiler or
203 compiler options have been used. Sometimes software, like
204 bootloaders, might need to bypass this check. If the file you receive
205 the error for is firmware that is not intended to be executed within
206 the target operating system or is intended to run on a separate
207 processor within the device, you can add "arch" to
208 :term:`INSANE_SKIP` for the package. Another
209 option is to check the :ref:`ref-tasks-compile` log
210 and verify that the compiler options being used are correct.
211
212  
213.. _qa-check-textrel:
214
215- ``ELF binary '<file>' has relocations in .text [textrel]``
216
217 The specified ELF binary contains relocations in its ``.text``
218 sections. This situation can result in a performance impact at
219 runtime.
220
221 Typically, the way to solve this performance issue is to add "-fPIC"
222 or "-fpic" to the compiler command-line options. For example, given
223 software that reads :term:`CFLAGS` when you build it,
224 you could add the following to your recipe:
225 ::
226
227 CFLAGS_append = " -fPIC "
228
229 For more information on text relocations at runtime, see
230 http://www.akkadia.org/drepper/textrelocs.html.
231
232  
233.. _qa-check-ldflags:
234
235- ``File '<file>' in package '<package>' doesn't have GNU_HASH (didn't pass LDFLAGS?) [ldflags]``
236
237 This indicates that binaries produced when building the recipe have
238 not been linked with the :term:`LDFLAGS` options
239 provided by the build system. Check to be sure that the ``LDFLAGS``
240 variable is being passed to the linker command. A common workaround
241 for this situation is to pass in ``LDFLAGS`` using
242 :term:`TARGET_CC_ARCH` within the recipe as
243 follows:
244 ::
245
246 TARGET_CC_ARCH += "${LDFLAGS}"
247
248  
249.. _qa-check-xorg-driver-abi:
250
251- ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]``
252
253 The specified package contains an Xorg driver, but does not have a
254 corresponding ABI package dependency. The xserver-xorg recipe
255 provides driver ABI names. All drivers should depend on the ABI
256 versions that they have been built against. Driver recipes that
257 include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
258 automatically get these versions. Consequently, you should only need
259 to explicitly add dependencies to binary driver recipes.
260
261  
262.. _qa-check-infodir:
263
264- ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]``
265
266 The ``/usr/share/info/dir`` should not be packaged. Add the following
267 line to your :ref:`ref-tasks-install` task or to your
268 ``do_install_append`` within the recipe as follows:
269 ::
270
271 rm ${D}${infodir}/dir
272  
273
274.. _qa-check-symlink-to-sysroot:
275
276- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
277
278 The specified symlink points into :term:`TMPDIR` on the
279 host. Such symlinks will work on the host. However, they are clearly
280 invalid when running on the target. You should either correct the
281 symlink to use a relative path or remove the symlink.
282
283  
284.. _qa-check-la:
285
286- ``<file> failed sanity test (workdir) in path <path> [la]``
287
288 The specified ``.la`` file contains :term:`TMPDIR`
289 paths. Any ``.la`` file containing these paths is incorrect since
290 ``libtool`` adds the correct sysroot prefix when using the files
291 automatically itself.
292
293  
294.. _qa-check-pkgconfig:
295
296- ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]``
297
298 The specified ``.pc`` file contains
299 :term:`TMPDIR`\ ``/``\ :term:`WORKDIR`
300 paths. Any ``.pc`` file containing these paths is incorrect since
301 ``pkg-config`` itself adds the correct sysroot prefix when the files
302 are accessed.
303
304  
305.. _qa-check-debug-deps:
306
307- ``<packagename> rdepends on <debug_packagename> [debug-deps]``
308
309 A dependency exists between the specified non-dbg package (i.e. a
310 package whose name does not end in ``-dbg``) and a package that is a
311 ``dbg`` package. The ``dbg`` packages contain debug symbols and are
312 brought in using several different methods:
313
314 - Using the ``dbg-pkgs``
315 :term:`IMAGE_FEATURES` value.
316
317 - Using :term:`IMAGE_INSTALL`.
318
319 - As a dependency of another ``dbg`` package that was brought in
320 using one of the above methods.
321
322 The dependency might have been automatically added because the
323 ``dbg`` package erroneously contains files that it should not contain
324 (e.g. a non-symlink ``.so`` file) or it might have been added
325 manually (e.g. by adding to :term:`RDEPENDS`).
326
327  
328.. _qa-check-dev-deps:
329
330- ``<packagename> rdepends on <dev_packagename> [dev-deps]``
331
332 A dependency exists between the specified non-dev package (a package
333 whose name does not end in ``-dev``) and a package that is a ``dev``
334 package. The ``dev`` packages contain development headers and are
335 usually brought in using several different methods:
336
337 - Using the ``dev-pkgs``
338 :term:`IMAGE_FEATURES` value.
339
340 - Using :term:`IMAGE_INSTALL`.
341
342 - As a dependency of another ``dev`` package that was brought in
343 using one of the above methods.
344
345 The dependency might have been automatically added (because the
346 ``dev`` package erroneously contains files that it should not have
347 (e.g. a non-symlink ``.so`` file) or it might have been added
348 manually (e.g. by adding to :term:`RDEPENDS`).
349
350  
351.. _qa-check-dep-cmp:
352
353- ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
354
355 If you are adding a versioned dependency relationship to one of the
356 dependency variables (:term:`RDEPENDS`,
357 :term:`RRECOMMENDS`,
358 :term:`RSUGGESTS`,
359 :term:`RPROVIDES`,
360 :term:`RREPLACES`, or
361 :term:`RCONFLICTS`), you must only use the named
362 comparison operators. Change the versioned dependency values you are
363 adding to match those listed in the message.
364
365  
366.. _qa-check-compile-host-path:
367
368- ``<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]``
369
370 The log for the :ref:`ref-tasks-compile` task
371 indicates that paths on the host were searched for files, which is
372 not appropriate when cross-compiling. Look for "is unsafe for
373 cross-compilation" or "CROSS COMPILE Badness" in the specified log
374 file.
375
376  
377.. _qa-check-install-host-path:
378
379- ``<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]``
380
381 The log for the :ref:`ref-tasks-install` task
382 indicates that paths on the host were searched for files, which is
383 not appropriate when cross-compiling. Look for "is unsafe for
384 cross-compilation" or "CROSS COMPILE Badness" in the specified log
385 file.
386
387  
388.. _qa-check-configure-unsafe:
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. [configure-unsafe]``
391
392 The log for the :ref:`ref-tasks-configure` task
393 indicates that paths on the host were searched for files, which is
394 not appropriate when cross-compiling. Look for "is unsafe for
395 cross-compilation" or "CROSS COMPILE Badness" in the specified log
396 file.
397
398  
399.. _qa-check-pkgname:
400
401- ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]``
402
403 The convention within the OpenEmbedded build system (sometimes
404 enforced by the package manager itself) is to require that package
405 names are all lower case and to allow a restricted set of characters.
406 If your recipe name does not match this, or you add packages to
407 :term:`PACKAGES` that do not conform to the
408 convention, then you will receive this error. Rename your recipe. Or,
409 if you have added a non-conforming package name to ``PACKAGES``,
410 change the package name appropriately.
411
412  
413.. _qa-check-unknown-configure-option:
414
415- ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]``
416
417 The configure script is reporting that the specified options are
418 unrecognized. This situation could be because the options were
419 previously valid but have been removed from the configure script. Or,
420 there was a mistake when the options were added and there is another
421 option that should be used instead. If you are unsure, consult the
422 upstream build documentation, the ``./configure --help`` output, and
423 the upstream change log or release notes. Once you have worked out
424 what the appropriate change is, you can update
425 :term:`EXTRA_OECONF`,
426 :term:`PACKAGECONFIG_CONFARGS`, or the
427 individual :term:`PACKAGECONFIG` option values
428 accordingly.
429
430  
431.. _qa-check-pn-overrides:
432
433- ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]``
434
435 The specified recipe has a name (:term:`PN`) value that
436 appears in :term:`OVERRIDES`. If a recipe is named
437 such that its ``PN`` value matches something already in ``OVERRIDES``
438 (e.g. ``PN`` happens to be the same as :term:`MACHINE`
439 or :term:`DISTRO`), it can have unexpected
440 consequences. For example, assignments such as
441 ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
442 Rename your recipe (or if ``PN`` is being set explicitly, change the
443 ``PN`` value) so that the conflict does not occur. See
444 :term:`FILES` for additional information.
445
446  
447.. _qa-check-pkgvarcheck:
448
449- ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]``
450
451 Certain variables (:term:`RDEPENDS`,
452 :term:`RRECOMMENDS`,
453 :term:`RSUGGESTS`,
454 :term:`RCONFLICTS`,
455 :term:`RPROVIDES`,
456 :term:`RREPLACES`, :term:`FILES`,
457 ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
458 :term:`ALLOW_EMPTY`) should always be set specific
459 to a package (i.e. they should be set with a package name override
460 such as ``RDEPENDS_${PN} = "value"`` rather than
461 ``RDEPENDS = "value"``). If you receive this error, correct any
462 assignments to these variables within your recipe.
463
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
473.. _qa-check-already-stripped:
474
475- ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]``
476
477 Produced binaries have already been stripped prior to the build
478 system extracting debug symbols. It is common for upstream software
479 projects to default to stripping debug symbols for output binaries.
480 In order for debugging to work on the target using ``-dbg`` packages,
481 this stripping must be disabled.
482
483 Depending on the build system used by the software being built,
484 disabling this stripping could be as easy as specifying an additional
485 configure option. If not, disabling stripping might involve patching
486 the build scripts. In the latter case, look for references to "strip"
487 or "STRIP", or the "-s" or "-S" command-line options being specified
488 on the linker command line (possibly through the compiler command
489 line if preceded with "-Wl,").
490
491 .. note::
492
493 Disabling stripping here does not mean that the final packaged
494 binaries will be unstripped. Once the OpenEmbedded build system
495 splits out debug symbols to the ``-dbg`` package, it will then
496 strip the symbols from the binaries.
497
498  
499.. _qa-check-packages-list:
500
501- ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]``
502
503 Package names must appear only once in the
504 :term:`PACKAGES` variable. You might receive this
505 error if you are attempting to add a package to ``PACKAGES`` that is
506 already in the variable's value.
507
508  
509.. _qa-check-files-invalid:
510
511- ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]``
512
513 The string "//" is invalid in a Unix path. Correct all occurrences
514 where this string appears in a :term:`FILES` variable so
515 that there is only a single "/".
516
517  
518.. _qa-check-installed-vs-shipped:
519
520- ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]``
521
522 Files have been installed within the
523 :ref:`ref-tasks-install` task but have not been
524 included in any package by way of the :term:`FILES`
525 variable. Files that do not appear in any package cannot be present
526 in an image later on in the build process. You need to do one of the
527 following:
528
529 - Add the files to ``FILES`` for the package you want them to appear
530 in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main
531 package).
532
533 - Delete the files at the end of the ``do_install`` task if the
534 files are not needed in any package.
535
536  
537
538- ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later``
539
540 This message means that both ``<oldpackage>`` and ``<newpackage>``
541 provide the specified shared library. You can expect this message
542 when a recipe has been renamed. However, if that is not the case, the
543 message might indicate that a private version of a library is being
544 erroneously picked up as the provider for a common library. If that
545 is the case, you should add the library's ``.so`` file name to
546 :term:`PRIVATE_LIBS` in the recipe that provides
547 the private version of the library.
548
549
550.. _qa-check-unlisted-pkg-lics:
551
552- ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
553
554 The :term:`LICENSE` of the recipe should be a superset
555 of all the licenses of all packages produced by this recipe. In other
556 words, any license in ``LICENSE_*`` should also appear in
557 :term:`LICENSE`.
558
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
745
746Configuring and Disabling QA Checks
747===================================
748
749You can configure the QA checks globally so that specific check failures
750either raise a warning or an error message, using the
751:term:`WARN_QA` and :term:`ERROR_QA`
752variables, respectively. You can also disable checks within a particular
753recipe using :term:`INSANE_SKIP`. For information on
754how to work with the QA checks, see the
755":ref:`insane.bbclass <ref-classes-insane>`" section.
756
757.. note::
758
759 Please keep in mind that the QA checks exist in order to detect real
760 or potential problems in the packaged output. So exercise caution
761 when disabling these checks.
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-12-05 00:15:47 +0000