blob: 0ef203c70fa584926233da2216c28a0ab497ca70 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
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
Andrew Geissler6ce62a22020-11-30 19:58:47 -060046.. _qa-check-libexec:
47
Andrew Geisslerc9f78652020-09-18 14:11:35 -050048- ``<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  
Andrew Geissler6ce62a22020-11-30 19:58:47 -060056.. _qa-check-rpaths:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050057
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  
Andrew Geissler6ce62a22020-11-30 19:58:47 -060071.. _qa-check-useless-rpaths:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050072
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  
Andrew Geissler6ce62a22020-11-30 19:58:47 -060084.. _qa-check-file-rdeps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050085
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
Andrew Geissler09036742021-06-25 14:25:14 -050091 particular files are required at runtime then :term:`RDEPENDS` should be
Andrew Geisslerc9f78652020-09-18 14:11:35 -050092 declared in the recipe to ensure the packages providing them are
93 built.
94
95  
Andrew Geissler6ce62a22020-11-30 19:58:47 -060096.. _qa-check-build-deps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050097
98- ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]``
99
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700100 There is a runtime dependency between the two specified packages, but
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500101 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
Andrew Geissler09036742021-06-25 14:25:14 -0500107 to add an explicit :term:`RDEPENDS` for the dependency.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500108
109  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600110.. _qa-check-dev-so:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500111
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  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600122.. _qa-check-staticdev:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500123
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  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600132.. _qa-check-libdir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500133
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  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600145.. _qa-check-debug-files:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500146
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
Andrew Geissler09036742021-06-25 14:25:14 -0500155 information on :term:`FILES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500156
157  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600158.. _qa-check-arch:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500159
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600160- ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500161
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
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600178- ``Bit size did not match (<file_bits>, expected <machine_bits>) in <file> [arch]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500179
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
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600196- ``Endianness did not match (<file_endianness>, expected <machine_endianness>) in <file> [arch]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500197
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  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600213.. _qa-check-textrel:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500214
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,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500224 you could add the following to your recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500225
226 CFLAGS_append = " -fPIC "
227
228 For more information on text relocations at runtime, see
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600229 https://www.akkadia.org/drepper/textrelocs.html.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500230
231  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600232.. _qa-check-ldflags:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500233
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600234- ``File '<file>' in package '<package>' doesn't have GNU_HASH (didn't pass LDFLAGS?) [ldflags]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500235
236 This indicates that binaries produced when building the recipe have
237 not been linked with the :term:`LDFLAGS` options
Andrew Geissler09036742021-06-25 14:25:14 -0500238 provided by the build system. Check to be sure that the :term:`LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500239 variable is being passed to the linker command. A common workaround
Andrew Geissler09036742021-06-25 14:25:14 -0500240 for this situation is to pass in :term:`LDFLAGS` using
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500241 :term:`TARGET_CC_ARCH` within the recipe as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500242 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500243
244 TARGET_CC_ARCH += "${LDFLAGS}"
245
246  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600247.. _qa-check-xorg-driver-abi:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500248
249- ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]``
250
251 The specified package contains an Xorg driver, but does not have a
252 corresponding ABI package dependency. The xserver-xorg recipe
253 provides driver ABI names. All drivers should depend on the ABI
254 versions that they have been built against. Driver recipes that
255 include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
256 automatically get these versions. Consequently, you should only need
257 to explicitly add dependencies to binary driver recipes.
258
259  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600260.. _qa-check-infodir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500261
262- ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]``
263
264 The ``/usr/share/info/dir`` should not be packaged. Add the following
265 line to your :ref:`ref-tasks-install` task or to your
Andrew Geisslerc926e172021-05-07 16:11:35 -0500266 ``do_install_append`` within the recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500267
268 rm ${D}${infodir}/dir
269  
270
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600271.. _qa-check-symlink-to-sysroot:
272
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500273- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
274
275 The specified symlink points into :term:`TMPDIR` on the
276 host. Such symlinks will work on the host. However, they are clearly
277 invalid when running on the target. You should either correct the
278 symlink to use a relative path or remove the symlink.
279
280  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600281.. _qa-check-la:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282
283- ``<file> failed sanity test (workdir) in path <path> [la]``
284
285 The specified ``.la`` file contains :term:`TMPDIR`
286 paths. Any ``.la`` file containing these paths is incorrect since
287 ``libtool`` adds the correct sysroot prefix when using the files
288 automatically itself.
289
290  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600291.. _qa-check-pkgconfig:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500292
293- ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]``
294
295 The specified ``.pc`` file contains
296 :term:`TMPDIR`\ ``/``\ :term:`WORKDIR`
297 paths. Any ``.pc`` file containing these paths is incorrect since
298 ``pkg-config`` itself adds the correct sysroot prefix when the files
299 are accessed.
300
301  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600302.. _qa-check-debug-deps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500303
304- ``<packagename> rdepends on <debug_packagename> [debug-deps]``
305
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700306 There is a dependency between the specified non-dbg package (i.e. a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500307 package whose name does not end in ``-dbg``) and a package that is a
308 ``dbg`` package. The ``dbg`` packages contain debug symbols and are
309 brought in using several different methods:
310
311 - Using the ``dbg-pkgs``
312 :term:`IMAGE_FEATURES` value.
313
314 - Using :term:`IMAGE_INSTALL`.
315
316 - As a dependency of another ``dbg`` package that was brought in
317 using one of the above methods.
318
319 The dependency might have been automatically added because the
320 ``dbg`` package erroneously contains files that it should not contain
321 (e.g. a non-symlink ``.so`` file) or it might have been added
322 manually (e.g. by adding to :term:`RDEPENDS`).
323
324  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600325.. _qa-check-dev-deps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500326
327- ``<packagename> rdepends on <dev_packagename> [dev-deps]``
328
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700329 There is a dependency between the specified non-dev package (a package
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500330 whose name does not end in ``-dev``) and a package that is a ``dev``
331 package. The ``dev`` packages contain development headers and are
332 usually brought in using several different methods:
333
334 - Using the ``dev-pkgs``
335 :term:`IMAGE_FEATURES` value.
336
337 - Using :term:`IMAGE_INSTALL`.
338
339 - As a dependency of another ``dev`` package that was brought in
340 using one of the above methods.
341
342 The dependency might have been automatically added (because the
343 ``dev`` package erroneously contains files that it should not have
344 (e.g. a non-symlink ``.so`` file) or it might have been added
345 manually (e.g. by adding to :term:`RDEPENDS`).
346
347  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600348.. _qa-check-dep-cmp:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500349
350- ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
351
352 If you are adding a versioned dependency relationship to one of the
353 dependency variables (:term:`RDEPENDS`,
354 :term:`RRECOMMENDS`,
355 :term:`RSUGGESTS`,
356 :term:`RPROVIDES`,
357 :term:`RREPLACES`, or
358 :term:`RCONFLICTS`), you must only use the named
359 comparison operators. Change the versioned dependency values you are
360 adding to match those listed in the message.
361
362  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600363.. _qa-check-compile-host-path:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500364
365- ``<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]``
366
367 The log for the :ref:`ref-tasks-compile` task
368 indicates that paths on the host were searched for files, which is
369 not appropriate when cross-compiling. Look for "is unsafe for
370 cross-compilation" or "CROSS COMPILE Badness" in the specified log
371 file.
372
373  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600374.. _qa-check-install-host-path:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500375
376- ``<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]``
377
378 The log for the :ref:`ref-tasks-install` task
379 indicates that paths on the host were searched for files, which is
380 not appropriate when cross-compiling. Look for "is unsafe for
381 cross-compilation" or "CROSS COMPILE Badness" in the specified log
382 file.
383
384  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600385.. _qa-check-configure-unsafe:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500386
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600387- ``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]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388
389 The log for the :ref:`ref-tasks-configure` task
390 indicates that paths on the host were searched for files, which is
391 not appropriate when cross-compiling. Look for "is unsafe for
392 cross-compilation" or "CROSS COMPILE Badness" in the specified log
393 file.
394
395  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600396.. _qa-check-pkgname:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500397
398- ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]``
399
400 The convention within the OpenEmbedded build system (sometimes
401 enforced by the package manager itself) is to require that package
402 names are all lower case and to allow a restricted set of characters.
403 If your recipe name does not match this, or you add packages to
404 :term:`PACKAGES` that do not conform to the
405 convention, then you will receive this error. Rename your recipe. Or,
Andrew Geissler09036742021-06-25 14:25:14 -0500406 if you have added a non-conforming package name to :term:`PACKAGES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500407 change the package name appropriately.
408
409  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600410.. _qa-check-unknown-configure-option:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500411
412- ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]``
413
414 The configure script is reporting that the specified options are
415 unrecognized. This situation could be because the options were
416 previously valid but have been removed from the configure script. Or,
417 there was a mistake when the options were added and there is another
418 option that should be used instead. If you are unsure, consult the
419 upstream build documentation, the ``./configure --help`` output, and
420 the upstream change log or release notes. Once you have worked out
421 what the appropriate change is, you can update
422 :term:`EXTRA_OECONF`,
423 :term:`PACKAGECONFIG_CONFARGS`, or the
424 individual :term:`PACKAGECONFIG` option values
425 accordingly.
426
427  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600428.. _qa-check-pn-overrides:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500429
430- ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]``
431
432 The specified recipe has a name (:term:`PN`) value that
433 appears in :term:`OVERRIDES`. If a recipe is named
Andrew Geissler09036742021-06-25 14:25:14 -0500434 such that its :term:`PN` value matches something already in :term:`OVERRIDES`
435 (e.g. :term:`PN` happens to be the same as :term:`MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500436 or :term:`DISTRO`), it can have unexpected
437 consequences. For example, assignments such as
438 ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
Andrew Geissler09036742021-06-25 14:25:14 -0500439 Rename your recipe (or if :term:`PN` is being set explicitly, change the
440 :term:`PN` value) so that the conflict does not occur. See
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500441 :term:`FILES` for additional information.
442
443  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600444.. _qa-check-pkgvarcheck:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445
446- ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]``
447
448 Certain variables (:term:`RDEPENDS`,
449 :term:`RRECOMMENDS`,
450 :term:`RSUGGESTS`,
451 :term:`RCONFLICTS`,
452 :term:`RPROVIDES`,
453 :term:`RREPLACES`, :term:`FILES`,
454 ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
455 :term:`ALLOW_EMPTY`) should always be set specific
456 to a package (i.e. they should be set with a package name override
457 such as ``RDEPENDS_${PN} = "value"`` rather than
458 ``RDEPENDS = "value"``). If you receive this error, correct any
459 assignments to these variables within your recipe.
460
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600461
462- ``recipe uses DEPENDS_${PN}, should use DEPENDS [pkgvarcheck]``
463
464 This check looks for instances of setting ``DEPENDS_${PN}``
465 which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus
466 it is not correct to specify it for a particular package, nor will such
Andrew Geissler09036742021-06-25 14:25:14 -0500467 an assignment actually work.) Set :term:`DEPENDS` instead.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600468
469
470.. _qa-check-already-stripped:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500471
472- ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]``
473
474 Produced binaries have already been stripped prior to the build
475 system extracting debug symbols. It is common for upstream software
476 projects to default to stripping debug symbols for output binaries.
477 In order for debugging to work on the target using ``-dbg`` packages,
478 this stripping must be disabled.
479
480 Depending on the build system used by the software being built,
481 disabling this stripping could be as easy as specifying an additional
482 configure option. If not, disabling stripping might involve patching
483 the build scripts. In the latter case, look for references to "strip"
484 or "STRIP", or the "-s" or "-S" command-line options being specified
485 on the linker command line (possibly through the compiler command
486 line if preceded with "-Wl,").
487
488 .. note::
489
490 Disabling stripping here does not mean that the final packaged
491 binaries will be unstripped. Once the OpenEmbedded build system
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500492 splits out debug symbols to the ``-dbg`` package, it will then
493 strip the symbols from the binaries.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500494
495  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600496.. _qa-check-packages-list:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500497
498- ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]``
499
500 Package names must appear only once in the
501 :term:`PACKAGES` variable. You might receive this
Andrew Geissler09036742021-06-25 14:25:14 -0500502 error if you are attempting to add a package to :term:`PACKAGES` that is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503 already in the variable's value.
504
505  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600506.. _qa-check-files-invalid:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500507
508- ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]``
509
510 The string "//" is invalid in a Unix path. Correct all occurrences
511 where this string appears in a :term:`FILES` variable so
512 that there is only a single "/".
513
514  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600515.. _qa-check-installed-vs-shipped:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500516
517- ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]``
518
519 Files have been installed within the
520 :ref:`ref-tasks-install` task but have not been
521 included in any package by way of the :term:`FILES`
522 variable. Files that do not appear in any package cannot be present
523 in an image later on in the build process. You need to do one of the
524 following:
525
Andrew Geissler09036742021-06-25 14:25:14 -0500526 - Add the files to :term:`FILES` for the package you want them to appear
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500527 in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main
528 package).
529
530 - Delete the files at the end of the ``do_install`` task if the
531 files are not needed in any package.
532
533  
534
535- ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later``
536
537 This message means that both ``<oldpackage>`` and ``<newpackage>``
538 provide the specified shared library. You can expect this message
539 when a recipe has been renamed. However, if that is not the case, the
540 message might indicate that a private version of a library is being
541 erroneously picked up as the provider for a common library. If that
542 is the case, you should add the library's ``.so`` file name to
543 :term:`PRIVATE_LIBS` in the recipe that provides
544 the private version of the library.
545
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600546
547.. _qa-check-unlisted-pkg-lics:
548
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500549- ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
550
551 The :term:`LICENSE` of the recipe should be a superset
552 of all the licenses of all packages produced by this recipe. In other
553 words, any license in ``LICENSE_*`` should also appear in
554 :term:`LICENSE`.
555
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600556
557.. _qa-check-configure-gettext:
558
559- ``AM_GNU_GETTEXT used but no inherit gettext [configure-gettext]``
560
561 If a recipe is building something that uses automake and the automake
562 files contain an ``AM_GNU_GETTEXT`` directive then this check will fail
563 if there is no ``inherit gettext`` statement in the recipe to ensure
564 that gettext is available during the build. Add ``inherit gettext`` to
565 remove the warning.
566
567
568.. _qa-check-mime:
569
570- ``package contains mime types but does not inherit mime: <packagename> path '<file>' [mime]``
571
572 The specified package contains mime type files (``.xml`` files in
573 ``${datadir}/mime/packages``) and yet does not inherit the mime
574 class which will ensure that these get properly installed. Either
575 add ``inherit mime`` to the recipe or remove the files at the
576 ``do_install`` step if they are not needed.
577
578
579.. _qa-check-mime-xdg:
580
581- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]``
582
583 The specified package contains a .desktop file with a 'MimeType' key
584 present, but does not inherit the mime-xdg class that is required in
585 order for that to be activated. Either add ``inherit mime`` to the
586 recipe or remove the files at the ``do_install`` step if they are not
587 needed.
588
589
590.. _qa-check-src-uri-bad:
591
592- ``<recipename>: SRC_URI uses unstable GitHub archives [src-uri-bad]``
593
594 GitHub provides "archive" tarballs, however these can be re-generated
595 on the fly and thus the file's signature will not necessarily match that
596 in the SRC_URI checksums in future leading to build failures. It is
597 recommended that you use an official release tarball or switch to
598 pulling the corresponding revision in the actual git repository instead.
599
600
601- ``SRC_URI uses PN not BPN [src-uri-bad]``
602
603 If some part of :term:`SRC_URI` needs to reference the recipe name, it should do
604 so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change
605 for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND`
606 or multilib are being used. This check will fail if a reference to ``${PN}``
Andrew Geissler5f350902021-07-23 13:09:54 -0400607 is found within the :term:`SRC_URI` value - change it to ``${BPN}`` instead.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600608
609
610.. _qa-check-unhandled-features-check:
611
612- ``<recipename>: recipe doesn't inherit features_check [unhandled-features-check]``
613
614 This check ensures that if one of the variables that the :ref:`features_check <ref-classes-features_check>`
615 class supports (e.g. :term:`REQUIRED_DISTRO_FEATURES`) is used, then the recipe
616 inherits ``features_check`` in order for the requirement to actually work. If
617 you are seeing this message, either add ``inherit features_check`` to your recipe
618 or remove the reference to the variable if it is not needed.
619
620
621.. _qa-check-missing-update-alternatives:
622
623- ``<recipename>: recipe defines ALTERNATIVE_<packagename> but doesn't inherit update-alternatives. This might fail during do_rootfs later! [missing-update-alternatives]``
624
625 This check ensures that if a recipe sets the :term:`ALTERNATIVE` variable that the
626 recipe also inherits :ref:`update-alternatives <ref-classes-update-alternatives>` such
627 that the alternative will be correctly set up. If you are seeing this message, either
628 add ``inherit update-alternatives`` to your recipe or remove the reference to the variable
629 if it is not needed.
630
631
632.. _qa-check-shebang-size:
633
634- ``<packagename>: <file> maximum shebang size exceeded, the maximum size is 128. [shebang-size]``
635
636 This check ensures that the shebang line (``#!`` in the first line) for a script
637 is not longer than 128 characters, which can cause an error at runtime depending
638 on the operating system. If you are seeing this message then the specified script
639 may need to be patched to have a shorter in order to avoid runtime problems.
640
641
642.. _qa-check-perllocalpod:
643
644- ``<packagename> contains perllocal.pod (<files>), should not be installed [perllocalpod]``
645
646 ``perllocal.pod`` is an index file of locally installed modules and so shouldn't be
647 installed by any distribution packages. The :ref:`cpan <ref-classes-cpan>` class
648 already sets ``NO_PERLLOCAL`` to stop this file being generated by most Perl recipes,
649 but if a recipe is using ``MakeMaker`` directly then they might not be doing this
650 correctly. This check ensures that perllocal.pod is not in any package in order to
651 avoid multiple packages shipping this file and thus their packages conflicting
652 if installed together.
653
654
655.. _qa-check-usrmerge:
656
657- ``<packagename> package is not obeying usrmerge distro feature. /<path> should be relocated to /usr. [usrmerge]``
658
659 If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package
660 installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this
661 message, it indicates that the ``do_install`` step (or perhaps the build process that
662 ``do_install`` is calling into, e.g. ``make install`` is using hardcoded paths instead
663 of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be
664 changed so that it does.
665
666
667.. _qa-check-patch-fuzz:
668
669- ``Fuzz detected: <patch output> [patch-fuzz]``
670
671 This check looks for evidence of "fuzz" when applying patches within the ``do_patch``
672 task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context
673 lines in order to apply the patch. Consider this example:
674
Andrew Geisslerc926e172021-05-07 16:11:35 -0500675 Patch to be applied::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600676
677 --- filename
678 +++ filename
679 context line 1
680 context line 2
681 context line 3
682 +newly added line
683 context line 4
684 context line 5
685 context line 6
686
Andrew Geisslerc926e172021-05-07 16:11:35 -0500687 Original source code::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600688
689 different context line 1
690 different context line 2
691 context line 3
692 context line 4
693 different context line 5
694 different context line 6
695
Andrew Geisslerc926e172021-05-07 16:11:35 -0500696 Outcome (after applying patch with fuzz)::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600697
698 different context line 1
699 different context line 2
700 context line 3
701 newly added line
702 context line 4
703 different context line 5
704 different context line 6
705
706 Chances are, the newly added line was actually added in a completely
707 wrong location, or it was already in the original source and was added
708 for the second time. This is especially possible if the context line 3
709 and 4 are blank or have only generic things in them, such as ``#endif`` or ``}``.
710 Depending on the patched code, it is entirely possible for an incorrectly
711 patched file to still compile without errors.
712
713 *How to eliminate patch fuzz warnings*
714
715 Use the ``devtool`` command as explained by the warning. First, unpack the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500716 source into devtool workspace::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600717
718 devtool modify <recipe>
719
720 This will apply all of the patches, and create new commits out of them in
721 the workspace - with the patch context updated.
722
Andrew Geisslerc926e172021-05-07 16:11:35 -0500723 Then, replace the patches in the recipe layer::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600724
725 devtool finish --force-patch-refresh <recipe> <layer_path>
726
727 The patch updates then need be reviewed (preferably with a side-by-side diff
728 tool) to ensure they are indeed doing the right thing i.e.:
729
730 #. they are applied in the correct location within the file;
731 #. they do not introduce duplicate lines, or otherwise do things that
732 are no longer necessary.
733
734 To confirm these things, you can also review the patched source code in
735 devtool's workspace, typically in ``<build_dir>/workspace/sources/<recipe>/``
736
737 Once the review is done, you can create and publish a layer commit with
738 the patch updates that modify the context. Devtool may also refresh
739 other things in the patches, those can be discarded.
740
741
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500742
743Configuring and Disabling QA Checks
744===================================
745
746You can configure the QA checks globally so that specific check failures
747either raise a warning or an error message, using the
748:term:`WARN_QA` and :term:`ERROR_QA`
749variables, respectively. You can also disable checks within a particular
750recipe using :term:`INSANE_SKIP`. For information on
751how to work with the QA checks, see the
752":ref:`insane.bbclass <ref-classes-insane>`" section.
753
754.. note::
755
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700756 Please keep in mind that the QA checks are meant to detect real
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500757 or potential problems in the packaged output. So exercise caution
758 when disabling these checks.