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