summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-qa-checks.xml
blob: 424a19c59d43e2a2fec1c6aa95fde603dc5b244a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >

<chapter id='ref-qa-checks'>
<title>QA Error and Warning Messages</title>

<section id='qa-introduction'>
    <title>Introduction</title>

    <para>
        When building a recipe, the OpenEmbedded build system performs
        various QA checks on the output to ensure that common issues are
        detected and reported.
        Sometimes when you create a new recipe to build new software,
        it will build with no problems.
        When this is not the case, or when you have QA issues building any
        software, it could take a little time to resolve them.
    </para>

    <para>
        While it is tempting to ignore a QA message or even to
        disable QA checks, it is best to try and resolve any
        reported QA issues.
        This chapter provides a list of the QA messages and brief explanations
        of the issues you could encounter so that you can properly resolve
        problems.
    </para>

    <para>
        The next section provides a list of all QA error and warning
        messages based on a default configuration.
        Each entry provides the message or error form along with an
        explanation.
        <note>
            <title>Notes</title>
            <itemizedlist>
                <listitem><para>
                    At the end of each message, the name of the associated
                    QA test (as listed in the
                    "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
                    section) appears within square brackets.
                    </para></listitem>
                <listitem><para>
                    As mentioned, this list of error and warning messages is for
                    QA checks only.
                    The list does not cover all possible build errors or
                    warnings you could encounter.
                    </para></listitem>
                <listitem><para>
                    Because some QA checks are disabled by default, this list
                    does not include all possible QA check errors and warnings.
                    </para></listitem>
            </itemizedlist>
        </note>
    </para>
</section>

<section id='qa-errors-and-warnings'>
    <title>Errors and Warnings</title>

<!--
This section uses the <para><code> construct to enable permalinks for the
various QA issue and warning messages.  The file templates/qa-code-permalinks.xsl
is used to locate the construct and generate the permalink.  This solution
leverages the fact that right now this section in the ref-manual is the only
place is all the YP docs that uses the <para><code> construct.  If, in the
future, that construct were to appear in the ref-manual, a generic permalink
would be generated for the text between <code></code>.  If a better solution
can be found then it should be implemented.  I can't find one at the moment.
-->

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-libexec'>
                    <code>
     &lt;packagename&gt;: &lt;path&gt; is using libexec please relocate to &lt;libexecdir&gt; [libexec]
                    </code>
                </para>

                <para>
                    The specified package contains files in
                    <filename>/usr/libexec</filename> when the distro
                    configuration uses a different path for
                    <filename>&lt;libexecdir&gt;</filename>
                    By default, <filename>&lt;libexecdir&gt;</filename> is
                    <filename>$prefix/libexec</filename>.
                    However, this default can be changed (e.g.
                    <filename>${libdir}</filename>).
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-rpaths'>
                    <code>
     package &lt;packagename&gt; contains bad RPATH &lt;rpath&gt; in file &lt;file&gt; [rpaths]
                    </code>
                </para>

                <para>
                    The specified binary produced by the recipe contains dynamic
                    library load paths (rpaths) that contain build system paths
                    such as
                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
                    which are incorrect for the target and could potentially
                    be a security issue.
                    Check for bad <filename>-rpath</filename> options being
                    passed to the linker in your
                    <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
                    log.
                    Depending on the build system used by the software being
                    built, there might be a configure option to disable rpath
                    usage completely within the build of the software.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-useless-rpaths'>
                    <code>
     &lt;packagename&gt;: &lt;file&gt; contains probably-redundant RPATH &lt;rpath&gt; [useless-rpaths]
                    </code>
                </para>

                <para>
                    The specified binary produced by the recipe contains dynamic
                    library load paths (rpaths) that on a standard system are
                    searched by default by the linker (e.g.
                    <filename>/lib</filename> and <filename>/usr/lib</filename>).
                    While these paths will not cause any breakage, they do waste
                    space and are unnecessary.
                    Depending on the build system used by the software being
                    built, there might be a configure option to disable rpath
                    usage completely within the build of the software.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-file-rdeps'>
                    <code>
     &lt;packagename&gt; requires &lt;files&gt;, but no providers in its RDEPENDS [file-rdeps]
                    </code>
                </para>

                <para>
                    A file-level dependency has been identified from the
                    specified package on the specified files, but there is
                    no explicit corresponding entry in
                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
                    If particular files are required at runtime then
                    <filename>RDEPENDS</filename> should be declared in the
                    recipe to ensure the packages providing them are built.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-build-deps'>
                    <code>
     &lt;packagename1&gt; rdepends on &lt;packagename2&gt;, but it isn't a build dependency? [build-deps]
                    </code>
                </para>

                <para>
                    A runtime dependency exists between the two specified
                    packages, but there is nothing explicit within the recipe
                    to enable the OpenEmbedded build system to ensure that
                    dependency is satisfied.
                    This condition is usually triggered by an
                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
                    value being added at the packaging stage rather than up
                    front, which is usually automatic based on the contents of
                    the package.
                    In most cases, you should change the recipe to add an
                    explicit <filename>RDEPENDS</filename> for the dependency.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-dev-so'>
                    <code>
     non -dev/-dbg/nativesdk- package contains symlink .so: &lt;packagename&gt; path '&lt;path&gt;' [dev-so]
                    </code>
                </para>

                <para>
                    Symlink <filename>.so</filename> files are for development
                    only, and should therefore go into the
                    <filename>-dev</filename> package.
                    This situation might occur if you add
                    <filename>*.so*</filename> rather than
                    <filename>*.so.*</filename> to a non-dev package.
                    Change
                    <link linkend='var-FILES'><filename>FILES</filename></link>
                    (and possibly
                    <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
                    such that the specified <filename>.so</filename> file goes
                    into an appropriate <filename>-dev</filename> package.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-staticdev'>
                    <code>
     non -staticdev package contains static .a library: &lt;packagename&gt; path '&lt;path&gt;' [staticdev]
                    </code>
                </para>

                <para>
                    Static <filename>.a</filename> library files should go into
                    a <filename>-staticdev</filename> package.
                    Change
                    <link linkend='var-FILES'><filename>FILES</filename></link>
                    (and possibly
                    <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
                    such that the specified <filename>.a</filename> file goes
                    into an appropriate <filename>-staticdev</filename> package.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-libdir'>
                    <code>
     &lt;packagename&gt;: found library in wrong location [libdir]
                    </code>
                </para>

                <para>
                    The specified file may have been installed into an incorrect
                    (possibly hardcoded) installation path.
                    For example, this test will catch recipes that install
                    <filename>/lib/bar.so</filename> when
                    <filename>${base_libdir}</filename> is "lib32".
                    Another example is when recipes install
                    <filename>/usr/lib64/foo.so</filename> when
                    <filename>${libdir}</filename> is "/usr/lib".
                    False positives occasionally exist.
                    For these cases add "libdir" to
                    <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
                    for the package.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-debug-files'>
                    <code>
     non debug package contains .debug directory: &lt;packagename&gt; path &lt;path&gt; [debug-files]
                    </code>
                </para>

                <para>
                    The specified package contains a
                    <filename>.debug</filename> directory, which should not
                    appear in anything but the <filename>-dbg</filename>
                    package.
                    This situation might occur if you add a path which contains
                    a <filename>.debug</filename> directory and do not
                    explicitly add the <filename>.debug</filename> directory
                    to the <filename>-dbg</filename> package.
                    If this is the case, add the <filename>.debug</filename>
                    directory explicitly to
                    <filename>FILES_${PN}-dbg</filename>.
                    See
                    <link linkend='var-FILES'><filename>FILES</filename></link>
                    for additional information on <filename>FILES</filename>.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-arch'>
                    <code>
     Architecture did not match (&lt;machine_arch&gt; to &lt;file_arch&gt;) on &lt;file&gt; [arch]
                    </code>
                </para>

                <para>
                    By default, the OpenEmbedded build system checks the
                    Executable and Linkable Format (ELF) type, bit size, and
                    endianness of any binaries to ensure they match the
                    target architecture.
                    This test fails if any binaries do not match the type since
                    there would be an incompatibility.
                    The test could indicate that the wrong compiler or compiler
                    options have been used.
                    Sometimes software, like bootloaders, might need to
                    bypass this check.
                    If the file you receive the error for is firmware
                    that is not intended to be executed within the target
                    operating system or is intended to run on a separate
                    processor within the device, you can add "arch" to
                    <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
                    for the package.
                    Another option is to check the
                    <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
                    log and verify that the compiler options being used
                    are correct.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-arch-bit-size-no-match'>
                    <code>
     Bit size did not match (&lt;machine_bits&gt; to &lt;file_bits&gt;) &lt;recipe&gt; on &lt;file&gt; [arch]
                    </code>
                </para>

                <para>
                    By default, the OpenEmbedded build system checks
                    the Executable and Linkable Format (ELF) type,
                    bit size, and endianness of any binaries to ensure
                    they match the target architecture.
                    This test fails if any binaries do not match the type since
                    there would be an incompatibility.
                    The test could indicate that the wrong compiler or compiler
                    options have been used.
                    Sometimes software, like bootloaders, might need to
                    bypass this check.
                    If the file you receive the error for is firmware that
                    is not intended to be executed within the target
                    operating system or is intended to run on a separate
                    processor within the device, you can add "arch" to
                    <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
                    for the package.
                    Another option is to check the
                    <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
                    log and verify that the compiler options being used are
                    correct.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-arch-endianness-no-match'>
                    <code>
     Endianness did not match (&lt;machine_endianness&gt; to &lt;file_endianness&gt;) on &lt;file&gt; [arch]
                    </code>
                </para>

                <para>
                    By default, the OpenEmbedded build system checks
                    the Executable and Linkable Format (ELF) type, bit
                    size, and endianness of any binaries to ensure they
                    match the target architecture.
                    This test fails if any binaries do not match the type since
                    there would be an incompatibility.
                    The test could indicate that the wrong compiler or compiler
                    options have been used.
                    Sometimes software, like bootloaders, might need to
                    bypass this check.
                    If the file you receive the error for is firmware
                    that is not intended to be executed within the target
                    operating system or is intended to run on a separate
                    processor within the device, you can add "arch" to
                    <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
                    for the package.
                    Another option is to check the
                    <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
                    log and verify that the compiler options being used
                    are correct.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-textrel'>
                    <code>
     ELF binary '&lt;file&gt;' has relocations in .text [textrel]
                    </code>
                </para>

                <para>
                    The specified ELF binary contains relocations in its
                    <filename>.text</filename> sections.
                    This situation can result in a performance impact
                    at runtime.
                </para>

                <para>
                    Typically, the way to solve this performance issue is to
                    add "-fPIC" or "-fpic" to the compiler command-line
                    options.
                    For example, given software that reads
                    <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link>
                    when you build it, you could add the following to your
                    recipe:
                    <literallayout class='monospaced'>
     CFLAGS_append = " -fPIC "
                    </literallayout>
                </para>

                <para>
                    For more information on text relocations at runtime, see
                    <ulink url='http://www.akkadia.org/drepper/textrelocs.html'></ulink>.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-ldflags'>
                    <code>
     No GNU_HASH in the elf binary: '&lt;file&gt;' [ldflags]
                    </code>
                </para>

                <para>
                    This indicates that binaries produced when building the
                    recipe have not been linked with the
                    <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>
                    options provided by the build system.
                    Check to be sure that the <filename>LDFLAGS</filename>
                    variable is being passed to the linker command.
                    A common workaround for this situation is to pass in
                    <filename>LDFLAGS</filename> using
                    <link linkend='var-TARGET_CC_ARCH'><filename>TARGET_CC_ARCH</filename></link>
                    within the recipe as follows:
                    <literallayout class='monospaced'>
     TARGET_CC_ARCH += "${LDFLAGS}"
                    </literallayout>
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-xorg-driver-abi'>
                    <code>
     Package &lt;packagename&gt; contains Xorg driver (&lt;driver&gt;) but no xorg-abi- dependencies [xorg-driver-abi]
                    </code>
                </para>

                <para>
                    The specified package contains an Xorg driver, but does not
                    have a corresponding ABI package dependency.
                    The xserver-xorg recipe provides driver ABI names.
                    All drivers should depend on the ABI versions that they have
                    been built against.
                    Driver recipes that include
                    <filename>xorg-driver-input.inc</filename> or
                    <filename>xorg-driver-video.inc</filename> will
                    automatically get these versions.
                    Consequently, you should only need to explicitly add
                    dependencies to binary driver recipes.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-infodir'>
                    <code>
     The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]
                    </code>
                </para>

                <para>
                    The <filename>/usr/share/info/dir</filename> should not be
                    packaged.
                    Add the following line to your
                    <link linkend='ref-tasks-install'><filename>do_install</filename></link>
                    task or to your <filename>do_install_append</filename>
                    within the recipe as follows:
                    <literallayout class='monospaced'>
     rm ${D}${infodir}/dir
                    </literallayout>
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-symlink-to-sysroot'>
                    <code>
     Symlink &lt;path&gt; in &lt;packagename&gt; points to TMPDIR [symlink-to-sysroot]
                    </code>
                </para>

                <para>
                    The specified symlink points into
                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
                    on the host.
                    Such symlinks will work on the host.
                    However, they are clearly invalid when running on
                    the target.
                    You should either correct the symlink to use a relative
                    path or remove the symlink.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-la'>
                    <code>
     &lt;file&gt; failed sanity test (workdir) in path &lt;path&gt; [la]
                    </code>
                </para>

                <para>
                    The specified <filename>.la</filename> file contains
                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
                    paths.
                    Any <filename>.la</filename> file containing these paths
                    is incorrect since <filename>libtool</filename> adds the
                    correct sysroot prefix when using the files automatically
                    itself.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-pkgconfig'>
                    <code>
     &lt;file&gt; failed sanity test (tmpdir) in path &lt;path&gt; [pkgconfig]
                    </code>
                </para>

                <para>
                    The specified <filename>.pc</filename> file contains
                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
                    paths.
                    Any <filename>.pc</filename> file containing these paths is
                    incorrect since <filename>pkg-config</filename> itself adds
                    the correct sysroot prefix when the files are accessed.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-debug-deps'>
                    <code>
     &lt;packagename&gt; rdepends on &lt;debug_packagename&gt; [debug-deps]
                    </code>
                </para>

                <para>
                    A dependency exists between the specified non-dbg package
                    (i.e. a package whose name does not end in
                    <filename>-dbg</filename>) and a package that is a
                    <filename>dbg</filename> package.
                    The <filename>dbg</filename> packages contain
                    debug symbols and are brought in using several
                    different methods:
                    <itemizedlist>
                        <listitem><para>
                            Using the <filename>dbg-pkgs</filename>
                            <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
                            value.
                            </para></listitem>
                        <listitem><para>
                            Using
                            <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
                            </para></listitem>
                        <listitem><para>
                            As a dependency of another
                            <filename>dbg</filename> package that was brought
                            in using one of the above methods.
                            </para></listitem>
                    </itemizedlist>
                    The dependency might have been automatically added
                    because the <filename>dbg</filename> package erroneously
                    contains files that it should not contain (e.g. a
                    non-symlink <filename>.so</filename> file) or it might
                    have been added manually (e.g. by adding to
                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-dev-deps'>
                    <code>
     &lt;packagename&gt; rdepends on &lt;dev_packagename&gt; [dev-deps]
                    </code>
                </para>

                <para>
                    A dependency exists between the specified non-dev package
                    (a package whose name does not end in
                    <filename>-dev</filename>) and a package that is a
                    <filename>dev</filename> package.
                    The <filename>dev</filename> packages contain development
                    headers and are usually brought in using several different
                    methods:
                    <itemizedlist>
                        <listitem><para>
                            Using the <filename>dev-pkgs</filename>
                            <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
                            value.
                            </para></listitem>
                        <listitem><para>
                            Using
                            <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>.
                            </para></listitem>
                        <listitem><para>
                            As a dependency of another
                            <filename>dev</filename> package that was brought
                            in using one of the above methods.
                            </para></listitem>
                    </itemizedlist>
                    The dependency might have been automatically added (because
                    the <filename>dev</filename> package erroneously contains
                    files that it should not have (e.g. a non-symlink
                    <filename>.so</filename> file) or it might have been added
                    manually (e.g. by adding to
                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>).
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-dep-cmp'>
                    <code>
     &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]
                    </code>
                </para>

                <para>
                    If you are adding a versioned dependency relationship to one
                    of the dependency variables
                    (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
                    <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
                    <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
                    <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
                    or
                    <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>),
                    you must only use the named comparison operators.
                    Change the versioned dependency values you are adding
                    to match those listed in the message.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-compile-host-path'>
                    <code>
     &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]
                    </code>
                </para>

                <para>
                    The log for the
                    <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
                    task indicates that paths on the host were searched
                    for files, which is not appropriate when cross-compiling.
                    Look for "is unsafe for cross-compilation" or "CROSS COMPILE
                    Badness" in the specified log file.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-install-host-path'>
                    <code>
     &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]
                    </code>
                </para>

                <para>
                    The log for the
                    <link linkend='ref-tasks-install'><filename>do_install</filename></link>
                    task indicates that paths on the host were searched
                    for files, which is not appropriate when cross-compiling.
                    Look for "is unsafe for cross-compilation"
                    or "CROSS COMPILE Badness" in the specified log file.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-autoconf-log'>
                    <code>
     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;'
                    </code>
                </para>

                <para>
                    The log for the
                    <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
                    task indicates that paths on the host were searched
                    for files, which is not appropriate when cross-compiling.
                    Look for "is unsafe for cross-compilation" or
                    "CROSS COMPILE Badness" in the specified log file.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-pkgname'>
                    <code>
     &lt;packagename&gt; doesn't match the [a-z0-9.+-]+ regex [pkgname]
                    </code>
                </para>

                <para>
                    The convention within the OpenEmbedded build system
                    (sometimes enforced by the package manager itself) is to
                    require that package names are all lower case
                    and to allow a restricted set of characters.
                    If your recipe name does not match this, or you add
                    packages to
                    <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
                    that do not conform to the convention, then you
                    will receive this error.
                    Rename your recipe.
                    Or, if you have added a non-conforming package name to
                    <filename>PACKAGES</filename>, change the package name
                    appropriately.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-unknown-configure-option'>
                    <code>
     &lt;recipe&gt;: configure was passed unrecognized options: &lt;options&gt; [unknown-configure-option]
                    </code>
                </para>

                <para>
                    The configure script is reporting that the specified
                    options are unrecognized.
                    This situation could be because the options
                    were previously valid but have been removed from the
                    configure script.
                    Or, there was a mistake when the options were added
                    and there is another option that should be used instead.
                    If you are unsure, consult the upstream build
                    documentation, the
                    <filename>./configure --help</filename> output,
                    and the upstream change log or release notes.
                    Once you have worked out what the appropriate
                    change is, you can update
                    <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>,
                    <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>,
                    or the individual
                    <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
                    option values accordingly.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-pn-overrides'>
                    <code>
     Recipe &lt;recipefile&gt; has PN of "&lt;recipename&gt;" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]
                    </code>
                </para>

                <para>
                    The specified recipe has a name
                    (<link linkend='var-PN'><filename>PN</filename></link>)
                    value that appears in
                    <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
                    If a recipe is named such that its <filename>PN</filename>
                    value matches something already in
                    <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
                    happens to be the same as
                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
                    or
                    <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
                    it can have unexpected consequences.
                    For example, assignments such as
                    <filename>FILES_${PN} = "xyz"</filename> effectively
                    turn into <filename>FILES = "xyz"</filename>.
                    Rename your recipe (or if <filename>PN</filename> is being
                    set explicitly, change the <filename>PN</filename> value) so
                    that the conflict does not occur.
                    See
                    <link linkend='var-FILES'><filename>FILES</filename></link>
                    for additional information.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-pkgvarcheck'>
                    <code>
     &lt;recipefile&gt;: Variable &lt;variable&gt; is set as not being package specific, please fix this. [pkgvarcheck]
                    </code>
                </para>

                <para>
                    Certain variables
                    (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
                    <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
                    <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
                    <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
                    <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
                    <link linkend='var-FILES'><filename>FILES</filename></link>,
                    <filename>pkg_preinst</filename>,
                    <filename>pkg_postinst</filename>,
                    <filename>pkg_prerm</filename>,
                    <filename>pkg_postrm</filename>, and
                    <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>)
                    should always be set specific to a package (i.e. they
                    should be set with a package name override such as
                    <filename>RDEPENDS_${PN} = "value"</filename> rather than
                    <filename>RDEPENDS = "value"</filename>).
                    If you receive this error, correct any assignments to these
                    variables within your recipe.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-already-stripped'>
                    <code>
     File '&lt;file&gt;' from &lt;recipename&gt; was already stripped, this will prevent future debugging! [already-stripped]
                    </code>
                </para>

                <para>
                    Produced binaries have already been stripped prior to the
                    build system extracting debug symbols.
                    It is common for upstream software projects to default to
                    stripping debug symbols for output binaries.
                    In order for debugging to work on the target using
                    <filename>-dbg</filename> packages, this stripping must be
                    disabled.
                </para>

                <para>
                    Depending on the build system used by the software being
                    built, disabling this stripping could be as easy as
                    specifying an additional configure option.
                    If not, disabling stripping might involve patching
                    the build scripts.
                    In the latter case, look for references to "strip" or
                    "STRIP", or the "-s" or "-S" command-line options being
                    specified on the linker command line (possibly
                    through the compiler command line if preceded with "-Wl,").
                    <note>
                        Disabling stripping here does not mean that the final
                        packaged binaries will be unstripped.
                        Once the OpenEmbedded build system splits out debug
                        symbols to the <filename>-dbg</filename> package,
                        it will then strip the symbols from the binaries.
                    </note>
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-packages-list'>
                    <code>
     &lt;packagename&gt; is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]
                    </code>
                </para>

                <para>
                    Package names must appear only once in the
                    <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
                    variable.
                    You might receive this error if you are attempting to add a
                    package to <filename>PACKAGES</filename> that is
                    already in the variable's value.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-files-invalid'>
                    <code>
     FILES variable for package &lt;packagename&gt; contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]
                    </code>
                </para>

                <para>
                    The string "//" is invalid in a Unix path.
                    Correct all occurrences where this string appears in a
                    <link linkend='var-FILES'><filename>FILES</filename></link>
                    variable so that there is only a single "/".
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-installed-vs-shipped'>
                    <code>
      &lt;recipename&gt;: Files/directories were installed but not shipped in any package [installed-vs-shipped]
                    </code>
                </para>

                <para>
                    Files have been installed within the
                    <link linkend='ref-tasks-install'><filename>do_install</filename></link>
                    task but have not been included in any package by way of the
                    <link linkend='var-FILES'><filename>FILES</filename></link>
                    variable.
                    Files that do not appear in any package cannot be present in
                    an image later on in the build process.
                    You need to do one of the following:
                    <itemizedlist>
                        <listitem><para>
                            Add the files to <filename>FILES</filename> for the
                            package you want them to appear in (e.g.
                            <filename>FILES_${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> for the main
                            package).
                            </para></listitem>
                        <listitem><para>
                            Delete the files at the end of the
                            <filename>do_install</filename> task if the files
                            are not needed in any package.
                            </para></listitem>
                    </itemizedlist>
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-old-and-new-package-and-version-names'>
                    <code>
     &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
                    </code>
                </para>

                <para>
                    This message means that both
                    <filename>&lt;oldpackage&gt;</filename> and
                    <filename>&lt;newpackage&gt;</filename> provide the specified
                    shared library.
                    You can expect this message when a recipe has been renamed.
                    However, if that is not the case, the message might indicate
                    that a private version of a library is being erroneously
                    picked up as the provider for a common library.
                    If that is the case, you should add the library's
                    <filename>.so</filename> file name to
                    <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link>
                    in the recipe that provides
                    the private version of the library.
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        <itemizedlist>
            <listitem>
                <para id='qa-issue-unlisted-pkg-lics'>
                    <code>
     LICENSE_&lt;packagename&gt; includes licenses (&lt;licenses&gt;) that are not listed in LICENSE [unlisted-pkg-lics]
                    </code>
                </para>

                <para>
                    The <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
		    of the recipe should be a superset of all the licenses of
		    all packages produced by this recipe.
		    In other words, any license in <filename>LICENSE_*</filename>
		    should also appear in
                    <link linkend='var-LICENSE'><filename>LICENSE</filename></link>.
                </para>

                <para>
                    &nbsp;
                </para>
            </listitem>
        </itemizedlist>
    </para>
</section>

<section id='configuring-and-disabling-qa-checks'>
    <title>Configuring and Disabling QA Checks</title>

    <para>
        You can configure the QA checks globally so that specific check
        failures either raise a warning or an error message, using the
        <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
        <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
        variables, respectively.
        You can also disable checks within a particular recipe using
        <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
        For information on how to work with the QA checks, see the
        "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
        section.
        <note><title>Tip</title>
            Please keep in mind that the QA checks exist in order to
            detect real or potential problems in the packaged output.
            So exercise caution when disabling these checks.
        </note>
    </para>
</section>
</chapter>
<!--
vim: expandtab tw=80 ts=4
-->