Bug 1773

Summary: Documentation: Document the QA/insane.bbclass errors
Product: [Build System, Metadata & Runtime] Meta-yocto Reporter: Mark Hatle <mark.hatle>
Component: meta-yoctoAssignee: Scott Rifenbark <srifenbark>
Status: RESOLVED FIXED QA Contact:
Severity: enhancement    
Priority: Low CC: poky.bs.watcher, poky.watcher, scott.a.garman
Version: unspecified   
Target Milestone: ---   
Hardware: x86   
OS: Multiple   
URL: a114ec3fd4f21ebf4dfd1d5c960d606e0db193f2
Whiteboard: 29-nov-2011: Resolved
OS type for building Yocto: --- Type of Regression: ---
Verified: Documentation change: ---

Description Mark Hatle 2011-11-18 09:25:54 UTC
After a conversation today on IRC - #oe, I believe we are lacking documentation on the built-in QA / insane.bbclass checks.

I would recommend that we document:

* how to control the QA checks -- make them warnings or errors

* What each of the QA checks actually checks for

* if possible, how to resolve the issue found in a QA check
Comment 1 Richard Purdie 2011-11-25 09:03:29 UTC
Proposed documentation:

"""
insane.bbclass controls many of the sanity checks performed on the
output of the build system. It is configurable and failures of tests can
either raise warning messages or errors. Newly added tests are usually
warnings at first and then later become errors once the metadata is in a
known good condition.

Tests listed in the WARN_QA variable will show up as warning messages.
Tests listed in the ERROR_QA variable will show up as errors and cause
build failures.

Tests which can be listed in these variables are:

"ldflags"

Ensures that the binaries were linked with the LDFLAGS options provided
by the build system. If this test fails, check that the LDFLAGS variable
is being passed to the linker command.

"useless-rpaths"

Checks for rpaths in the binaries which would be searched by the linker
anyway such as /lib and /usr/lib on a standard system. Whilst these
won't cause any breakage, they do waste space and are unnecessary.

"rpaths"

Checks for rpaths in the binaries which contain build system paths such
as TMPDIR. If this test fails, bad -rpath options are being passed to
the linker commands and your binaries have potential security issues.

"dev-so"

Checks that the .so symbolic links are in the -dev package and not in
any of the other packages. In general these symlinks are only useful for
development purposes so the -dev package is the correct location for
them. There are some cases for dynamically loaded modules where they are
needed in the main package instead but this is very rare.

"debug-files"

Checks for .debug directories in anything but the -dbg package. The
debug files should all be in the -dbg package so anything packaged
elsewhere is incorrect packaging.

"arch"

Checks the ELF type, bit size and endianness of any binaries to ensure
it matches the target architecture. It will raise an error if any
binaries don't match since there would be an incompatibility. Sometimes,
software like bootloaders may need to bypass this check.

"debug-deps"

Checks that -dbg packages only depend on other -dbg packages and not on
any other types of package which would be a packing bug

"dev-deps"

Checks that -dev packages only depend on other -dev packages and not on
any other types of package which would be a packing bug

"pkgconfig"

Checks .pc files for any TMPDIR/WORKDIR paths. Any .pc file containing
these paths is incorrect since pkg-config itself adds the correct
sysroot prefix when the files are accessed.

"la"

Checks .la files for any TMPDIR paths. Any .la file continaing these
paths is incorrect since libtool adds the correct sysroot prefix when
using the files automatically itself.

"desktop"

Runs the desktop-file-validate program against any .desktop files to
validate their contents against the specification for .desktop files.

"""
Comment 2 Scott Rifenbark 2011-11-29 11:36:34 UTC
Updated the existing insane.bbclass section in the class appendix of the YP reference manual.  The updates are viewable online at:

http://www.yoctoproject.org/docs/1.2/poky-ref-manual/poky-ref-manual.html#ref-classes-insane

I based the changes heavily on Richard's suggested text.

The commit for yocto-docs/master is a114ec3fd4f21ebf4dfd1d5c960d606e0db193f2

I cherry picked the change into the yocto-docs/edison branch in anticipation of a 1.1.1 release.  That commit is 2b15aa9076ec120d078bfcd570001a49e81df038.