blob: fb31dc16f98790cfb4568ed1939276bd560a1d43 [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
Andrew Geissler595f6302022-01-24 19:11:47 +000031 listed in the ":ref:`ref-classes-insane`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050032 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
Patrick Williams93c203f2021-10-06 16:15:23 -0500154 ``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
Patrick Williams03907ee2022-05-01 06:28:52 -0500157.. _qa-check-empty-dirs:
158
159- ``<packagename> installs files in <path>, but it is expected to be empty [empty-dirs]``
160
161 The specified package is installing files into a directory that is
162 normally expected to be empty (such as ``/tmp``). These files may
163 be more appropriately installed to a different location, or
164 perhaps alternatively not installed at all, usually by updating the
Patrick Williams2194f502022-10-16 14:26:09 -0500165 :ref:`ref-tasks-install` task/function.
Patrick Williams03907ee2022-05-01 06:28:52 -0500166
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600167.. _qa-check-arch:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600169- ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500170
171 By default, the OpenEmbedded build system checks the Executable and
172 Linkable Format (ELF) type, bit size, and endianness of any binaries
173 to ensure they match the target architecture. This test fails if any
174 binaries do not match the type since there would be an
175 incompatibility. The test could indicate that the wrong compiler or
176 compiler options have been used. Sometimes software, like
177 bootloaders, might need to bypass this check. If the file you receive
178 the error for is firmware that is not intended to be executed within
179 the target operating system or is intended to run on a separate
180 processor within the device, you can add "arch" to
181 :term:`INSANE_SKIP` for the package. Another
182 option is to check the :ref:`ref-tasks-compile` log
183 and verify that the compiler options being used are correct.
184
185  
186
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600187- ``Bit size did not match (<file_bits>, expected <machine_bits>) in <file> [arch]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500188
189 By default, the OpenEmbedded build system checks the Executable and
190 Linkable Format (ELF) type, bit size, and endianness of any binaries
191 to ensure they match the target architecture. This test fails if any
192 binaries do not match the type since there would be an
193 incompatibility. The test could indicate that the wrong compiler or
194 compiler options have been used. Sometimes software, like
195 bootloaders, might need to bypass this check. If the file you receive
196 the error for is firmware that is not intended to be executed within
197 the target operating system or is intended to run on a separate
198 processor within the device, you can add "arch" to
199 :term:`INSANE_SKIP` for the package. Another
200 option is to check the :ref:`ref-tasks-compile` log
201 and verify that the compiler options being used are correct.
202
203  
204
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600205- ``Endianness did not match (<file_endianness>, expected <machine_endianness>) in <file> [arch]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500206
207 By default, the OpenEmbedded build system checks the Executable and
208 Linkable Format (ELF) type, bit size, and endianness of any binaries
209 to ensure they match the target architecture. This test fails if any
210 binaries do not match the type since there would be an
211 incompatibility. The test could indicate that the wrong compiler or
212 compiler options have been used. Sometimes software, like
213 bootloaders, might need to bypass this check. If the file you receive
214 the error for is firmware that is not intended to be executed within
215 the target operating system or is intended to run on a separate
216 processor within the device, you can add "arch" to
217 :term:`INSANE_SKIP` for the package. Another
218 option is to check the :ref:`ref-tasks-compile` log
219 and verify that the compiler options being used are correct.
220
221  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600222.. _qa-check-textrel:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500223
224- ``ELF binary '<file>' has relocations in .text [textrel]``
225
226 The specified ELF binary contains relocations in its ``.text``
227 sections. This situation can result in a performance impact at
228 runtime.
229
230 Typically, the way to solve this performance issue is to add "-fPIC"
231 or "-fpic" to the compiler command-line options. For example, given
232 software that reads :term:`CFLAGS` when you build it,
Andrew Geisslerc926e172021-05-07 16:11:35 -0500233 you could add the following to your recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500234
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500235 CFLAGS:append = " -fPIC "
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500236
237 For more information on text relocations at runtime, see
Andrew Geisslerd1e89492021-02-12 15:35:20 -0600238 https://www.akkadia.org/drepper/textrelocs.html.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500239
240  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600241.. _qa-check-ldflags:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500242
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600243- ``File '<file>' in package '<package>' doesn't have GNU_HASH (didn't pass LDFLAGS?) [ldflags]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500244
245 This indicates that binaries produced when building the recipe have
246 not been linked with the :term:`LDFLAGS` options
Andrew Geissler09036742021-06-25 14:25:14 -0500247 provided by the build system. Check to be sure that the :term:`LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500248 variable is being passed to the linker command. A common workaround
Andrew Geissler09036742021-06-25 14:25:14 -0500249 for this situation is to pass in :term:`LDFLAGS` using
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500250 :term:`TARGET_CC_ARCH` within the recipe as
Andrew Geisslerc926e172021-05-07 16:11:35 -0500251 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500252
253 TARGET_CC_ARCH += "${LDFLAGS}"
254
255  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600256.. _qa-check-xorg-driver-abi:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500257
258- ``Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi]``
259
260 The specified package contains an Xorg driver, but does not have a
261 corresponding ABI package dependency. The xserver-xorg recipe
262 provides driver ABI names. All drivers should depend on the ABI
263 versions that they have been built against. Driver recipes that
264 include ``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
265 automatically get these versions. Consequently, you should only need
266 to explicitly add dependencies to binary driver recipes.
267
268  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600269.. _qa-check-infodir:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500270
271- ``The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]``
272
273 The ``/usr/share/info/dir`` should not be packaged. Add the following
274 line to your :ref:`ref-tasks-install` task or to your
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500275 ``do_install:append`` within the recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500276
277 rm ${D}${infodir}/dir
278  
279
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600280.. _qa-check-symlink-to-sysroot:
281
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
283
284 The specified symlink points into :term:`TMPDIR` on the
285 host. Such symlinks will work on the host. However, they are clearly
286 invalid when running on the target. You should either correct the
287 symlink to use a relative path or remove the symlink.
288
289  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600290.. _qa-check-la:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500291
292- ``<file> failed sanity test (workdir) in path <path> [la]``
293
294 The specified ``.la`` file contains :term:`TMPDIR`
295 paths. Any ``.la`` file containing these paths is incorrect since
296 ``libtool`` adds the correct sysroot prefix when using the files
297 automatically itself.
298
299  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600300.. _qa-check-pkgconfig:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500301
302- ``<file> failed sanity test (tmpdir) in path <path> [pkgconfig]``
303
304 The specified ``.pc`` file contains
305 :term:`TMPDIR`\ ``/``\ :term:`WORKDIR`
306 paths. Any ``.pc`` file containing these paths is incorrect since
307 ``pkg-config`` itself adds the correct sysroot prefix when the files
308 are accessed.
309
310  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600311.. _qa-check-debug-deps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500312
313- ``<packagename> rdepends on <debug_packagename> [debug-deps]``
314
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700315 There is a dependency between the specified non-dbg package (i.e. a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500316 package whose name does not end in ``-dbg``) and a package that is a
317 ``dbg`` package. The ``dbg`` packages contain debug symbols and are
318 brought in using several different methods:
319
320 - Using the ``dbg-pkgs``
321 :term:`IMAGE_FEATURES` value.
322
323 - Using :term:`IMAGE_INSTALL`.
324
325 - As a dependency of another ``dbg`` package that was brought in
326 using one of the above methods.
327
328 The dependency might have been automatically added because the
329 ``dbg`` package erroneously contains files that it should not contain
330 (e.g. a non-symlink ``.so`` file) or it might have been added
331 manually (e.g. by adding to :term:`RDEPENDS`).
332
333  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600334.. _qa-check-dev-deps:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500335
336- ``<packagename> rdepends on <dev_packagename> [dev-deps]``
337
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700338 There is a dependency between the specified non-dev package (a package
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500339 whose name does not end in ``-dev``) and a package that is a ``dev``
340 package. The ``dev`` packages contain development headers and are
341 usually brought in using several different methods:
342
343 - Using the ``dev-pkgs``
344 :term:`IMAGE_FEATURES` value.
345
346 - Using :term:`IMAGE_INSTALL`.
347
348 - As a dependency of another ``dev`` package that was brought in
349 using one of the above methods.
350
351 The dependency might have been automatically added (because the
352 ``dev`` package erroneously contains files that it should not have
353 (e.g. a non-symlink ``.so`` file) or it might have been added
354 manually (e.g. by adding to :term:`RDEPENDS`).
355
356  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600357.. _qa-check-dep-cmp:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500358
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500359- ``<var>:<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500360
361 If you are adding a versioned dependency relationship to one of the
362 dependency variables (:term:`RDEPENDS`,
363 :term:`RRECOMMENDS`,
364 :term:`RSUGGESTS`,
365 :term:`RPROVIDES`,
366 :term:`RREPLACES`, or
367 :term:`RCONFLICTS`), you must only use the named
368 comparison operators. Change the versioned dependency values you are
369 adding to match those listed in the message.
370
371  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600372.. _qa-check-compile-host-path:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500373
374- ``<recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path]``
375
376 The log for the :ref:`ref-tasks-compile` task
377 indicates that paths on the host were searched for files, which is
378 not appropriate when cross-compiling. Look for "is unsafe for
379 cross-compilation" or "CROSS COMPILE Badness" in the specified log
380 file.
381
382  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600383.. _qa-check-install-host-path:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500384
385- ``<recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path]``
386
387 The log for the :ref:`ref-tasks-install` task
388 indicates that paths on the host were searched for files, which is
389 not appropriate when cross-compiling. Look for "is unsafe for
390 cross-compilation" or "CROSS COMPILE Badness" in the specified log
391 file.
392
393  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600394.. _qa-check-configure-unsafe:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500395
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600396- ``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 -0500397
398 The log for the :ref:`ref-tasks-configure` task
399 indicates that paths on the host were searched for files, which is
400 not appropriate when cross-compiling. Look for "is unsafe for
401 cross-compilation" or "CROSS COMPILE Badness" in the specified log
402 file.
403
404  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600405.. _qa-check-pkgname:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500406
407- ``<packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname]``
408
409 The convention within the OpenEmbedded build system (sometimes
410 enforced by the package manager itself) is to require that package
411 names are all lower case and to allow a restricted set of characters.
412 If your recipe name does not match this, or you add packages to
413 :term:`PACKAGES` that do not conform to the
414 convention, then you will receive this error. Rename your recipe. Or,
Andrew Geissler09036742021-06-25 14:25:14 -0500415 if you have added a non-conforming package name to :term:`PACKAGES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500416 change the package name appropriately.
417
418  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600419.. _qa-check-unknown-configure-option:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500420
421- ``<recipe>: configure was passed unrecognized options: <options> [unknown-configure-option]``
422
423 The configure script is reporting that the specified options are
424 unrecognized. This situation could be because the options were
425 previously valid but have been removed from the configure script. Or,
426 there was a mistake when the options were added and there is another
427 option that should be used instead. If you are unsure, consult the
428 upstream build documentation, the ``./configure --help`` output, and
429 the upstream change log or release notes. Once you have worked out
430 what the appropriate change is, you can update
431 :term:`EXTRA_OECONF`,
432 :term:`PACKAGECONFIG_CONFARGS`, or the
433 individual :term:`PACKAGECONFIG` option values
434 accordingly.
435
436  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600437.. _qa-check-pn-overrides:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500438
439- ``Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]``
440
441 The specified recipe has a name (:term:`PN`) value that
442 appears in :term:`OVERRIDES`. If a recipe is named
Andrew Geissler09036742021-06-25 14:25:14 -0500443 such that its :term:`PN` value matches something already in :term:`OVERRIDES`
444 (e.g. :term:`PN` happens to be the same as :term:`MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445 or :term:`DISTRO`), it can have unexpected
446 consequences. For example, assignments such as
Patrick Williams93c203f2021-10-06 16:15:23 -0500447 ``FILES:${PN} = "xyz"`` effectively turn into ``FILES = "xyz"``.
Andrew Geissler09036742021-06-25 14:25:14 -0500448 Rename your recipe (or if :term:`PN` is being set explicitly, change the
449 :term:`PN` value) so that the conflict does not occur. See
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500450 :term:`FILES` for additional information.
451
452  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600453.. _qa-check-pkgvarcheck:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500454
455- ``<recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck]``
456
457 Certain variables (:term:`RDEPENDS`,
458 :term:`RRECOMMENDS`,
459 :term:`RSUGGESTS`,
460 :term:`RCONFLICTS`,
461 :term:`RPROVIDES`,
462 :term:`RREPLACES`, :term:`FILES`,
463 ``pkg_preinst``, ``pkg_postinst``, ``pkg_prerm``, ``pkg_postrm``, and
464 :term:`ALLOW_EMPTY`) should always be set specific
465 to a package (i.e. they should be set with a package name override
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500466 such as ``RDEPENDS:${PN} = "value"`` rather than
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500467 ``RDEPENDS = "value"``). If you receive this error, correct any
468 assignments to these variables within your recipe.
469
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600470
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500471- ``recipe uses DEPENDS:${PN}, should use DEPENDS [pkgvarcheck]``
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600472
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500473 This check looks for instances of setting ``DEPENDS:${PN}``
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600474 which is erroneous (:term:`DEPENDS` is a recipe-wide variable and thus
475 it is not correct to specify it for a particular package, nor will such
Andrew Geissler09036742021-06-25 14:25:14 -0500476 an assignment actually work.) Set :term:`DEPENDS` instead.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600477
478
479.. _qa-check-already-stripped:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500480
481- ``File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped]``
482
483 Produced binaries have already been stripped prior to the build
484 system extracting debug symbols. It is common for upstream software
485 projects to default to stripping debug symbols for output binaries.
486 In order for debugging to work on the target using ``-dbg`` packages,
487 this stripping must be disabled.
488
489 Depending on the build system used by the software being built,
490 disabling this stripping could be as easy as specifying an additional
491 configure option. If not, disabling stripping might involve patching
492 the build scripts. In the latter case, look for references to "strip"
493 or "STRIP", or the "-s" or "-S" command-line options being specified
494 on the linker command line (possibly through the compiler command
495 line if preceded with "-Wl,").
496
497 .. note::
498
499 Disabling stripping here does not mean that the final packaged
500 binaries will be unstripped. Once the OpenEmbedded build system
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500501 splits out debug symbols to the ``-dbg`` package, it will then
502 strip the symbols from the binaries.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500503
504  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600505.. _qa-check-packages-list:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500506
507- ``<packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]``
508
509 Package names must appear only once in the
510 :term:`PACKAGES` variable. You might receive this
Andrew Geissler09036742021-06-25 14:25:14 -0500511 error if you are attempting to add a package to :term:`PACKAGES` that is
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500512 already in the variable's value.
513
514  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600515.. _qa-check-files-invalid:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500516
517- ``FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]``
518
519 The string "//" is invalid in a Unix path. Correct all occurrences
520 where this string appears in a :term:`FILES` variable so
521 that there is only a single "/".
522
523  
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600524.. _qa-check-installed-vs-shipped:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500525
526- ``<recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped]``
527
528 Files have been installed within the
529 :ref:`ref-tasks-install` task but have not been
530 included in any package by way of the :term:`FILES`
531 variable. Files that do not appear in any package cannot be present
532 in an image later on in the build process. You need to do one of the
533 following:
534
Andrew Geissler09036742021-06-25 14:25:14 -0500535 - Add the files to :term:`FILES` for the package you want them to appear
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500536 in (e.g. ``FILES:${``\ :term:`PN`\ ``}`` for the main
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500537 package).
538
Patrick Williams2194f502022-10-16 14:26:09 -0500539 - Delete the files at the end of the :ref:`ref-tasks-install` task if the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500540 files are not needed in any package.
541
542  
543
544- ``<oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later``
545
546 This message means that both ``<oldpackage>`` and ``<newpackage>``
547 provide the specified shared library. You can expect this message
548 when a recipe has been renamed. However, if that is not the case, the
549 message might indicate that a private version of a library is being
550 erroneously picked up as the provider for a common library. If that
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500551 is the case, you should add the library's ``.so`` filename to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500552 :term:`PRIVATE_LIBS` in the recipe that provides
553 the private version of the library.
554
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600555
556.. _qa-check-unlisted-pkg-lics:
557
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500558- ``LICENSE:<packagename> includes licenses (<licenses>) that are not listed in LICENSE [unlisted-pkg-lics]``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559
560 The :term:`LICENSE` of the recipe should be a superset
561 of all the licenses of all packages produced by this recipe. In other
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500562 words, any license in ``LICENSE:*`` should also appear in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500563 :term:`LICENSE`.
564
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600565
566.. _qa-check-configure-gettext:
567
568- ``AM_GNU_GETTEXT used but no inherit gettext [configure-gettext]``
569
570 If a recipe is building something that uses automake and the automake
571 files contain an ``AM_GNU_GETTEXT`` directive then this check will fail
572 if there is no ``inherit gettext`` statement in the recipe to ensure
573 that gettext is available during the build. Add ``inherit gettext`` to
574 remove the warning.
575
576
577.. _qa-check-mime:
578
579- ``package contains mime types but does not inherit mime: <packagename> path '<file>' [mime]``
580
581 The specified package contains mime type files (``.xml`` files in
582 ``${datadir}/mime/packages``) and yet does not inherit the mime
583 class which will ensure that these get properly installed. Either
584 add ``inherit mime`` to the recipe or remove the files at the
Patrick Williams2194f502022-10-16 14:26:09 -0500585 :ref:`ref-tasks-install` step if they are not needed.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600586
587
588.. _qa-check-mime-xdg:
589
590- ``package contains desktop file with key 'MimeType' but does not inhert mime-xdg: <packagename> path '<file>' [mime-xdg]``
591
592 The specified package contains a .desktop file with a 'MimeType' key
593 present, but does not inherit the mime-xdg class that is required in
594 order for that to be activated. Either add ``inherit mime`` to the
Patrick Williams2194f502022-10-16 14:26:09 -0500595 recipe or remove the files at the :ref:`ref-tasks-install` step if they are not
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600596 needed.
597
598
599.. _qa-check-src-uri-bad:
600
601- ``<recipename>: SRC_URI uses unstable GitHub archives [src-uri-bad]``
602
603 GitHub provides "archive" tarballs, however these can be re-generated
604 on the fly and thus the file's signature will not necessarily match that
605 in the SRC_URI checksums in future leading to build failures. It is
606 recommended that you use an official release tarball or switch to
607 pulling the corresponding revision in the actual git repository instead.
608
609
610- ``SRC_URI uses PN not BPN [src-uri-bad]``
611
612 If some part of :term:`SRC_URI` needs to reference the recipe name, it should do
613 so using ${:term:`BPN`} rather than ${:term:`PN`} as the latter will change
614 for different variants of the same recipe e.g. when :term:`BBCLASSEXTEND`
615 or multilib are being used. This check will fail if a reference to ``${PN}``
Andrew Geissler615f2f12022-07-15 14:00:58 -0500616 is found within the :term:`SRC_URI` value --- change it to ``${BPN}`` instead.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600617
618
619.. _qa-check-unhandled-features-check:
620
621- ``<recipename>: recipe doesn't inherit features_check [unhandled-features-check]``
622
623 This check ensures that if one of the variables that the :ref:`features_check <ref-classes-features_check>`
624 class supports (e.g. :term:`REQUIRED_DISTRO_FEATURES`) is used, then the recipe
625 inherits ``features_check`` in order for the requirement to actually work. If
626 you are seeing this message, either add ``inherit features_check`` to your recipe
627 or remove the reference to the variable if it is not needed.
628
629
630.. _qa-check-missing-update-alternatives:
631
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500632- ``<recipename>: recipe defines ALTERNATIVE:<packagename> but doesn't inherit update-alternatives. This might fail during do_rootfs later! [missing-update-alternatives]``
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600633
634 This check ensures that if a recipe sets the :term:`ALTERNATIVE` variable that the
635 recipe also inherits :ref:`update-alternatives <ref-classes-update-alternatives>` such
636 that the alternative will be correctly set up. If you are seeing this message, either
637 add ``inherit update-alternatives`` to your recipe or remove the reference to the variable
638 if it is not needed.
639
640
641.. _qa-check-shebang-size:
642
643- ``<packagename>: <file> maximum shebang size exceeded, the maximum size is 128. [shebang-size]``
644
645 This check ensures that the shebang line (``#!`` in the first line) for a script
646 is not longer than 128 characters, which can cause an error at runtime depending
647 on the operating system. If you are seeing this message then the specified script
648 may need to be patched to have a shorter in order to avoid runtime problems.
649
650
651.. _qa-check-perllocalpod:
652
653- ``<packagename> contains perllocal.pod (<files>), should not be installed [perllocalpod]``
654
655 ``perllocal.pod`` is an index file of locally installed modules and so shouldn't be
656 installed by any distribution packages. The :ref:`cpan <ref-classes-cpan>` class
657 already sets ``NO_PERLLOCAL`` to stop this file being generated by most Perl recipes,
658 but if a recipe is using ``MakeMaker`` directly then they might not be doing this
659 correctly. This check ensures that perllocal.pod is not in any package in order to
660 avoid multiple packages shipping this file and thus their packages conflicting
661 if installed together.
662
663
664.. _qa-check-usrmerge:
665
666- ``<packagename> package is not obeying usrmerge distro feature. /<path> should be relocated to /usr. [usrmerge]``
667
668 If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this check will ensure that no package
669 installs files to root (``/bin``, ``/sbin``, ``/lib``, ``/lib64``) directories. If you are seeing this
Patrick Williams2194f502022-10-16 14:26:09 -0500670 message, it indicates that the :ref:`ref-tasks-install` step (or perhaps the build process that
671 :ref:`ref-tasks-install` is calling into, e.g. ``make install`` is using hardcoded paths instead
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600672 of the variables set up for this (``bindir``, ``sbindir``, etc.), and should be
673 changed so that it does.
674
675
676.. _qa-check-patch-fuzz:
677
678- ``Fuzz detected: <patch output> [patch-fuzz]``
679
Patrick Williams2194f502022-10-16 14:26:09 -0500680 This check looks for evidence of "fuzz" when applying patches within the :ref:`ref-tasks-patch`
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600681 task. Patch fuzz is a situation when the ``patch`` tool ignores some of the context
682 lines in order to apply the patch. Consider this example:
683
Andrew Geisslerc926e172021-05-07 16:11:35 -0500684 Patch to be applied::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600685
686 --- filename
687 +++ filename
688 context line 1
689 context line 2
690 context line 3
691 +newly added line
692 context line 4
693 context line 5
694 context line 6
695
Andrew Geisslerc926e172021-05-07 16:11:35 -0500696 Original source code::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600697
698 different context line 1
699 different context line 2
700 context line 3
701 context line 4
702 different context line 5
703 different context line 6
704
Andrew Geisslerc926e172021-05-07 16:11:35 -0500705 Outcome (after applying patch with fuzz)::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600706
707 different context line 1
708 different context line 2
709 context line 3
710 newly added line
711 context line 4
712 different context line 5
713 different context line 6
714
715 Chances are, the newly added line was actually added in a completely
716 wrong location, or it was already in the original source and was added
717 for the second time. This is especially possible if the context line 3
718 and 4 are blank or have only generic things in them, such as ``#endif`` or ``}``.
719 Depending on the patched code, it is entirely possible for an incorrectly
720 patched file to still compile without errors.
721
722 *How to eliminate patch fuzz warnings*
723
724 Use the ``devtool`` command as explained by the warning. First, unpack the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500725 source into devtool workspace::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600726
727 devtool modify <recipe>
728
729 This will apply all of the patches, and create new commits out of them in
Andrew Geissler615f2f12022-07-15 14:00:58 -0500730 the workspace --- with the patch context updated.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600731
Andrew Geisslerc926e172021-05-07 16:11:35 -0500732 Then, replace the patches in the recipe layer::
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600733
734 devtool finish --force-patch-refresh <recipe> <layer_path>
735
736 The patch updates then need be reviewed (preferably with a side-by-side diff
737 tool) to ensure they are indeed doing the right thing i.e.:
738
739 #. they are applied in the correct location within the file;
740 #. they do not introduce duplicate lines, or otherwise do things that
741 are no longer necessary.
742
743 To confirm these things, you can also review the patched source code in
744 devtool's workspace, typically in ``<build_dir>/workspace/sources/<recipe>/``
745
746 Once the review is done, you can create and publish a layer commit with
747 the patch updates that modify the context. Devtool may also refresh
748 other things in the patches, those can be discarded.
749
750
Patrick Williams975a06f2022-10-21 14:42:47 -0500751.. _qa-check-buildpaths:
752
753- ``File <filename> in package <packagename> contains reference to TMPDIR [buildpaths]``
754
755 This check ensures that build system paths (including :term:`TMPDIR`) do not
756 appear in output files, which not only leaks build system configuration into
757 the target, but also hinders binary reproducibility as the output will change
758 if the build system configuration changes.
759
760 Typically these paths will enter the output through some mechanism in the
761 configuration or compilation of the software being built by the recipe. To
762 resolve this issue you will need to determine how the detected path is
763 entering the output. Sometimes it may require adjusting scripts or code to
764 use a relative path rather than an absolute one, or to pick up the path from
765 runtime configuration or environment variables.
766
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500767
768Configuring and Disabling QA Checks
769===================================
770
771You can configure the QA checks globally so that specific check failures
772either raise a warning or an error message, using the
773:term:`WARN_QA` and :term:`ERROR_QA`
774variables, respectively. You can also disable checks within a particular
775recipe using :term:`INSANE_SKIP`. For information on
776how to work with the QA checks, see the
Andrew Geissler595f6302022-01-24 19:11:47 +0000777":ref:`ref-classes-insane`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500778
779.. note::
780
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700781 Please keep in mind that the QA checks are meant to detect real
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500782 or potential problems in the packaged output. So exercise caution
783 when disabling these checks.