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