summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/ref-manual-customization.xsl12
-rw-r--r--documentation/ref-manual/ref-manual.xml2
-rw-r--r--documentation/ref-manual/ref-qa-checks.xml787
3 files changed, 800 insertions, 1 deletions
diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl
index 3ad3a315c0..f1e6e0dcf8 100644
--- a/documentation/ref-manual/ref-manual-customization.xsl
+++ b/documentation/ref-manual/ref-manual-customization.xsl
@@ -1,6 +1,6 @@
1<?xml version='1.0'?> 1<?xml version='1.0'?>
2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> 2<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
3 3
4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> 4 <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
5 5
6 <xsl:param name="html.stylesheet" select="'ref-style.css'" /> 6 <xsl:param name="html.stylesheet" select="'ref-style.css'" />
@@ -8,4 +8,14 @@
8 <xsl:param name="appendix.autolabel" select="A" /> 8 <xsl:param name="appendix.autolabel" select="A" />
9 <xsl:param name="section.autolabel" select="1" /> 9 <xsl:param name="section.autolabel" select="1" />
10 <xsl:param name="section.label.includes.component.label" select="1" /> 10 <xsl:param name="section.label.includes.component.label" select="1" />
11
12 <xsl:attribute-set name="normal.para.spacing">
13 <xsl:attribute name="text-indent">
14 <xsl:choose>
15 <xsl:when test="self::para">2em</xsl:when>
16 <xsl:otherwise>inherit</xsl:otherwise>
17 </xsl:choose>
18 </xsl:attribute>
19 </xsl:attribute-set>
20
11</xsl:stylesheet> 21</xsl:stylesheet>
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
index 1ec1458f2d..3eff7de712 100644
--- a/documentation/ref-manual/ref-manual.xml
+++ b/documentation/ref-manual/ref-manual.xml
@@ -125,6 +125,8 @@
125 125
126 <xi:include href="ref-tasks.xml"/> 126 <xi:include href="ref-tasks.xml"/>
127 127
128 <xi:include href="ref-qa-checks.xml"/>
129
128 <xi:include href="ref-images.xml"/> 130 <xi:include href="ref-images.xml"/>
129 131
130 <xi:include href="ref-features.xml"/> 132 <xi:include href="ref-features.xml"/>
diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml
new file mode 100644
index 0000000000..8571192e8d
--- /dev/null
+++ b/documentation/ref-manual/ref-qa-checks.xml
@@ -0,0 +1,787 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-qa-checks'>
6<title>QA Error and Warning Messages</title>
7
8<section id='qa-introduction'>
9 <title>Introduction</title>
10
11 <para>
12 Fixing QA issues in your recipes can take significant time and effort
13 when writing new recipes.
14 Sometimes you might be tempted to ignore a QA message or even to
15 disable these QA checks.
16 This chapter provides a list of the QA messages and brief explanations
17 of the issues you could encounter so that you can properly resolve
18 problems.
19 </para>
20
21 <para>
22 The next section provides a list of all QA error and warning
23 messages based on a default configuration.
24 Each entry provides the message or error form along with an explanation.
25 <note>
26 <title>Notes</title>
27 <itemizedlist>
28 <listitem><para>
29 As mentioned, this list of error and warning messages is for
30 QA checks only.
31 The list does not cover all possible build errors or
32 warnings you could encounter.
33 </para></listitem>
34 <listitem><para>
35 Because some QA checks are disabled by default, this list
36 does not include all possible QA check errors and warnings.
37 </para></listitem>
38 </itemizedlist>
39 </note>
40 </para>
41</section>
42
43<section id='qa-errors-and-warnings'>
44 <title>Errors and Warnings</title>
45
46 <para>
47 <itemizedlist>
48 <listitem><para>
49 <literallayout class='monospaced'>
50 &lt;packagename&gt;: &lt;path&gt; is using libexec please relocate to &lt;libexecdir&gt; [libexec]
51 </literallayout>
52 The specified package contains files in
53 <filename>/usr/libexec</filename>.
54 By default, <filename>libexecdir</filename> is set to
55 "${libdir}/${BPN}" rather than to "/usr/libexec".
56 Thus, installing to <filename>/usr/libexec</filename>
57 is likely not desirable.
58 </para></listitem>
59 </itemizedlist>
60 </para>
61
62 <para>
63 <itemizedlist>
64 <listitem><para>
65 <literallayout class='monospaced'>
66 package &lt;packagename&gt; contains bad RPATH &lt;rpath&gt; in file &lt;file&gt; [rpaths]
67 </literallayout>
68 The specified binary produced by the recipe contains dynamic
69 library load paths (rpaths) that contain build system paths
70 such as
71 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>,
72 which could potentially be a security issue.
73 Check for bad <filename>-rpath</filename> options being passed
74 to the linker in your
75 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
76 log.
77 Depending on the build system used by the software being built,
78 there might be a configure option to disable rpath usage
79 completely within the build of the software.
80 </para></listitem>
81 </itemizedlist>
82 </para>
83
84 <para>
85 <itemizedlist>
86 <listitem><para>
87 <literallayout class='monospaced'>
88 &lt;packagename&gt;: &lt;file&gt; contains probably-redundant RPATH &lt;rpath&gt; [useless-rpaths]
89 </literallayout>
90 The specified binary produced by the recipe contains dynamic
91 library load paths (rpaths) that on a standard system are
92 searched by default by the linker (e.g.
93 <filename>/lib</filename> and <filename>/usr/lib</filename>).
94 While these paths will not cause any breakage, they do waste
95 space and are unnecessary.
96 Depending on the build system used by the software being built,
97 there might be a configure option to disable rpath usage
98 completely within the build of the software.
99 </para></listitem>
100 </itemizedlist>
101 </para>
102
103 <para>
104 <itemizedlist>
105 <listitem><para>
106 <literallayout class='monospaced'>
107 non -dev/-dbg/-nativesdk package contains symlink .so: &lt;packagename&gt; path '&lt;path&gt;' [dev-so]
108 </literallayout>
109 Symlink <filename>.so</filename> files are for development
110 only, and should therefore go into the
111 <filename>-dev</filename> package.
112 This situation might occur if you add
113 <filename>*.so*</filename> rather than
114 <filename>*.so.*</filename> to a non-dev package.
115 Change
116 <link linkend='var-FILES'><filename>FILES</filename></link>
117 (and possibly
118 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
119 such that the specified <filename>.so</filename> file goes
120 into an appropriate <filename>-dev</filename> package.
121 </para></listitem>
122 </itemizedlist>
123 </para>
124
125 <para>
126 <itemizedlist>
127 <listitem><para>
128 <literallayout class='monospaced'>
129 non -staticdev package contains static .a library: &lt;packagename&gt; path '&lt;path&gt;' [staticdev]
130 </literallayout>
131 Static <filename>.a</filename> library files should go into
132 a <filename>-staticdev</filename> package.
133 Change
134 <link linkend='var-FILES'><filename>FILES</filename></link>
135 (and possibly
136 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>)
137 such that the specified <filename>.a</filename> file goes into
138 an appropriate <filename>-staticdev</filename> package.
139 </para></listitem>
140 </itemizedlist>
141 </para>
142
143 <para>
144 <itemizedlist>
145 <listitem><para>
146 <literallayout class='monospaced'>
147 &lt;packagename&gt;: found library in wrong location [libdir]
148 </literallayout>
149 The specified file may have been installed into an incorrect
150 (possibly hardcoded) installation path.
151 For example, this test will catch recipes that install
152 <filename>/lib/bar.so</filename> when
153 <filename>${base_libdir}</filename> is "lib32".
154 Another example is when recipes install
155 <filename>/usr/lib64/foo.so</filename> when
156 <filename>${libdir}</filename> is "/usr/lib".
157 False positives occasionally exist.
158 For these cases add "libdir" to
159 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
160 for the package.
161 </para></listitem>
162 </itemizedlist>
163 </para>
164
165 <para>
166 <itemizedlist>
167 <listitem><para>
168 <literallayout class='monospaced'>
169 non debug package contains .debug directory: &lt;packagename&gt; path &lt;path&gt; [debug-files]
170 </literallayout>
171 The specified package contains a
172 <filename>.debug</filename> directory, which should not appear
173 in anything but the <filename>-dbg</filename> package.
174 This situation might occur if you add a path which contains
175 a <filename>.debug</filename> directory and do not explicitly
176 add the <filename>.debug</filename> directory to the
177 <filename>-dbg</filename> package.
178 If this is the case, add the <filename>.debug</filename>
179 directory explicitly to <filename>FILES_${PN}-dbg</filename>.
180 See
181 <link linkend='var-FILES'><filename>FILES</filename></link>
182 for additional information on <filename>FILES</filename>.
183 </para></listitem>
184 </itemizedlist>
185 </para>
186
187 <para>
188 <itemizedlist>
189 <listitem><para>
190 <literallayout class='monospaced'>
191 Architecture did not match (&lt;machine_arch&gt; to &lt;file_arch&gt;) on &lt;file&gt;
192 </literallayout>
193 By default, the OpenEmbedded build system checks the Executable
194 and Linkable Format (ELF) type, bit size, and endianness of
195 any binaries to ensure they match the target architecture.
196 This test fails if any binaries do not match the type since
197 there would be an incompatibility.
198 The test could indicate that the wrong compiler or compiler
199 options have been used.
200 Sometimes software, like bootloaders, might need to bypass this
201 check.
202 If the file you receive the error for is firmware that is not
203 intended to be executed within the target operating system
204 or is intended to run on a separate processor within the
205 device, you can add "arch" to
206 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
207 for the package.
208 Another option is to check the
209 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
210 log and verify that the
211 compiler options being used are correct.
212 </para></listitem>
213 </itemizedlist>
214 </para>
215
216 <para>
217 <itemizedlist>
218 <listitem><para>
219 <literallayout class='monospaced'>
220 Bit size did not match (&lt;machine_bits&gt; to &lt;file_bits&gt;) &lt;recipe&gt; on &lt;file&gt;
221 </literallayout>
222 By default, the OpenEmbedded build system checks the Executable
223 and Linkable Format (ELF) type, bit size, and endianness of
224 any binaries to ensure they match the target architecture.
225 This test fails if any binaries do not match the type since
226 there would be an incompatibility.
227 The test could indicate that the wrong compiler or compiler
228 options have been used.
229 Sometimes software, like bootloaders, might need to bypass this
230 check.
231 If the file you receive the error for is firmware that is not
232 intended to be executed within the target operating system
233 or is intended to run on a separate processor within the
234 device, you can add "arch" to
235 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
236 for the package.
237 Another option is to check the
238 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
239 log and verify that the
240 compiler options being used are correct.
241 </para></listitem>
242 </itemizedlist>
243 </para>
244
245 <para>
246 <itemizedlist>
247 <listitem><para>
248 <literallayout class='monospaced'>
249 Endianness did not match (&lt;machine_endianness&gt; to &lt;file_endianness&gt;) on &lt;file&gt; [arch]
250 </literallayout>
251 By default, the OpenEmbedded build system checks the Executable
252 and Linkable Format (ELF) type, bit size, and endianness of
253 any binaries to ensure they match the target architecture.
254 This test fails if any binaries do not match the type since
255 there would be an incompatibility.
256 The test could indicate that the wrong compiler or compiler
257 options have been used.
258 Sometimes software, like bootloaders, might need to bypass this
259 check.
260 If the file you receive the error for is firmware that is not
261 intended to be executed within the target operating system
262 or is intended to run on a separate processor within the
263 device, you can add "arch" to
264 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>
265 for the package.
266 Another option is to check the
267 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
268 log and verify that the
269 compiler options being used are correct.
270 </para></listitem>
271 </itemizedlist>
272 </para>
273
274 <para>
275 <itemizedlist>
276 <listitem><para>
277 <literallayout class='monospaced'>
278 ELF binary '&lt;file&gt;' has relocations in .text [textrel]
279 </literallayout>
280 The specified ELF binary contains relocations in its
281 <filename>.text</filename> sections.
282 This situation can result in a performance impact at runtime.
283 <note>
284 A bug currently exists that causes this warning to appear
285 erroneously.
286 See
287 <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=6104'></ulink>
288 for more information.
289 </note>
290 </para></listitem>
291 </itemizedlist>
292 </para>
293
294 <para>
295 <itemizedlist>
296 <listitem><para>
297 <literallayout class='monospaced'>
298 No GNU_HASH in the elf binary: '&lt;file&gt;' [ldflags]
299 </literallayout>
300 This indicates that binaries produced when building the
301 recipe have not been linked with the
302 <filename>LDFLAGS</filename>
303 options provided by the build system.
304 Check to be sure that the <filename>LDFLAGS</filename> variable
305 is being passed to the linker command.
306 A common workaround for this situation is to pass in
307 <filename>LDFLAGS</filename> using
308 <filename>TARGET_CC_ARCH</filename>
309 within the recipe as follows:
310 <literallayout class='monospaced'>
311 TARGET_CC_ARCH += "${LDFLAGS}"
312 </literallayout>
313 </para></listitem>
314 </itemizedlist>
315 </para>
316
317 <para>
318 <itemizedlist>
319 <listitem><para>
320 <literallayout class='monospaced'>
321 Package &lt;packagename&gt; contains Xorg driver (&lt;driver&gt;) but no xorg-abi- dependencies [xorg-driver-abi]
322 </literallayout>
323 The specified package contains an Xorg driver, but does not
324 have a corresponding ABI package dependency.
325 The xserver-xorg recipe provides driver ABI names.
326 All drivers should depend on the ABI versions that they have
327 been built against.
328 Driver recipes that include
329 <filename>xorg-driver-input.inc</filename> or
330 <filename>xorg-driver-video.inc</filename> will automatically
331 get these versions.
332 Consequently, you should only need to explicitly add
333 dependencies to binary driver recipes.
334 </para></listitem>
335 </itemizedlist>
336 </para>
337
338 <para>
339 <itemizedlist>
340 <listitem><para>
341 <literallayout class='monospaced'>
342 The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir]
343 </literallayout>
344 The <filename>/usr/share/info/dir</filename> should not be
345 packaged.
346 Add the following line to your
347 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
348 task or to your <filename>do_install_append</filename> within
349 the recipe as follows:
350 <literallayout class='monospaced'>
351 rm ${D}${infodir}/dir
352 </literallayout>
353 </para></listitem>
354 </itemizedlist>
355 </para>
356
357 <para>
358 <itemizedlist>
359 <listitem><para>
360 <literallayout class='monospaced'>
361 Symlink &lt;path&gt; in &lt;packagename&gt; points to TMPDIR [symlink-to-sysroot]
362 </literallayout>
363 The specified symlink points into
364 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
365 on the host.
366 Such symlinks will work on the host.
367 However, they are clearly invalid when running on the target.
368 You should either correct the symlink to use a relative path
369 or remove the symlink.
370 </para></listitem>
371 </itemizedlist>
372 </para>
373
374 <para>
375 <itemizedlist>
376 <listitem><para>
377 <literallayout class='monospaced'>
378 &lt;file&gt; failed sanity test (workdir) in path &lt;path&gt; [la]
379 </literallayout>
380 The specified <filename>.la</filename> file contains
381 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
382 paths.
383 Any <filename>.la</filename> file containing these paths
384 is incorrect since <filename>libtool</filename> adds the
385 correct sysroot prefix when using the files automatically
386 itself.
387 </para></listitem>
388 </itemizedlist>
389 </para>
390
391 <para>
392 <itemizedlist>
393 <listitem><para>
394 <literallayout class='monospaced'>
395 &lt;file&gt; failed sanity test (tmpdir) in path &lt;path&gt; [pkgconfig]
396 </literallayout>
397 The specified <filename>.pc</filename> file contains
398 <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
399 paths.
400 Any <filename>.pc</filename> file containing these paths is
401 incorrect since <filename>pkg-config</filename> itself adds
402 the correct sysroot prefix when the files are accessed.
403 </para></listitem>
404 </itemizedlist>
405 </para>
406
407 <para>
408 <itemizedlist>
409 <listitem><para>
410 <literallayout class='monospaced'>
411 &lt;packagename&gt; rdepends on &lt;debug_packagename&gt; [debug-deps]
412 </literallayout>
413 A dependency exists between the specified non-dbg package
414 (a package whose name does not end in
415 <filename>-dbg</filename>) and a package that is a
416 <filename>dbg</filename> package.
417 The <filename>dbg</filename> packages contain debug symbols
418 and are usually brought in using the dbg-pkgs
419 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
420 value or explicitly brought into the image using
421 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
422 (or as a dependency of another <filename>dbg</filename>
423 package brought in using either method).
424 The dependency might have been automatically added
425 (because the <filename>dbg</filename> package erroneously
426 contains files that it should not contain (e.g. a non-symlink
427 <filename>.so</filename> file) or it might have been added
428 manually (e.g. by adding to
429 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
430 </para></listitem>
431 </itemizedlist>
432 </para>
433
434 <para>
435 <itemizedlist>
436 <listitem><para>
437 <literallayout class='monospaced'>
438 &lt;packagename&gt; rdepends on &lt;dev_packagename&gt; [dev-deps]
439 </literallayout>
440 A dependency exists between the specified non-dev package
441 (a package whose name does not end in
442 <filename>-dev</filename>) and a package that is a
443 <filename>dev</filename> package.
444 The <filename>dev</filename> packages contain development
445 headers and are usually brought in using the dev-pkgs
446 <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
447 value or explicitly brought into the image using
448 <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
449 (or as a dependency of another <filename>dev</filename>
450 package brought in using either method).
451 The dependency might have been automatically added (because
452 the <filename>dev</filename> package erroneously contains
453 files that it should not have (e.g. a non-symlink
454 <filename>.so</filename> file) or it might have been added
455 manually (e.g. by adding to
456 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>.
457 </para></listitem>
458 </itemizedlist>
459 </para>
460
461 <para>
462 <itemizedlist>
463 <listitem><para>
464 <literallayout class='monospaced'>
465 &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]
466 </literallayout>
467 If you are adding a versioned dependency relationship to one
468 of the dependency variables
469 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
470 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
471 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
472 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
473 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
474 or
475 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>),
476 you must only use the named comparison operators.
477 Change the versioned dependency values you are adding to match
478 those listed in the message.
479 </para></listitem>
480 </itemizedlist>
481 </para>
482
483 <para>
484 <itemizedlist>
485 <listitem><para>
486 <literallayout class='monospaced'>
487 &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]
488 </literallayout>
489 The log for the
490 <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>
491 task indicates that paths on the host were searched for files,
492 which is not appropriate when cross-compiling.
493 Look for "is unsafe for cross-compilation" or "CROSS COMPILE
494 Badness" in the specified log file.
495 </para></listitem>
496 </itemizedlist>
497 </para>
498
499 <para>
500 <itemizedlist>
501 <listitem><para>
502 <literallayout class='monospaced'>
503 &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]
504 </literallayout>
505 The log for the
506 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
507 task indicates that paths on the host were searched for files,
508 which is not appropriate when cross-compiling.
509 Look for "is unsafe for cross-compilation" or "CROSS COMPILE
510 Badness" in the specified log file.
511 </para></listitem>
512 </itemizedlist>
513 </para>
514
515 <para>
516 <itemizedlist>
517 <listitem><para>
518 <literallayout class='monospaced'>
519 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;'
520 </literallayout>
521 The log for the
522 <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
523 task indicates that paths on the host were searched for files,
524 which is not appropriate when cross-compiling.
525 Look for "is unsafe for cross-compilation" or "CROSS COMPILE
526 Badness" in the specified log file.
527 </para></listitem>
528 </itemizedlist>
529 </para>
530
531 <para>
532 <itemizedlist>
533 <listitem><para>
534 <literallayout class='monospaced'>
535 &lt;packagename&gt; doesn't match the [a-z0-9.+-]+ regex [pkgname]
536 </literallayout>
537 The convention within the OpenEmbedded build system is for
538 package names (sometimes enforced by the package manager itself)
539 to require that package names are all lower case and to
540 allow a restricted set of characters.
541 If your recipe name does not match this, or you add packages
542 to
543 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
544 that do not conform to the convention, then you will receive
545 this error.
546 Rename your recipe.
547 Or, if you have added a non-conforming package name to
548 <filename>PACKAGES</filename>, change the package name
549 appropriately.
550 </para></listitem>
551 </itemizedlist>
552 </para>
553
554 <para>
555 <itemizedlist>
556 <listitem><para>
557 <literallayout class='monospaced'>
558 &lt;recipe&gt;: configure was passed unrecognized options: &lt;options&gt; [unknown-configure-option]
559 </literallayout>
560 The configure script is reporting that the specified options
561 are unrecognized.
562 This situation could be because the options were previously
563 valid but have been removed.
564 Or, there was a mistake when the options were added and there
565 is another option that should be used instead.
566 If you are unsure, consult the upstream build documentation,
567 the <filename>./configure &dash;&dash;help</filename> output,
568 and the upstream change log or release notes.
569 Once you have worked out what the appropriate change is, you
570 can update
571 <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
572 or the individual
573 <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>
574 option values accordingly.
575 </para></listitem>
576 </itemizedlist>
577 </para>
578
579 <para>
580 <itemizedlist>
581 <listitem><para>
582 <literallayout class='monospaced'>
583 Recipe &lt;recipefile&gt; has PN of "&lt;recipename&gt;" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides]
584 </literallayout>
585 The specified recipe has a name
586 (<link linkend='var-PN'><filename>PN</filename></link>)
587 value that appears in
588 <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
589 If a recipe is named such that its <filename>PN</filename>
590 value matches something already in
591 <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
592 happens to be the same as
593 <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
594 or
595 <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
596 it can have unexpected consequences.
597 For example, assignments such as
598 <filename>FILES_${PN} = "xyz"</filename> effectively turn into
599 <filename>FILES = "xyz"</filename>.
600 Rename your recipe (or if <filename>PN</filename> is being
601 set explicitly, change the <filename>PN</filename> value) so
602 that the conflict does not occur.
603 See
604 <link linkend='var-FILES'><filename>FILES</filename></link>
605 for additional information.
606 </para></listitem>
607 </itemizedlist>
608 </para>
609
610 <para>
611 <itemizedlist>
612 <listitem><para>
613 <literallayout class='monospaced'>
614 &lt;recipefile&gt;: Variable &lt;variable&gt; is set as not being package specific, please fix this. [pkgvarcheck]
615 </literallayout>
616 Certain variables
617 (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
618 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
619 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
620 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
621 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
622 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
623 <link linkend='var-FILES'><filename>FILES</filename></link>,
624 <filename>pkg_preinst</filename>,
625 <filename>pkg_postinst</filename>,
626 <filename>pkg_prerm</filename>,
627 <filename>pkg_postrm</filename>, and
628 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>)
629 should always be set specific to a package (i.e. they should
630 be set with a package name override such as
631 <filename>RDEPENDS_${PN} = "value"</filename> rather than
632 <filename>RDEPENDS = "value"</filename>).
633 If you receive this error, correct any assignments to these
634 variables within your recipe.
635 </para></listitem>
636 </itemizedlist>
637 </para>
638
639 <para>
640 <itemizedlist>
641 <listitem><para>
642 <literallayout class='monospaced'>
643 File '&lt;file&gt;' from &lt;recipename&gt; was already stripped, this will prevent future debugging! [already-stripped]
644 </literallayout>
645 Produced binaries have already been stripped prior to the
646 build system extracting debug symbols.
647 It is common for upstream software projects to default to
648 stripping debug symbols for output binaries.
649 In order for debugging to work on the target using
650 <filename>-dbg</filename> packages, this stripping must be
651 disabled.
652 Depending on the build system used by the software being built,
653 disabling this stripping could be as easy as specifying an
654 additional configure option.
655 If not, disabling stripping might involve patching the build
656 scripts.
657 </para></listitem>
658 </itemizedlist>
659 </para>
660
661 <para>
662 <itemizedlist>
663 <listitem><para>
664 <literallayout class='monospaced'>
665 &lt;packagename&gt; is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list]
666 </literallayout>
667 Package names must appear only once in the
668 <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
669 variable.
670 You might receive this error if you are attempting to add a
671 package to <filename>PACKAGES</filename> that is
672 already in the variable's value.
673 </para></listitem>
674 </itemizedlist>
675 </para>
676
677 <para>
678 <itemizedlist>
679 <listitem><para>
680 <literallayout class='monospaced'>
681 FILES variable for package &lt;packagename&gt; contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid]
682 </literallayout>
683 The string "//" is invalid in a Unix path.
684 Correct all occurrences where this string appears in a
685 <link linkend='var-FILES'><filename>FILES</filename></link>
686 variable so that there is only a single "/".
687 </para></listitem>
688 </itemizedlist>
689 </para>
690
691 <para>
692 <itemizedlist>
693 <listitem><para>
694 <literallayout class='monospaced'>
695 &lt;recipename&gt;: Files/directories were installed but not shipped [installed-vs-shipped]
696 </literallayout>
697 Files have been installed within the
698 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
699 task but have not been included in any package by way of the
700 <link linkend='var-FILES'><filename>FILES</filename></link>
701 variable.
702 Files that do not appear in any package cannot be present in
703 an image later on in the build process.
704 You need to one of the following:
705 <itemizedlist>
706 <listitem><para>
707 Add the files to <filename>FILES</filename> for the
708 package you want them to appear in (e.g.
709 <filename>FILES_${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> for the main
710 package).
711 </para></listitem>
712 <listitem><para>
713 Delete the files at the end of the
714 <filename>do_install</filename> task if the files
715 are not needed in any package
716 </para></listitem>
717 </itemizedlist>
718 </para></listitem>
719 </itemizedlist>
720 </para>
721
722 <para>
723 <itemizedlist>
724 <listitem><para>
725 <literallayout class='monospaced'>
726 &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
727 </literallayout>
728 This message means that both
729 <filename>&lt;oldpackage&gt;</filename> and
730 <filename>&lt;newpackage&gt;</filename> provide the specified
731 shared library.
732 You can expect this message when a recipe has been renamed.
733 However, if that is not the case, the message might indicate
734 that a private version of a library is being erroneously
735 picked up as the provider for a common library.
736 If that is the case, you should add the library's
737 <filename>.so</filename> file name to
738 <filename>PRIVATE_LIBS</filename> in the recipe that provides
739 the private version of the library.
740 </para></listitem>
741 </itemizedlist>
742 </para>
743
744<!--
745Here are some messages that might be documented in the future.
746Right now we are not documenting them because the QA checks are not
747enabled by default:
748
749 <para>
750 <itemizedlist>
751 <listitem><para>
752 <literallayout class='monospaced'>
753 Desktop file issue: &lt;error&gt; [desktop]
754 </literallayout>
755 NEED A DESCRIPTION AND SOLUTION
756 </para></listitem>
757 </itemizedlist>
758 </para>
759
760 <para>
761 <itemizedlist>
762 <listitem><para>
763 <literallayout class='monospaced'>
764 &lt;packagename&gt;: &lt;file&gt;, installed in the base_prefix, requires a shared library under exec_prefix (&lt;exec_prefix&t;g) [unsafe-references-in-binaries]
765 </literallayout>
766 NEED A DESCRIPTION AND SOLUTION
767 </para></listitem>
768 </itemizedlist>
769 </para>
770
771 <para>
772 <itemizedlist>
773 <listitem><para>
774 <literallayout class='monospaced'>
775 &lt;packagename&gt;: Found a reference to &lt;exec_prefix&gt;/ in &lt;path&gt; - Shell scripts in base_bindir and base_sbindir should not reference anything in exec_prefix [unsafe-references-in-scripts]
776 </literallayout>
777 NEED A DESCRIPTION AND SOLUTION
778 </para></listitem>
779 </itemizedlist>
780 </para>
781-->
782</section>
783
784</chapter>
785<!--
786vim: expandtab tw=80 ts=4
787-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-16 15:11:55 +0000