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