summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-qa-checks.xml
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-10-05 16:30:32 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-10-06 13:56:17 +0100
commit43d07a285181e64c30d98d10ff93ef50391efe59 (patch)
tree78918fc94d55d44d35e1e3e61c7a6fccc28bca24 /documentation/ref-manual/ref-qa-checks.xml
parent1fd9c4b2c0ae927df29f7a0d34c3e595bcf48e89 (diff)
downloadpoky-43d07a285181e64c30d98d10ff93ef50391efe59.tar.gz
sphinx: remove DocBook files
The Yocto Project documentation was migrated to Sphinx. Let's remove the deprecated DocBook files. (From yocto-docs rev: 28fb0e63b2fbfd6426b00498bf2682bb53fdd862) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-qa-checks.xml')
-rw-r--r--documentation/ref-manual/ref-qa-checks.xml1225
1 files changed, 0 insertions, 1225 deletions
diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml
deleted file mode 100644
index 0071e4a55d..0000000000
--- a/documentation/ref-manual/ref-qa-checks.xml
+++ /dev/null
@@ -1,1225 +0,0 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
5
6<chapter id='ref-qa-checks'>
7<title>QA Error and Warning Messages</title>
8
9<section id='qa-introduction'>
10 <title>Introduction</title>
11
12 <para>
13 When building a recipe, the OpenEmbedded build system performs
14 various QA checks on the output to ensure that common issues are
15 detected and reported.
16 Sometimes when you create a new recipe to build new software,
17 it will build with no problems.
18 When this is not the case, or when you have QA issues building any
19 software, it could take a little time to resolve them.
20 </para>
21
22 <para>
23 While it is tempting to ignore a QA message or even to
24 disable QA checks, it is best to try and resolve any
25 reported QA issues.
26 This chapter provides a list of the QA messages and brief explanations
27 of the issues you could encounter so that you can properly resolve
28 problems.
29 </para>
30
31 <para>
32 The next section provides a list of all QA error and warning
33 messages based on a default configuration.
34 Each entry provides the message or error form along with an
35 explanation.
36 <note>
37 <title>Notes</title>
38 <itemizedlist>
39 <listitem><para>
40 At the end of each message, the name of the associated
41 QA test (as listed in the
42 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
43 section) appears within square brackets.
44 </para></listitem>
45 <listitem><para>
46 As mentioned, this list of error and warning messages is for
47 QA checks only.
48 The list does not cover all possible build errors or
49 warnings you could encounter.
50 </para></listitem>
51 <listitem><para>
52 Because some QA checks are disabled by default, this list
53 does not include all possible QA check errors and warnings.
54 </para></listitem>
55 </itemizedlist>
56 </note>
57 </para>
58</section>
59
60<section id='qa-errors-and-warnings'>
61 <title>Errors and Warnings</title>
62
63<!--
64This section uses the <para><code> construct to enable permalinks for the
65various QA issue and warning messages. The file templates/qa-code-permalinks.xsl
66is used to locate the construct and generate the permalink. This solution
67leverages the fact that right now this section in the ref-manual is the only
68place is all the YP docs that uses the <para><code> construct. If, in the
69future, that construct were to appear in the ref-manual, a generic permalink
70would be generated for the text between <code></code>. If a better solution
71can be found then it should be implemented. I can't find one at the moment.
72-->
73
74 <para>
75 <itemizedlist>
76 <listitem>
77 <para id='qa-issue-libexec'>
78 <code>
79 &lt;packagename&gt;: &lt;path&gt; is using libexec please relocate to &lt;libexecdir&gt; [libexec]
80 </code>
81 </para>
82
83 <para>
84 The specified package contains files in
85 <filename>/usr/libexec</filename> when the distro
86 configuration uses a different path for
87 <filename>&lt;libexecdir&gt;</filename>
88 By default, <filename>&lt;libexecdir&gt;</filename> is
89 <filename>$prefix/libexec</filename>.
90 However, this default can be changed (e.g.
91 <filename>${libdir}</filename>).
92 </para>
93
94 <para>
95 &nbsp;
96 </para>
97 </listitem>
98 </itemizedlist>
99 </para>
100
101 <para>
102 <itemizedlist>
103 <listitem>
104 <para id='qa-issue-rpaths'>
105 <code>
106 package &lt;packagename&gt; contains bad RPATH &lt;rpath&gt; in file &lt;file&gt; [rpaths]
107 </code>
108 </para>
109
110 <para>
111 The specified binary produced by the recipe contains dynamic
112 library load paths (rpaths) that contain build system paths
113 such as
114 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
115 which are incorrect for the target and could potentially
116 be a security issue.
117 Check for bad <filename>-rpath</filename> options being
118 passed to the linker in your
119 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
120 log.
121 Depending on the build system used by the software being
122 built, there might be a configure option to disable rpath
123 usage completely within the build of the software.
124 </para>
125
126 <para>
127 &nbsp;
128 </para>
129 </listitem>
130 </itemizedlist>
131 </para>
132
133 <para>
134 <itemizedlist>
135 <listitem>
136 <para id='qa-issue-useless-rpaths'>
137 <code>
138 &lt;packagename&gt;: &lt;file&gt; contains probably-redundant RPATH &lt;rpath&gt; [useless-rpaths]
139 </code>
140 </para>
141
142 <para>
143 The specified binary produced by the recipe contains dynamic
144 library load paths (rpaths) that on a standard system are
145 searched by default by the linker (e.g.
146 <filename>/lib</filename> and <filename>/usr/lib</filename>).
147 While these paths will not cause any breakage, they do waste
148 space and are unnecessary.
149 Depending on the build system used by the software being
150 built, there might be a configure option to disable rpath
151 usage completely within the build of the software.
152 </para>
153
154 <para>
155 &nbsp;
156 </para>
157 </listitem>
158 </itemizedlist>
159 </para>
160
161 <para>
162 <itemizedlist>
163 <listitem>
164 <para id='qa-issue-file-rdeps'>
165 <code>
166 &lt;packagename&gt; requires &lt;files&gt;, but no providers in its RDEPENDS [file-rdeps]
167 </code>
168 </para>
169
170 <para>
171 A file-level dependency has been identified from the
172 specified package on the specified files, but there is
173 no explicit corresponding entry in
174 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
175 If particular files are required at runtime then
176 <filename>RDEPENDS</filename> should be declared in the
177 recipe to ensure the packages providing them are built.
178 </para>
179
180 <para>
181 &nbsp;
182 </para>
183 </listitem>
184 </itemizedlist>
185 </para>
186
187 <para>
188 <itemizedlist>
189 <listitem>
190 <para id='qa-issue-build-deps'>
191 <code>
192 &lt;packagename1&gt; rdepends on &lt;packagename2&gt;, but it isn't a build dependency? [build-deps]
193 </code>
194 </para>
195
196 <para>
197 A runtime dependency exists between the two specified
198 packages, but there is nothing explicit within the recipe
199 to enable the OpenEmbedded build system to ensure that
200 dependency is satisfied.
201 This condition is usually triggered by an
202 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
203 value being added at the packaging stage rather than up
204 front, which is usually automatic based on the contents of
205 the package.
206 In most cases, you should change the recipe to add an
207 explicit <filename>RDEPENDS</filename> for the dependency.
208 </para>
209
210 <para>
211 &nbsp;
212 </para>
213 </listitem>
214 </itemizedlist>
215 </para>
216
217 <para>
218 <itemizedlist>
219 <listitem>
220 <para id='qa-issue-dev-so'>
221 <code>
222 non -dev/-dbg/nativesdk- package contains symlink .so: &lt;packagename&gt; path '&lt;path&gt;' [dev-so]
223 </code>
224 </para>
225
226 <para>
227 Symlink <filename>.so</filename> files are for development
228 only, and should therefore go into the
229 <filename>-dev</filename> package.
230 This situation might occur if you add
231 <filename>*.so*</filename> rather than
232 <filename>*.so.*</filename> to a non-dev package.
233 Change
234 <link linkend='var-FILES'><filename>FILES</filename></link>
235 (and possibly
236 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
237 such that the specified <filename>.so</filename> file goes
238 into an appropriate <filename>-dev</filename> package.
239 </para>
240
241 <para>
242 &nbsp;
243 </para>
244 </listitem>
245 </itemizedlist>
246 </para>
247
248 <para>
249 <itemizedlist>
250 <listitem>
251 <para id='qa-issue-staticdev'>
252 <code>
253 non -staticdev package contains static .a library: &lt;packagename&gt; path '&lt;path&gt;' [staticdev]
254 </code>
255 </para>
256
257 <para>
258 Static <filename>.a</filename> library files should go into
259 a <filename>-staticdev</filename> package.
260 Change
261 <link linkend='var-FILES'><filename>FILES</filename></link>
262 (and possibly
263 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
264 such that the specified <filename>.a</filename> file goes
265 into an appropriate <filename>-staticdev</filename> package.
266 </para>
267
268 <para>
269 &nbsp;
270 </para>
271 </listitem>
272 </itemizedlist>
273 </para>
274
275 <para>
276 <itemizedlist>
277 <listitem>
278 <para id='qa-issue-libdir'>
279 <code>
280 &lt;packagename&gt;: found library in wrong location [libdir]
281 </code>
282 </para>
283
284 <para>
285 The specified file may have been installed into an incorrect
286 (possibly hardcoded) installation path.
287 For example, this test will catch recipes that install
288 <filename>/lib/bar.so</filename> when
289 <filename>${base_libdir}</filename> is "lib32".
290 Another example is when recipes install
291 <filename>/usr/lib64/foo.so</filename> when
292 <filename>${libdir}</filename> is "/usr/lib".
293 False positives occasionally exist.
294 For these cases add "libdir" to
295 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
296 for the package.
297 </para>
298
299 <para>
300 &nbsp;
301 </para>
302 </listitem>
303 </itemizedlist>
304 </para>
305
306 <para>
307 <itemizedlist>
308 <listitem>
309 <para id='qa-issue-debug-files'>
310 <code>
311 non debug package contains .debug directory: &lt;packagename&gt; path &lt;path&gt; [debug-files]
312 </code>
313 </para>
314
315 <para>
316 The specified package contains a
317 <filename>.debug</filename> directory, which should not
318 appear in anything but the <filename>-dbg</filename>
319 package.
320 This situation might occur if you add a path which contains
321 a <filename>.debug</filename> directory and do not
322 explicitly add the <filename>.debug</filename> directory
323 to the <filename>-dbg</filename> package.
324 If this is the case, add the <filename>.debug</filename>
325 directory explicitly to
326 <filename>FILES_${PN}-dbg</filename>.
327 See
328 <link linkend='var-FILES'><filename>FILES</filename></link>
329 for additional information on <filename>FILES</filename>.
330 </para>
331
332 <para>
333 &nbsp;
334 </para>
335 </listitem>
336 </itemizedlist>
337 </para>
338
339 <para>
340 <itemizedlist>
341 <listitem>
342 <para id='qa-issue-arch'>
343 <code>
344 Architecture did not match (&lt;machine_arch&gt; to &lt;file_arch&gt;) on &lt;file&gt; [arch]
345 </code>
346 </para>
347
348 <para>
349 By default, the OpenEmbedded build system checks the
350 Executable and Linkable Format (ELF) type, bit size, and
351 endianness of any binaries to ensure they match the
352 target architecture.
353 This test fails if any binaries do not match the type since
354 there would be an incompatibility.
355 The test could indicate that the wrong compiler or compiler
356 options have been used.
357 Sometimes software, like bootloaders, might need to
358 bypass this check.
359 If the file you receive the error for is firmware
360 that is not intended to be executed within the target
361 operating system or is intended to run on a separate
362 processor within the device, you can add "arch" to
363 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
364 for the package.
365 Another option is to check the
366 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
367 log and verify that the compiler options being used
368 are correct.
369 </para>
370
371 <para>
372 &nbsp;
373 </para>
374 </listitem>
375 </itemizedlist>
376 </para>
377
378 <para>
379 <itemizedlist>
380 <listitem>
381 <para id='qa-issue-arch-bit-size-no-match'>
382 <code>
383 Bit size did not match (&lt;machine_bits&gt; to &lt;file_bits&gt;) &lt;recipe&gt; on &lt;file&gt; [arch]
384 </code>
385 </para>
386
387 <para>
388 By default, the OpenEmbedded build system checks
389 the Executable and Linkable Format (ELF) type,
390 bit size, and endianness of any binaries to ensure
391 they match the target architecture.
392 This test fails if any binaries do not match the type since
393 there would be an incompatibility.
394 The test could indicate that the wrong compiler or compiler
395 options have been used.
396 Sometimes software, like bootloaders, might need to
397 bypass this check.
398 If the file you receive the error for is firmware that
399 is not intended to be executed within the target
400 operating system or is intended to run on a separate
401 processor within the device, you can add "arch" to
402 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
403 for the package.
404 Another option is to check the
405 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
406 log and verify that the compiler options being used are
407 correct.
408 </para>
409
410 <para>
411 &nbsp;
412 </para>
413 </listitem>
414 </itemizedlist>
415 </para>
416
417 <para>
418 <itemizedlist>
419 <listitem>
420 <para id='qa-issue-arch-endianness-no-match'>
421 <code>
422 Endianness did not match (&lt;machine_endianness&gt; to &lt;file_endianness&gt;) on &lt;file&gt; [arch]
423 </code>
424 </para>
425
426 <para>
427 By default, the OpenEmbedded build system checks
428 the Executable and Linkable Format (ELF) type, bit
429 size, and endianness of any binaries to ensure they
430 match the target architecture.
431 This test fails if any binaries do not match the type since
432 there would be an incompatibility.
433 The test could indicate that the wrong compiler or compiler
434 options have been used.
435 Sometimes software, like bootloaders, might need to
436 bypass this check.
437 If the file you receive the error for is firmware
438 that is not intended to be executed within the target
439 operating system or is intended to run on a separate
440 processor within the device, you can add "arch" to
441 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
442 for the package.
443 Another option is to check the
444 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
445 log and verify that the compiler options being used
446 are correct.
447 </para>
448
449 <para>
450 &nbsp;
451 </para>
452 </listitem>
453 </itemizedlist>
454 </para>
455
456 <para>
457 <itemizedlist>
458 <listitem>
459 <para id='qa-issue-textrel'>
460 <code>
461 ELF binary '&lt;file&gt;' has relocations in .text [textrel]
462 </code>
463 </para>
464
465 <para>
466 The specified ELF binary contains relocations in its
467 <filename>.text</filename> sections.
468 This situation can result in a performance impact
469 at runtime.
470 </para>
471
472 <para>
473 Typically, the way to solve this performance issue is to
474 add "-fPIC" or "-fpic" to the compiler command-line
475 options.
476 For example, given software that reads
477 <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
478 when you build it, you could add the following to your
479 recipe:
480 <literallayout class='monospaced'>
481 CFLAGS_append = " -fPIC "
482 </literallayout>
483 </para>
484
485 <para>
486 For more information on text relocations at runtime, see
487 <ulink url='http://www.akkadia.org/drepper/textrelocs.html'></ulink>.
488 </para>
489
490 <para>
491 &nbsp;
492 </para>
493 </listitem>
494 </itemizedlist>
495 </para>
496
497 <para>
498 <itemizedlist>
499 <listitem>
500 <para id='qa-issue-ldflags'>
501 <code>
502 No GNU_HASH in the elf binary: '&lt;file&gt;' [ldflags]
503 </code>
504 </para>
505
506 <para>
507 This indicates that binaries produced when building the
508 recipe have not been linked with the
509 <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
510 options provided by the build system.
511 Check to be sure that the <filename>LDFLAGS</filename>
512 variable is being passed to the linker command.
513 A common workaround for this situation is to pass in
514 <filename>LDFLAGS</filename> using
515 <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
516 within the recipe as follows:
517 <literallayout class='monospaced'>
518 TARGET_CC_ARCH += "${LDFLAGS}"
519 </literallayout>
520 </para>
521
522 <para>
523 &nbsp;
524 </para>
525 </listitem>
526 </itemizedlist>
527 </para>
528
529 <para>
530 <itemizedlist>
531 <listitem>
532 <para id='qa-issue-xorg-driver-abi'>
533 <code>
534 Package &lt;packagename&gt; contains Xorg driver (&lt;driver&gt;) but no xorg-abi- dependencies [xorg-driver-abi]
535 </code>
536 </para>
537
538 <para>
539 The specified package contains an Xorg driver, but does not
540 have a corresponding ABI package dependency.
541 The xserver-xorg recipe provides driver ABI names.
542 All drivers should depend on the ABI versions that they have
543 been built against.
544 Driver recipes that include
545 <filename>xorg-driver-input.inc</filename> or
546 <filename>xorg-driver-video.inc</filename> will
547 automatically get these versions.
548 Consequently, you should only need to explicitly add
549 dependencies to binary driver recipes.
550 </para>
551
552 <para>
553 &nbsp;
554 </para>
555 </listitem>
556 </itemizedlist>
557 </para>
558
559 <para>
560 <itemizedlist>
561 <listitem>
562 <para id='qa-issue-infodir'>
563 <code>
564 The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]
565 </code>
566 </para>
567
568 <para>
569 The <filename>/usr/share/info/dir</filename> should not be
570 packaged.
571 Add the following line to your
572 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
573 task or to your <filename>do_install_append</filename>
574 within the recipe as follows:
575 <literallayout class='monospaced'>
576 rm ${D}${infodir}/dir
577 </literallayout>
578 </para>
579
580 <para>
581 &nbsp;
582 </para>
583 </listitem>
584 </itemizedlist>
585 </para>
586
587 <para>
588 <itemizedlist>
589 <listitem>
590 <para id='qa-issue-symlink-to-sysroot'>
591 <code>
592 Symlink &lt;path&gt; in &lt;packagename&gt; points to TMPDIR [symlink-to-sysroot]
593 </code>
594 </para>
595
596 <para>
597 The specified symlink points into
598 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
599 on the host.
600 Such symlinks will work on the host.
601 However, they are clearly invalid when running on
602 the target.
603 You should either correct the symlink to use a relative
604 path or remove the symlink.
605 </para>
606
607 <para>
608 &nbsp;
609 </para>
610 </listitem>
611 </itemizedlist>
612 </para>
613
614 <para>
615 <itemizedlist>
616 <listitem>
617 <para id='qa-issue-la'>
618 <code>
619 &lt;file&gt; failed sanity test (workdir) in path &lt;path&gt; [la]
620 </code>
621 </para>
622
623 <para>
624 The specified <filename>.la</filename> file contains
625 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
626 paths.
627 Any <filename>.la</filename> file containing these paths
628 is incorrect since <filename>libtool</filename> adds the
629 correct sysroot prefix when using the files automatically
630 itself.
631 </para>
632
633 <para>
634 &nbsp;
635 </para>
636 </listitem>
637 </itemizedlist>
638 </para>
639
640 <para>
641 <itemizedlist>
642 <listitem>
643 <para id='qa-issue-pkgconfig'>
644 <code>
645 &lt;file&gt; failed sanity test (tmpdir) in path &lt;path&gt; [pkgconfig]
646 </code>
647 </para>
648
649 <para>
650 The specified <filename>.pc</filename> file contains
651 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
652 paths.
653 Any <filename>.pc</filename> file containing these paths is
654 incorrect since <filename>pkg-config</filename> itself adds
655 the correct sysroot prefix when the files are accessed.
656 </para>
657
658 <para>
659 &nbsp;
660 </para>
661 </listitem>
662 </itemizedlist>
663 </para>
664
665 <para>
666 <itemizedlist>
667 <listitem>
668 <para id='qa-issue-debug-deps'>
669 <code>
670 &lt;packagename&gt; rdepends on &lt;debug_packagename&gt; [debug-deps]
671 </code>
672 </para>
673
674 <para>
675 A dependency exists between the specified non-dbg package
676 (i.e. a package whose name does not end in
677 <filename>-dbg</filename>) and a package that is a
678 <filename>dbg</filename> package.
679 The <filename>dbg</filename> packages contain
680 debug symbols and are brought in using several
681 different methods:
682 <itemizedlist>
683 <listitem><para>
684 Using the <filename>dbg-pkgs</filename>
685 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
686 value.
687 </para></listitem>
688 <listitem><para>
689 Using
690 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
691 </para></listitem>
692 <listitem><para>
693 As a dependency of another
694 <filename>dbg</filename> package that was brought
695 in using one of the above methods.
696 </para></listitem>
697 </itemizedlist>
698 The dependency might have been automatically added
699 because the <filename>dbg</filename> package erroneously
700 contains files that it should not contain (e.g. a
701 non-symlink <filename>.so</filename> file) or it might
702 have been added manually (e.g. by adding to
703 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
704 </para>
705
706 <para>
707 &nbsp;
708 </para>
709 </listitem>
710 </itemizedlist>
711 </para>
712
713 <para>
714 <itemizedlist>
715 <listitem>
716 <para id='qa-issue-dev-deps'>
717 <code>
718 &lt;packagename&gt; rdepends on &lt;dev_packagename&gt; [dev-deps]
719 </code>
720 </para>
721
722 <para>
723 A dependency exists between the specified non-dev package
724 (a package whose name does not end in
725 <filename>-dev</filename>) and a package that is a
726 <filename>dev</filename> package.
727 The <filename>dev</filename> packages contain development
728 headers and are usually brought in using several different
729 methods:
730 <itemizedlist>
731 <listitem><para>
732 Using the <filename>dev-pkgs</filename>
733 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
734 value.
735 </para></listitem>
736 <listitem><para>
737 Using
738 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
739 </para></listitem>
740 <listitem><para>
741 As a dependency of another
742 <filename>dev</filename> package that was brought
743 in using one of the above methods.
744 </para></listitem>
745 </itemizedlist>
746 The dependency might have been automatically added (because
747 the <filename>dev</filename> package erroneously contains
748 files that it should not have (e.g. a non-symlink
749 <filename>.so</filename> file) or it might have been added
750 manually (e.g. by adding to
751 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
752 </para>
753
754 <para>
755 &nbsp;
756 </para>
757 </listitem>
758 </itemizedlist>
759 </para>
760
761 <para>
762 <itemizedlist>
763 <listitem>
764 <para id='qa-issue-dep-cmp'>
765 <code>
766 &lt;var&gt;_&lt;packagename&gt; is invalid: &lt;comparison&gt; (&lt;value&gt;) only comparisons &lt;, =, &gt;, &lt;=, and &gt;= are allowed [dep-cmp]
767 </code>
768 </para>
769
770 <para>
771 If you are adding a versioned dependency relationship to one
772 of the dependency variables
773 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
774 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
775 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
776 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
777 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
778 or
779 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>),
780 you must only use the named comparison operators.
781 Change the versioned dependency values you are adding
782 to match those listed in the message.
783 </para>
784
785 <para>
786 &nbsp;
787 </para>
788 </listitem>
789 </itemizedlist>
790 </para>
791
792 <para>
793 <itemizedlist>
794 <listitem>
795 <para id='qa-issue-compile-host-path'>
796 <code>
797 &lt;recipename&gt;: The compile log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' for more information. [compile-host-path]
798 </code>
799 </para>
800
801 <para>
802 The log for the
803 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
804 task indicates that paths on the host were searched
805 for files, which is not appropriate when cross-compiling.
806 Look for "is unsafe for cross-compilation" or "CROSS COMPILE
807 Badness" in the specified log file.
808 </para>
809
810 <para>
811 &nbsp;
812 </para>
813 </listitem>
814 </itemizedlist>
815 </para>
816
817 <para>
818 <itemizedlist>
819 <listitem>
820 <para id='qa-issue-install-host-path'>
821 <code>
822 &lt;recipename&gt;: The install log indicates that host include and/or library paths were used. Please check the log '&lt;logfile&gt;' for more information. [install-host-path]
823 </code>
824 </para>
825
826 <para>
827 The log for the
828 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
829 task indicates that paths on the host were searched
830 for files, which is not appropriate when cross-compiling.
831 Look for "is unsafe for cross-compilation"
832 or "CROSS COMPILE Badness" in the specified log file.
833 </para>
834
835 <para>
836 &nbsp;
837 </para>
838 </listitem>
839 </itemizedlist>
840 </para>
841
842 <para>
843 <itemizedlist>
844 <listitem>
845 <para id='qa-issue-autoconf-log'>
846 <code>
847 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 '&lt;path&gt;'
848 </code>
849 </para>
850
851 <para>
852 The log for the
853 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
854 task indicates that paths on the host were searched
855 for files, which is not appropriate when cross-compiling.
856 Look for "is unsafe for cross-compilation" or
857 "CROSS COMPILE Badness" in the specified log file.
858 </para>
859
860 <para>
861 &nbsp;
862 </para>
863 </listitem>
864 </itemizedlist>
865 </para>
866
867 <para>
868 <itemizedlist>
869 <listitem>
870 <para id='qa-issue-pkgname'>
871 <code>
872 &lt;packagename&gt; doesn't match the [a-z0-9.+-]+ regex [pkgname]
873 </code>
874 </para>
875
876 <para>
877 The convention within the OpenEmbedded build system
878 (sometimes enforced by the package manager itself) is to
879 require that package names are all lower case
880 and to allow a restricted set of characters.
881 If your recipe name does not match this, or you add
882 packages to
883 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
884 that do not conform to the convention, then you
885 will receive this error.
886 Rename your recipe.
887 Or, if you have added a non-conforming package name to
888 <filename>PACKAGES</filename>, change the package name
889 appropriately.
890 </para>
891
892 <para>
893 &nbsp;
894 </para>
895 </listitem>
896 </itemizedlist>
897 </para>
898
899 <para>
900 <itemizedlist>
901 <listitem>
902 <para id='qa-issue-unknown-configure-option'>
903 <code>
904 &lt;recipe&gt;: configure was passed unrecognized options: &lt;options&gt; [unknown-configure-option]
905 </code>
906 </para>
907
908 <para>
909 The configure script is reporting that the specified
910 options are unrecognized.
911 This situation could be because the options
912 were previously valid but have been removed from the
913 configure script.
914 Or, there was a mistake when the options were added
915 and there is another option that should be used instead.
916 If you are unsure, consult the upstream build
917 documentation, the
918 <filename>./configure --help</filename> output,
919 and the upstream change log or release notes.
920 Once you have worked out what the appropriate
921 change is, you can update
922 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>,
923 <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>,
924 or the individual
925 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
926 option values accordingly.
927 </para>
928
929 <para>
930 &nbsp;
931 </para>
932 </listitem>
933 </itemizedlist>
934 </para>
935
936 <para>
937 <itemizedlist>
938 <listitem>
939 <para id='qa-issue-pn-overrides'>
940 <code>
941 Recipe &lt;recipefile&gt; has PN of "&lt;recipename&gt;" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]
942 </code>
943 </para>
944
945 <para>
946 The specified recipe has a name
947 (<link linkend='var-PN'><filename>PN</filename></link>)
948 value that appears in
949 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
950 If a recipe is named such that its <filename>PN</filename>
951 value matches something already in
952 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
953 happens to be the same as
954 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
955 or
956 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
957 it can have unexpected consequences.
958 For example, assignments such as
959 <filename>FILES_${PN} = "xyz"</filename> effectively
960 turn into <filename>FILES = "xyz"</filename>.
961 Rename your recipe (or if <filename>PN</filename> is being
962 set explicitly, change the <filename>PN</filename> value) so
963 that the conflict does not occur.
964 See
965 <link linkend='var-FILES'><filename>FILES</filename></link>
966 for additional information.
967 </para>
968
969 <para>
970 &nbsp;
971 </para>
972 </listitem>
973 </itemizedlist>
974 </para>
975
976 <para>
977 <itemizedlist>
978 <listitem>
979 <para id='qa-issue-pkgvarcheck'>
980 <code>
981 &lt;recipefile&gt;: Variable &lt;variable&gt; is set as not being package specific, please fix this. [pkgvarcheck]
982 </code>
983 </para>
984
985 <para>
986 Certain variables
987 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
988 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
989 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
990 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
991 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
992 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
993 <link linkend='var-FILES'><filename>FILES</filename></link>,
994 <filename>pkg_preinst</filename>,
995 <filename>pkg_postinst</filename>,
996 <filename>pkg_prerm</filename>,
997 <filename>pkg_postrm</filename>, and
998 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>)
999 should always be set specific to a package (i.e. they
1000 should be set with a package name override such as
1001 <filename>RDEPENDS_${PN} = "value"</filename> rather than
1002 <filename>RDEPENDS = "value"</filename>).
1003 If you receive this error, correct any assignments to these
1004 variables within your recipe.
1005 </para>
1006
1007 <para>
1008 &nbsp;
1009 </para>
1010 </listitem>
1011 </itemizedlist>
1012 </para>
1013
1014 <para>
1015 <itemizedlist>
1016 <listitem>
1017 <para id='qa-issue-already-stripped'>
1018 <code>
1019 File '&lt;file&gt;' from &lt;recipename&gt; was already stripped, this will prevent future debugging! [already-stripped]
1020 </code>
1021 </para>
1022
1023 <para>
1024 Produced binaries have already been stripped prior to the
1025 build system extracting debug symbols.
1026 It is common for upstream software projects to default to
1027 stripping debug symbols for output binaries.
1028 In order for debugging to work on the target using
1029 <filename>-dbg</filename> packages, this stripping must be
1030 disabled.
1031 </para>
1032
1033 <para>
1034 Depending on the build system used by the software being
1035 built, disabling this stripping could be as easy as
1036 specifying an additional configure option.
1037 If not, disabling stripping might involve patching
1038 the build scripts.
1039 In the latter case, look for references to "strip" or
1040 "STRIP", or the "-s" or "-S" command-line options being
1041 specified on the linker command line (possibly
1042 through the compiler command line if preceded with "-Wl,").
1043 <note>
1044 Disabling stripping here does not mean that the final
1045 packaged binaries will be unstripped.
1046 Once the OpenEmbedded build system splits out debug
1047 symbols to the <filename>-dbg</filename> package,
1048 it will then strip the symbols from the binaries.
1049 </note>
1050 </para>
1051
1052 <para>
1053 &nbsp;
1054 </para>
1055 </listitem>
1056 </itemizedlist>
1057 </para>
1058
1059 <para>
1060 <itemizedlist>
1061 <listitem>
1062 <para id='qa-issue-packages-list'>
1063 <code>
1064 &lt;packagename&gt; is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]
1065 </code>
1066 </para>
1067
1068 <para>
1069 Package names must appear only once in the
1070 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
1071 variable.
1072 You might receive this error if you are attempting to add a
1073 package to <filename>PACKAGES</filename> that is
1074 already in the variable's value.
1075 </para>
1076
1077 <para>
1078 &nbsp;
1079 </para>
1080 </listitem>
1081 </itemizedlist>
1082 </para>
1083
1084 <para>
1085 <itemizedlist>
1086 <listitem>
1087 <para id='qa-issue-files-invalid'>
1088 <code>
1089 FILES variable for package &lt;packagename&gt; contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]
1090 </code>
1091 </para>
1092
1093 <para>
1094 The string "//" is invalid in a Unix path.
1095 Correct all occurrences where this string appears in a
1096 <link linkend='var-FILES'><filename>FILES</filename></link>
1097 variable so that there is only a single "/".
1098 </para>
1099
1100 <para>
1101 &nbsp;
1102 </para>
1103 </listitem>
1104 </itemizedlist>
1105 </para>
1106
1107 <para>
1108 <itemizedlist>
1109 <listitem>
1110 <para id='qa-issue-installed-vs-shipped'>
1111 <code>
1112 &lt;recipename&gt;: Files/directories were installed but not shipped in any package [installed-vs-shipped]
1113 </code>
1114 </para>
1115
1116 <para>
1117 Files have been installed within the
1118 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
1119 task but have not been included in any package by way of the
1120 <link linkend='var-FILES'><filename>FILES</filename></link>
1121 variable.
1122 Files that do not appear in any package cannot be present in
1123 an image later on in the build process.
1124 You need to do one of the following:
1125 <itemizedlist>
1126 <listitem><para>
1127 Add the files to <filename>FILES</filename> for the
1128 package you want them to appear in (e.g.
1129 <filename>FILES_${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> for the main
1130 package).
1131 </para></listitem>
1132 <listitem><para>
1133 Delete the files at the end of the
1134 <filename>do_install</filename> task if the files
1135 are not needed in any package.
1136 </para></listitem>
1137 </itemizedlist>
1138 </para>
1139
1140 <para>
1141 &nbsp;
1142 </para>
1143 </listitem>
1144 </itemizedlist>
1145 </para>
1146
1147 <para>
1148 <itemizedlist>
1149 <listitem>
1150 <para id='qa-issue-old-and-new-package-and-version-names'>
1151 <code>
1152 &lt;oldpackage&gt;-&lt;oldpkgversion&gt; was registered as shlib provider for &lt;library&gt;, changing it to &lt;newpackage&gt;-&lt;newpkgversion&gt; because it was built later
1153 </code>
1154 </para>
1155
1156 <para>
1157 This message means that both
1158 <filename>&lt;oldpackage&gt;</filename> and
1159 <filename>&lt;newpackage&gt;</filename> provide the specified
1160 shared library.
1161 You can expect this message when a recipe has been renamed.
1162 However, if that is not the case, the message might indicate
1163 that a private version of a library is being erroneously
1164 picked up as the provider for a common library.
1165 If that is the case, you should add the library's
1166 <filename>.so</filename> file name to
1167 <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
1168 in the recipe that provides
1169 the private version of the library.
1170 </para>
1171 </listitem>
1172 </itemizedlist>
1173 </para>
1174
1175 <para>
1176 <itemizedlist>
1177 <listitem>
1178 <para id='qa-issue-unlisted-pkg-lics'>
1179 <code>
1180 LICENSE_&lt;packagename&gt; includes licenses (&lt;licenses&gt;) that are not listed in LICENSE [unlisted-pkg-lics]
1181 </code>
1182 </para>
1183
1184 <para>
1185 The <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
1186 of the recipe should be a superset of all the licenses of
1187 all packages produced by this recipe.
1188 In other words, any license in <filename>LICENSE_*</filename>
1189 should also appear in
1190 <link linkend='var-LICENSE'><filename>LICENSE</filename></link>.
1191 </para>
1192
1193 <para>
1194 &nbsp;
1195 </para>
1196 </listitem>
1197 </itemizedlist>
1198 </para>
1199</section>
1200
1201<section id='configuring-and-disabling-qa-checks'>
1202 <title>Configuring and Disabling QA Checks</title>
1203
1204 <para>
1205 You can configure the QA checks globally so that specific check
1206 failures either raise a warning or an error message, using the
1207 <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
1208 <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
1209 variables, respectively.
1210 You can also disable checks within a particular recipe using
1211 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
1212 For information on how to work with the QA checks, see the
1213 "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
1214 section.
1215 <note><title>Tip</title>
1216 Please keep in mind that the QA checks exist in order to
1217 detect real or potential problems in the packaged output.
1218 So exercise caution when disabling these checks.
1219 </note>
1220 </para>
1221</section>
1222</chapter>
1223<!--
1224vim: expandtab tw=80 ts=4
1225-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-08-05 21:49:46 +0000