blob: 3e76ac1509e190e8a714df581647ef2a5535d024 [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001.. SPDX-License-Identifier: CC-BY-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- ``<packagename>: <path> is using libexec please relocate to <libexecdir> [libexec]``
47
48 The specified package contains files in ``/usr/libexec`` when the
49 distro configuration uses a different path for ``<libexecdir>`` By
50 default, ``<libexecdir>`` is ``$prefix/libexec``. However, this
51 default can be changed (e.g. ``${libdir}``).
52
53  
54
55- ``package <packagename> contains bad RPATH <rpath> in file <file> [rpaths]``
56
57 The specified binary produced by the recipe contains dynamic library
58 load paths (rpaths) that contain build system paths such as
59 :term:`TMPDIR`, which are incorrect for the target and
60 could potentially be a security issue. Check for bad ``-rpath``
61 options being passed to the linker in your
62 :ref:`ref-tasks-compile` log. Depending on the build
63 system used by the software being built, there might be a configure
64 option to disable rpath usage completely within the build of the
65 software.
66
67  
68
69- ``<packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths]``
70
71 The specified binary produced by the recipe contains dynamic library
72 load paths (rpaths) that on a standard system are searched by default
73 by the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths
74 will not cause any breakage, they do waste space and are unnecessary.
75 Depending on the build system used by the software being built, there
76 might be a configure option to disable rpath usage completely within
77 the build of the software.
78
79  
80
81- ``<packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps]``
82
83 A file-level dependency has been identified from the specified
84 package on the specified files, but there is no explicit
85 corresponding entry in :term:`RDEPENDS`. If
86 particular files are required at runtime then ``RDEPENDS`` should be
87 declared in the recipe to ensure the packages providing them are
88 built.
89
90  
91
92- ``<packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps]``
93
94 A runtime dependency exists between the two specified packages, but
95 there is nothing explicit within the recipe to enable the
96 OpenEmbedded build system to ensure that dependency is satisfied.
97 This condition is usually triggered by an
98 :term:`RDEPENDS` value being added at the packaging
99 stage rather than up front, which is usually automatic based on the
100 contents of the package. In most cases, you should change the recipe
101 to add an explicit ``RDEPENDS`` for the dependency.
102
103  
104
105- ``non -dev/-dbg/nativesdk- package contains symlink .so: <packagename> path '<path>' [dev-so]``
106
107 Symlink ``.so`` files are for development only, and should therefore
108 go into the ``-dev`` package. This situation might occur if you add
109 ``*.so*`` rather than ``*.so.*`` to a non-dev package. Change
110 :term:`FILES` (and possibly
111 :term:`PACKAGES`) such that the specified ``.so``
112 file goes into an appropriate ``-dev`` package.
113
114  
115
116- ``non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev]``
117
118 Static ``.a`` library files should go into a ``-staticdev`` package.
119 Change :term:`FILES` (and possibly
120 :term:`PACKAGES`) such that the specified ``.a`` file
121 goes into an appropriate ``-staticdev`` package.
122
123  
124
125- ``<packagename>: found library in wrong location [libdir]``
126
127 The specified file may have been installed into an incorrect
128 (possibly hardcoded) installation path. For example, this test will
129 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
130 "lib32". Another example is when recipes install
131 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". False
132 positives occasionally exist. For these cases add "libdir" to
133 :term:`INSANE_SKIP` for the package.
134
135  
136
137- ``non debug package contains .debug directory: <packagename> path <path> [debug-files]``
138
139 The specified package contains a ``.debug`` directory, which should
140 not appear in anything but the ``-dbg`` package. This situation might
141 occur if you add a path which contains a ``.debug`` directory and do
142 not explicitly add the ``.debug`` directory to the ``-dbg`` package.
143 If this is the case, add the ``.debug`` directory explicitly to
144 ``FILES_${PN}-dbg``. See :term:`FILES` for additional
145 information on ``FILES``.
146
147  
148
149- ``Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch]``
150
151 By default, the OpenEmbedded build system checks the Executable and
152 Linkable Format (ELF) type, bit size, and endianness of any binaries
153 to ensure they match the target architecture. This test fails if any
154 binaries do not match the type since there would be an
155 incompatibility. The test could indicate that the wrong compiler or
156 compiler options have been used. Sometimes software, like
157 bootloaders, might need to bypass this check. If the file you receive
158 the error for is firmware that is not intended to be executed within
159 the target operating system or is intended to run on a separate
160 processor within the device, you can add "arch" to
161 :term:`INSANE_SKIP` for the package. Another
162 option is to check the :ref:`ref-tasks-compile` log
163 and verify that the compiler options being used are correct.
164
165  
166
167- ``Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch]``
168
169 By default, the OpenEmbedded build system checks the Executable and
170 Linkable Format (ELF) type, bit size, and endianness of any binaries
171 to ensure they match the target architecture. This test fails if any
172 binaries do not match the type since there would be an
173 incompatibility. The test could indicate that the wrong compiler or
174 compiler options have been used. Sometimes software, like
175 bootloaders, might need to bypass this check. If the file you receive
176 the error for is firmware that is not intended to be executed within
177 the target operating system or is intended to run on a separate
178 processor within the device, you can add "arch" to
179 :term:`INSANE_SKIP` for the package. Another
180 option is to check the :ref:`ref-tasks-compile` log
181 and verify that the compiler options being used are correct.
182
183  
184
185- ``Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch]``
186
187 By default, the OpenEmbedded build system checks the Executable and
188 Linkable Format (ELF) type, bit size, and endianness of any binaries
189 to ensure they match the target architecture. This test fails if any
190 binaries do not match the type since there would be an
191 incompatibility. The test could indicate that the wrong compiler or
192 compiler options have been used. Sometimes software, like
193 bootloaders, might need to bypass this check. If the file you receive
194 the error for is firmware that is not intended to be executed within
195 the target operating system or is intended to run on a separate
196 processor within the device, you can add "arch" to
197 :term:`INSANE_SKIP` for the package. Another
198 option is to check the :ref:`ref-tasks-compile` log
199 and verify that the compiler options being used are correct.
200
201  
202
203- ``ELF binary '<file>' has relocations in .text [textrel]``
204
205 The specified ELF binary contains relocations in its ``.text``
206 sections. This situation can result in a performance impact at
207 runtime.
208
209 Typically, the way to solve this performance issue is to add "-fPIC"
210 or "-fpic" to the compiler command-line options. For example, given
211 software that reads :term:`CFLAGS` when you build it,
212 you could add the following to your recipe:
213 ::
214
215 CFLAGS_append = " -fPIC "
216
217 For more information on text relocations at runtime, see
218 http://www.akkadia.org/drepper/textrelocs.html.
219
220  
221
222- ``No GNU_HASH in the elf binary: '<file>' [ldflags]``
223
224 This indicates that binaries produced when building the recipe have
225 not been linked with the :term:`LDFLAGS` options
226 provided by the build system. Check to be sure that the ``LDFLAGS``
227 variable is being passed to the linker command. A common workaround
228 for this situation is to pass in ``LDFLAGS`` using
229 :term:`TARGET_CC_ARCH` within the recipe as
230 follows:
231 ::
232
233 TARGET_CC_ARCH += "${LDFLAGS}"
234
235  
236
237- ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]``
238
239 The specified package contains an Xorg driver, but does not have a
240 corresponding ABI package dependency. The xserver-xorg recipe
241 provides driver ABI names. All drivers should depend on the ABI
242 versions that they have been built against. Driver recipes that
243 include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
244 automatically get these versions. Consequently, you should only need
245 to explicitly add dependencies to binary driver recipes.
246
247  
248
249- ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]``
250
251 The ``/usr/share/info/dir`` should not be packaged. Add the following
252 line to your :ref:`ref-tasks-install` task or to your
253 ``do_install_append`` within the recipe as follows:
254 ::
255
256 rm ${D}${infodir}/dir
257  
258
259- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
260
261 The specified symlink points into :term:`TMPDIR` on the
262 host. Such symlinks will work on the host. However, they are clearly
263 invalid when running on the target. You should either correct the
264 symlink to use a relative path or remove the symlink.
265
266  
267
268- ``<file> failed sanity test (workdir) in path <path> [la]``
269
270 The specified ``.la`` file contains :term:`TMPDIR`
271 paths. Any ``.la`` file containing these paths is incorrect since
272 ``libtool`` adds the correct sysroot prefix when using the files
273 automatically itself.
274
275  
276
277- ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]``
278
279 The specified ``.pc`` file contains
280 :term:`TMPDIR`\ ``/``\ :term:`WORKDIR`
281 paths. Any ``.pc`` file containing these paths is incorrect since
282 ``pkg-config`` itself adds the correct sysroot prefix when the files
283 are accessed.
284
285  
286
287- ``<packagename> rdepends on <debug_packagename> [debug-deps]``
288
289 A dependency exists between the specified non-dbg package (i.e. a
290 package whose name does not end in ``-dbg``) and a package that is a
291 ``dbg`` package. The ``dbg`` packages contain debug symbols and are
292 brought in using several different methods:
293
294 - Using the ``dbg-pkgs``
295 :term:`IMAGE_FEATURES` value.
296
297 - Using :term:`IMAGE_INSTALL`.
298
299 - As a dependency of another ``dbg`` package that was brought in
300 using one of the above methods.
301
302 The dependency might have been automatically added because the
303 ``dbg`` package erroneously contains files that it should not contain
304 (e.g. a non-symlink ``.so`` file) or it might have been added
305 manually (e.g. by adding to :term:`RDEPENDS`).
306
307  
308
309- ``<packagename> rdepends on <dev_packagename> [dev-deps]``
310
311 A dependency exists between the specified non-dev package (a package
312 whose name does not end in ``-dev``) and a package that is a ``dev``
313 package. The ``dev`` packages contain development headers and are
314 usually brought in using several different methods:
315
316 - Using the ``dev-pkgs``
317 :term:`IMAGE_FEATURES` value.
318
319 - Using :term:`IMAGE_INSTALL`.
320
321 - As a dependency of another ``dev`` package that was brought in
322 using one of the above methods.
323
324 The dependency might have been automatically added (because the
325 ``dev`` package erroneously contains files that it should not have
326 (e.g. a non-symlink ``.so`` file) or it might have been added
327 manually (e.g. by adding to :term:`RDEPENDS`).
328
329  
330
331- ``<var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
332
333 If you are adding a versioned dependency relationship to one of the
334 dependency variables (:term:`RDEPENDS`,
335 :term:`RRECOMMENDS`,
336 :term:`RSUGGESTS`,
337 :term:`RPROVIDES`,
338 :term:`RREPLACES`, or
339 :term:`RCONFLICTS`), you must only use the named
340 comparison operators. Change the versioned dependency values you are
341 adding to match those listed in the message.
342
343  
344
345- ``<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]``
346
347 The log for the :ref:`ref-tasks-compile` task
348 indicates that paths on the host were searched for files, which is
349 not appropriate when cross-compiling. Look for "is unsafe for
350 cross-compilation" or "CROSS COMPILE Badness" in the specified log
351 file.
352
353  
354
355- ``<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]``
356
357 The log for the :ref:`ref-tasks-install` task
358 indicates that paths on the host were searched for files, which is
359 not appropriate when cross-compiling. Look for "is unsafe for
360 cross-compilation" or "CROSS COMPILE Badness" in the specified log
361 file.
362
363  
364
365- ``This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>'``
366
367 The log for the :ref:`ref-tasks-configure` 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  
374
375- ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]``
376
377 The convention within the OpenEmbedded build system (sometimes
378 enforced by the package manager itself) is to require that package
379 names are all lower case and to allow a restricted set of characters.
380 If your recipe name does not match this, or you add packages to
381 :term:`PACKAGES` that do not conform to the
382 convention, then you will receive this error. Rename your recipe. Or,
383 if you have added a non-conforming package name to ``PACKAGES``,
384 change the package name appropriately.
385
386  
387
388- ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]``
389
390 The configure script is reporting that the specified options are
391 unrecognized. This situation could be because the options were
392 previously valid but have been removed from the configure script. Or,
393 there was a mistake when the options were added and there is another
394 option that should be used instead. If you are unsure, consult the
395 upstream build documentation, the ``./configure --help`` output, and
396 the upstream change log or release notes. Once you have worked out
397 what the appropriate change is, you can update
398 :term:`EXTRA_OECONF`,
399 :term:`PACKAGECONFIG_CONFARGS`, or the
400 individual :term:`PACKAGECONFIG` option values
401 accordingly.
402
403  
404
405- ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]``
406
407 The specified recipe has a name (:term:`PN`) value that
408 appears in :term:`OVERRIDES`. If a recipe is named
409 such that its ``PN`` value matches something already in ``OVERRIDES``
410 (e.g. ``PN`` happens to be the same as :term:`MACHINE`
411 or :term:`DISTRO`), it can have unexpected
412 consequences. For example, assignments such as
413 ``FILES_${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
414 Rename your recipe (or if ``PN`` is being set explicitly, change the
415 ``PN`` value) so that the conflict does not occur. See
416 :term:`FILES` for additional information.
417
418  
419
420- ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]``
421
422 Certain variables (:term:`RDEPENDS`,
423 :term:`RRECOMMENDS`,
424 :term:`RSUGGESTS`,
425 :term:`RCONFLICTS`,
426 :term:`RPROVIDES`,
427 :term:`RREPLACES`, :term:`FILES`,
428 ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
429 :term:`ALLOW_EMPTY`) should always be set specific
430 to a package (i.e. they should be set with a package name override
431 such as ``RDEPENDS_${PN} = "value"`` rather than
432 ``RDEPENDS = "value"``). If you receive this error, correct any
433 assignments to these variables within your recipe.
434
435  
436
437- ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]``
438
439 Produced binaries have already been stripped prior to the build
440 system extracting debug symbols. It is common for upstream software
441 projects to default to stripping debug symbols for output binaries.
442 In order for debugging to work on the target using ``-dbg`` packages,
443 this stripping must be disabled.
444
445 Depending on the build system used by the software being built,
446 disabling this stripping could be as easy as specifying an additional
447 configure option. If not, disabling stripping might involve patching
448 the build scripts. In the latter case, look for references to "strip"
449 or "STRIP", or the "-s" or "-S" command-line options being specified
450 on the linker command line (possibly through the compiler command
451 line if preceded with "-Wl,").
452
453 .. note::
454
455 Disabling stripping here does not mean that the final packaged
456 binaries will be unstripped. Once the OpenEmbedded build system
457 splits out debug symbols to the
458 -dbg
459 package, it will then strip the symbols from the binaries.
460
461  
462
463- ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]``
464
465 Package names must appear only once in the
466 :term:`PACKAGES` variable. You might receive this
467 error if you are attempting to add a package to ``PACKAGES`` that is
468 already in the variable's value.
469
470  
471
472- ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]``
473
474 The string "//" is invalid in a Unix path. Correct all occurrences
475 where this string appears in a :term:`FILES` variable so
476 that there is only a single "/".
477
478  
479
480- ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]``
481
482 Files have been installed within the
483 :ref:`ref-tasks-install` task but have not been
484 included in any package by way of the :term:`FILES`
485 variable. Files that do not appear in any package cannot be present
486 in an image later on in the build process. You need to do one of the
487 following:
488
489 - Add the files to ``FILES`` for the package you want them to appear
490 in (e.g. ``FILES_${``\ :term:`PN`\ ``}`` for the main
491 package).
492
493 - Delete the files at the end of the ``do_install`` task if the
494 files are not needed in any package.
495
496  
497
498- ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later``
499
500 This message means that both ``<oldpackage>`` and ``<newpackage>``
501 provide the specified shared library. You can expect this message
502 when a recipe has been renamed. However, if that is not the case, the
503 message might indicate that a private version of a library is being
504 erroneously picked up as the provider for a common library. If that
505 is the case, you should add the library's ``.so`` file name to
506 :term:`PRIVATE_LIBS` in the recipe that provides
507 the private version of the library.
508
509- ``LICENSE_<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
510
511 The :term:`LICENSE` of the recipe should be a superset
512 of all the licenses of all packages produced by this recipe. In other
513 words, any license in ``LICENSE_*`` should also appear in
514 :term:`LICENSE`.
515
516  
517
518Configuring and Disabling QA Checks
519===================================
520
521You can configure the QA checks globally so that specific check failures
522either raise a warning or an error message, using the
523:term:`WARN_QA` and :term:`ERROR_QA`
524variables, respectively. You can also disable checks within a particular
525recipe using :term:`INSANE_SKIP`. For information on
526how to work with the QA checks, see the
527":ref:`insane.bbclass <ref-classes-insane>`" section.
528
529.. note::
530
531 Please keep in mind that the QA checks exist in order to detect real
532 or potential problems in the packaged output. So exercise caution
533 when disabling these checks.