ref-manual: Edits to icecc class and re-order of "I" classes.
(From yocto-docs rev: 643ccc4ac495e0dc88de20012d4843d2a402b507) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
d22c00e9fc
commit
ae9f8623a9
|
|
@ -824,9 +824,8 @@
|
|||
<title><filename>icecc.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
The Icecream distributed compile support (<filename>icecc</filename>)
|
||||
class stages directories with symlinks from
|
||||
<filename>gcc</filename> and <filename>g++</filename> to
|
||||
The <filename>icecc</filename> class stages directories with symlinks
|
||||
from <filename>gcc</filename> and <filename>g++</filename> to
|
||||
<filename>icecc</filename>, for both native and cross compilers.
|
||||
Depending on each configure or compile, the OpenEmbedded build system
|
||||
adds the directories at the head of the <filename>PATH</filename> list
|
||||
|
|
@ -892,6 +891,61 @@
|
|||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image'>
|
||||
<title>Creating Images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
These classes add support for creating images in several formats.
|
||||
First, the root filesystem is created from packages using
|
||||
one of the <filename>rootfs_*.bbclass</filename>
|
||||
files (depending on the package format used) and then the image is created.
|
||||
<itemizedlist>
|
||||
<listitem><para>The
|
||||
<filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
|
||||
variable controls the types of images to generate.
|
||||
</para></listitem>
|
||||
<listitem><para>The
|
||||
<filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
|
||||
variable controls the list of packages to install into the
|
||||
image.</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image_types'>
|
||||
<title><filename>image_types.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
The image types (<filename>image_types</filename>) class defines all of
|
||||
the standard image output types that you can enable through the
|
||||
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
|
||||
variable.
|
||||
You can use this class as a reference on how to add support for custom
|
||||
image output types.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
By default, this class is enabled through the
|
||||
<link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
|
||||
variable in
|
||||
<link linkend='ref-classes-image'><filename>image.bbclass</filename></link>.
|
||||
If you define your own image types using a custom BitBake class and
|
||||
then use <filename>IMAGE_CLASSES</filename> to enable it, the custom
|
||||
class must either inherit <filename>image_types</filename> or
|
||||
<filename>image_types</filename> must also appear in
|
||||
<filename>IMAGE_CLASSES</filename>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image_types_uboot'>
|
||||
<title><filename>image_types_uboot.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
The U-Boot image types (<filename>image_types_uboot</filename>) class
|
||||
defines additional image types specifically for the U-Boot bootloader.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image-live'>
|
||||
<title><filename>image-live.bbclass</filename></title>
|
||||
|
||||
|
|
@ -904,18 +958,6 @@
|
|||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image-vmdk'>
|
||||
<title><filename>image-vmdk.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
The Virtual Machine Disk image (<filename>image-vmdk</filename>) class
|
||||
supports building VMware VMDK images.
|
||||
Normally, you do not use this class directly.
|
||||
Instead, you add "vmdk" to
|
||||
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image-mklibs'>
|
||||
<title><filename>image-mklibs.bbclass</filename></title>
|
||||
|
||||
|
|
@ -979,37 +1021,378 @@
|
|||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image_types'>
|
||||
<title><filename>image_types.bbclass</filename></title>
|
||||
<section id='ref-classes-image-vmdk'>
|
||||
<title><filename>image-vmdk.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
The image types (<filename>image_types</filename>) class defines all of
|
||||
the standard image output types that you can enable through the
|
||||
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
|
||||
variable.
|
||||
You can use this class as a reference on how to add support for custom
|
||||
image output types.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
By default, this class is enabled through the
|
||||
<link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link>
|
||||
variable in
|
||||
<link linkend='ref-classes-image'><filename>image.bbclass</filename></link>.
|
||||
If you define your own image types using a custom BitBake class and
|
||||
then use <filename>IMAGE_CLASSES</filename> to enable it, the custom
|
||||
class must either inherit <filename>image_types</filename> or
|
||||
<filename>image_types</filename> must also appear in
|
||||
<filename>IMAGE_CLASSES</filename>.
|
||||
The Virtual Machine Disk image (<filename>image-vmdk</filename>) class
|
||||
supports building VMware VMDK images.
|
||||
Normally, you do not use this class directly.
|
||||
Instead, you add "vmdk" to
|
||||
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-image_types_uboot'>
|
||||
<title><filename>image_types_uboot.bbclass</filename></title>
|
||||
<section id='ref-classes-insane'>
|
||||
<title><filename>insane.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
The U-Boot image types (<filename>image_types_uboot</filename>) class
|
||||
defines additional image types specifically for the U-Boot bootloader.
|
||||
This class adds a step to the package generation process so that
|
||||
output quality assurance checks are generated by the OpenEmbedded
|
||||
build system.
|
||||
A range of checks are performed that check the build's output
|
||||
for common problems that show up during runtime.
|
||||
Distribution policy usually dictates whether to include this class.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can configure the sanity checks so that specific test failures
|
||||
either raise a warning or an error message.
|
||||
Typically, failures for new tests generate a warning.
|
||||
Subsequent failures for the same test would then generate an error
|
||||
message once the metadata is in a known and good condition.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Use the
|
||||
<link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
|
||||
<link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
|
||||
variables to control the behavior of
|
||||
these checks at the global level (i.e. in your custom distro
|
||||
configuration).
|
||||
However, to skip one or more checks in recipes, you should use
|
||||
<link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
|
||||
For example, to skip the check for symbolic link
|
||||
<filename>.so</filename> files in the main package of a recipe,
|
||||
add the following to the recipe.
|
||||
You need to realize that the package name override, in this example
|
||||
<filename>${PN}</filename>, must be used:
|
||||
<literallayout class='monospaced'>
|
||||
INSANE_SKIP_${PN} += "dev-so"
|
||||
</literallayout>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following list shows the tests you can list with the
|
||||
<filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
|
||||
variables:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis><filename>ldflags:</filename></emphasis>
|
||||
Ensures that the binaries were linked with the
|
||||
<filename>LDFLAGS</filename> options provided by the build system.
|
||||
If this test fails, check that the <filename>LDFLAGS</filename> variable
|
||||
is being passed to the linker command.</para></listitem>
|
||||
<listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
|
||||
Checks for dynamic library load paths (rpaths) in the binaries that
|
||||
by default on a standard system are searched 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.</para></listitem>
|
||||
<listitem><para><emphasis><filename>rpaths:</filename></emphasis>
|
||||
Checks for rpaths in the binaries that contain build system paths such
|
||||
as <filename>TMPDIR</filename>.
|
||||
If this test fails, bad <filename>-rpath</filename> options are being
|
||||
passed to the linker commands and your binaries have potential security
|
||||
issues.</para></listitem>
|
||||
<listitem><para><emphasis><filename>dev-so:</filename></emphasis>
|
||||
Checks that the <filename>.so</filename> symbolic links are in the
|
||||
<filename>-dev</filename> package and not in any of the other packages.
|
||||
In general, these symlinks are only useful for development purposes.
|
||||
Thus, the <filename>-dev</filename> package is the correct location for
|
||||
them.
|
||||
Some very rare cases do exist for dynamically loaded modules where
|
||||
these symlinks are needed instead in the main package.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>debug-files:</filename></emphasis>
|
||||
Checks for <filename>.debug</filename> directories in anything but the
|
||||
<filename>-dbg</filename> package.
|
||||
The debug files should all be in the <filename>-dbg</filename> package.
|
||||
Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
|
||||
<listitem><para><emphasis><filename>arch:</filename></emphasis>
|
||||
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 don't match the type since there would be an
|
||||
incompatibility.
|
||||
Sometimes software, like bootloaders, might need to bypass this check.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
|
||||
Checks that <filename>-dbg</filename> packages only depend on other
|
||||
<filename>-dbg</filename> packages and not on any other types of packages,
|
||||
which would cause a packaging bug.</para></listitem>
|
||||
<listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
|
||||
Checks that <filename>-dev</filename> packages only depend on other
|
||||
<filename>-dev</filename> packages and not on any other types of packages,
|
||||
which would be a packaging bug.</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
|
||||
Checks <filename>.pc</filename> files for any
|
||||
<link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<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></listitem>
|
||||
<listitem><para><emphasis><filename>textrel:</filename></emphasis>
|
||||
Checks for ELF binaries that contain relocations in their
|
||||
<filename>.text</filename> sections, which can result in a
|
||||
performance impact at runtime.</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
|
||||
Checks through the 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>,
|
||||
<link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
|
||||
<filename>pkg_preinst</filename>,
|
||||
<filename>pkg_postinst</filename>,
|
||||
<filename>pkg_prerm</filename>
|
||||
and <filename>pkg_postrm</filename>, and reports if there are
|
||||
variable sets that are not package-specific.
|
||||
Using these variables without a package suffix is bad practice,
|
||||
and might unnecessarily complicate dependencies of other packages
|
||||
within the same recipe or have other unintended consequences.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
|
||||
Checks that all packages containing Xorg drivers have ABI
|
||||
dependencies.
|
||||
The <filename>xserver-xorg</filename> 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></listitem>
|
||||
<listitem><para><emphasis><filename>libexec:</filename></emphasis>
|
||||
Checks if a package contains files in
|
||||
<filename>/usr/libexec</filename>.
|
||||
This check is not performed if the
|
||||
<filename>libexecdir</filename> variable has been set
|
||||
explicitly to <filename>/usr/libexec</filename>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>staticdev:</filename></emphasis>
|
||||
Checks for static library files (<filename>*.a</filename>) in
|
||||
non-<filename>staticdev</filename> packages.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>la:</filename></emphasis>
|
||||
Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
|
||||
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></listitem>
|
||||
<listitem><para><emphasis><filename>desktop:</filename></emphasis>
|
||||
Runs the <filename>desktop-file-validate</filename> program
|
||||
against any <filename>.desktop</filename> files to validate
|
||||
their contents against the specification for
|
||||
<filename>.desktop</filename> files.</para></listitem>
|
||||
<listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
|
||||
Checks that produced binaries have not 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></listitem>
|
||||
<listitem><para><emphasis><filename>split-strip:</filename></emphasis>
|
||||
Reports that splitting or stripping debug symbols from binaries
|
||||
has failed.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>arch:</filename></emphasis>
|
||||
Checks to ensure the architecture, bit size, and endianness
|
||||
of all output binaries matches that of the target.
|
||||
This test can detect when the wrong compiler or compiler options
|
||||
have been used.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
|
||||
Reports when files have been installed within
|
||||
<filename>do_install</filename> 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.
|
||||
Ideally, all installed files should be packaged or not
|
||||
installed at all.
|
||||
These files can be deleted at the end of
|
||||
<filename>do_install</filename> if the files are not
|
||||
needed in any package.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
|
||||
Checks for invalid version comparison statements in runtime
|
||||
dependency relationships between packages (i.e. in
|
||||
<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>,
|
||||
and
|
||||
<link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
|
||||
variable values).
|
||||
Any invalid comparisons might trigger failures or undesirable
|
||||
behavior when passed to the package manager.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
|
||||
Checks for
|
||||
<link linkend='var-FILES'><filename>FILES</filename></link>
|
||||
variable values that contain "//", which is invalid.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
|
||||
Report when packages are excluded from being created due to
|
||||
being marked with a license that is in
|
||||
<link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
|
||||
Checks the <filename>do_compile</filename> log for indications
|
||||
that paths to locations on the build host were used.
|
||||
Using such paths might result in host contamination of the
|
||||
build output.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
|
||||
Checks the <filename>do_install</filename> log for indications
|
||||
that paths to locations on the build host were used.
|
||||
Using such paths might result in host contamination of the
|
||||
build output.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>libdir:</filename></emphasis>
|
||||
Checks for libraries being installed into incorrect
|
||||
(possibly hardcoded) installation paths.
|
||||
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".
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>packages-list:</filename></emphasis>
|
||||
Checks for the same package being listed multiple times through
|
||||
the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
|
||||
variable value.
|
||||
Installing the package in this manner can cause errors during
|
||||
packaging.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perm-config:</filename></emphasis>
|
||||
Reports lines in <filename>fs-perms.txt</filename> that have
|
||||
an invalid format.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perm-line:</filename></emphasis>
|
||||
Reports lines in <filename>fs-perms.txt</filename> that have
|
||||
an invalid format.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perm-link:</filename></emphasis>
|
||||
Reports lines in <filename>fs-perms.txt</filename> that
|
||||
specify 'link' where the specified target already exists.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgname:</filename></emphasis>
|
||||
Checks that all packages in
|
||||
<link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
|
||||
have names that do not contain invalid characters (i.e.
|
||||
characters other than 0-9, a-z, ., +, and -).
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
|
||||
Checks that a recipe does not have 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>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
|
||||
Reports when a binary installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, or
|
||||
<filename>${base_sbindir}</filename>, depends on another
|
||||
binary installed under <filename>${exec_prefix}</filename>.
|
||||
This dependency is a concern if you want the system to remain
|
||||
basically operable if <filename>/usr</filename> is mounted
|
||||
separately and is not mounted.
|
||||
<note>
|
||||
Defaults for binaries installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, and
|
||||
<filename>${base_sbindir}</filename> are
|
||||
<filename>/lib</filename>, <filename>/bin</filename>, and
|
||||
<filename>/sbin</filename>, respectively.
|
||||
The default for a binary installed
|
||||
under <filename>${exec_prefix}</filename> is
|
||||
<filename>/usr</filename>.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
|
||||
Reports when a script file installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, or
|
||||
<filename>${base_sbindir}</filename>, depends on files
|
||||
installed under <filename>${exec_prefix}</filename>.
|
||||
This dependency is a concern if you want the system to remain
|
||||
basically operable if <filename>/usr</filename> is mounted
|
||||
separately and is not mounted.
|
||||
<note>
|
||||
Defaults for binaries installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, and
|
||||
<filename>${base_sbindir}</filename> are
|
||||
<filename>/lib</filename>, <filename>/bin</filename>, and
|
||||
<filename>/sbin</filename>, respectively.
|
||||
The default for a binary installed
|
||||
under <filename>${exec_prefix}</filename> is
|
||||
<filename>/usr</filename>.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
|
||||
Reports when variables fundamental to packaging (i.e.
|
||||
<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
|
||||
<link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
|
||||
<link linkend='var-D'><filename>D</filename></link>,
|
||||
<link linkend='var-PN'><filename>PN</filename></link>, and
|
||||
<link linkend='var-PKGD'><filename>PKGD</filename></link>) are
|
||||
undefined during <filename>do_package</filename>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
|
||||
Checks to see if the <filename>PKGV</filename> variable
|
||||
is undefined during <filename>do_package</filename>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
|
||||
Checks for paths to locations on the build host inside the
|
||||
output files.
|
||||
Currently, this test triggers too many false positives and
|
||||
thus is not normally enabled.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perms:</filename></emphasis>
|
||||
Currently, this check is unused but reserved.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
|
||||
If Build History is enabled, reports when a package
|
||||
being written out has a lower version than the previously
|
||||
written package under the same name.
|
||||
If you are placing output packages into a feed and
|
||||
upgrading packages on a target system using that feed, the
|
||||
version of a package going backwards can result in the target
|
||||
system not correctly upgrading to the "new" version of the
|
||||
package.
|
||||
<note>
|
||||
If you are not using runtime package management on your
|
||||
target system, then you do not need to worry about
|
||||
this situation.
|
||||
</note>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
|
@ -2112,369 +2495,6 @@
|
|||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-insane'>
|
||||
<title><filename>insane.bbclass</filename></title>
|
||||
|
||||
<para>
|
||||
This class adds a step to the package generation process so that
|
||||
output quality assurance checks are generated by the OpenEmbedded
|
||||
build system.
|
||||
A range of checks are performed that check the build's output
|
||||
for common problems that show up during runtime.
|
||||
Distribution policy usually dictates whether to include this class.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can configure the sanity checks so that specific test failures
|
||||
either raise a warning or an error message.
|
||||
Typically, failures for new tests generate a warning.
|
||||
Subsequent failures for the same test would then generate an error
|
||||
message once the metadata is in a known and good condition.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Use the
|
||||
<link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
|
||||
<link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
|
||||
variables to control the behavior of
|
||||
these checks at the global level (i.e. in your custom distro
|
||||
configuration).
|
||||
However, to skip one or more checks in recipes, you should use
|
||||
<link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
|
||||
For example, to skip the check for symbolic link
|
||||
<filename>.so</filename> files in the main package of a recipe,
|
||||
add the following to the recipe.
|
||||
You need to realize that the package name override, in this example
|
||||
<filename>${PN}</filename>, must be used:
|
||||
<literallayout class='monospaced'>
|
||||
INSANE_SKIP_${PN} += "dev-so"
|
||||
</literallayout>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The following list shows the tests you can list with the
|
||||
<filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
|
||||
variables:
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis><filename>ldflags:</filename></emphasis>
|
||||
Ensures that the binaries were linked with the
|
||||
<filename>LDFLAGS</filename> options provided by the build system.
|
||||
If this test fails, check that the <filename>LDFLAGS</filename> variable
|
||||
is being passed to the linker command.</para></listitem>
|
||||
<listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
|
||||
Checks for dynamic library load paths (rpaths) in the binaries that
|
||||
by default on a standard system are searched 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.</para></listitem>
|
||||
<listitem><para><emphasis><filename>rpaths:</filename></emphasis>
|
||||
Checks for rpaths in the binaries that contain build system paths such
|
||||
as <filename>TMPDIR</filename>.
|
||||
If this test fails, bad <filename>-rpath</filename> options are being
|
||||
passed to the linker commands and your binaries have potential security
|
||||
issues.</para></listitem>
|
||||
<listitem><para><emphasis><filename>dev-so:</filename></emphasis>
|
||||
Checks that the <filename>.so</filename> symbolic links are in the
|
||||
<filename>-dev</filename> package and not in any of the other packages.
|
||||
In general, these symlinks are only useful for development purposes.
|
||||
Thus, the <filename>-dev</filename> package is the correct location for
|
||||
them.
|
||||
Some very rare cases do exist for dynamically loaded modules where
|
||||
these symlinks are needed instead in the main package.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>debug-files:</filename></emphasis>
|
||||
Checks for <filename>.debug</filename> directories in anything but the
|
||||
<filename>-dbg</filename> package.
|
||||
The debug files should all be in the <filename>-dbg</filename> package.
|
||||
Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
|
||||
<listitem><para><emphasis><filename>arch:</filename></emphasis>
|
||||
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 don't match the type since there would be an
|
||||
incompatibility.
|
||||
Sometimes software, like bootloaders, might need to bypass this check.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
|
||||
Checks that <filename>-dbg</filename> packages only depend on other
|
||||
<filename>-dbg</filename> packages and not on any other types of packages,
|
||||
which would cause a packaging bug.</para></listitem>
|
||||
<listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
|
||||
Checks that <filename>-dev</filename> packages only depend on other
|
||||
<filename>-dev</filename> packages and not on any other types of packages,
|
||||
which would be a packaging bug.</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
|
||||
Checks <filename>.pc</filename> files for any
|
||||
<link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<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></listitem>
|
||||
<listitem><para><emphasis><filename>textrel:</filename></emphasis>
|
||||
Checks for ELF binaries that contain relocations in their
|
||||
<filename>.text</filename> sections, which can result in a
|
||||
performance impact at runtime.</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
|
||||
Checks through the 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>,
|
||||
<link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
|
||||
<filename>pkg_preinst</filename>,
|
||||
<filename>pkg_postinst</filename>,
|
||||
<filename>pkg_prerm</filename>
|
||||
and <filename>pkg_postrm</filename>, and reports if there are
|
||||
variable sets that are not package-specific.
|
||||
Using these variables without a package suffix is bad practice,
|
||||
and might unnecessarily complicate dependencies of other packages
|
||||
within the same recipe or have other unintended consequences.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
|
||||
Checks that all packages containing Xorg drivers have ABI
|
||||
dependencies.
|
||||
The <filename>xserver-xorg</filename> 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></listitem>
|
||||
<listitem><para><emphasis><filename>libexec:</filename></emphasis>
|
||||
Checks if a package contains files in
|
||||
<filename>/usr/libexec</filename>.
|
||||
This check is not performed if the
|
||||
<filename>libexecdir</filename> variable has been set
|
||||
explicitly to <filename>/usr/libexec</filename>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>staticdev:</filename></emphasis>
|
||||
Checks for static library files (<filename>*.a</filename>) in
|
||||
non-<filename>staticdev</filename> packages.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>la:</filename></emphasis>
|
||||
Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
|
||||
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></listitem>
|
||||
<listitem><para><emphasis><filename>desktop:</filename></emphasis>
|
||||
Runs the <filename>desktop-file-validate</filename> program
|
||||
against any <filename>.desktop</filename> files to validate
|
||||
their contents against the specification for
|
||||
<filename>.desktop</filename> files.</para></listitem>
|
||||
<listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
|
||||
Checks that produced binaries have not 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></listitem>
|
||||
<listitem><para><emphasis><filename>split-strip:</filename></emphasis>
|
||||
Reports that splitting or stripping debug symbols from binaries
|
||||
has failed.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>arch:</filename></emphasis>
|
||||
Checks to ensure the architecture, bit size, and endianness
|
||||
of all output binaries matches that of the target.
|
||||
This test can detect when the wrong compiler or compiler options
|
||||
have been used.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
|
||||
Reports when files have been installed within
|
||||
<filename>do_install</filename> 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.
|
||||
Ideally, all installed files should be packaged or not
|
||||
installed at all.
|
||||
These files can be deleted at the end of
|
||||
<filename>do_install</filename> if the files are not
|
||||
needed in any package.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
|
||||
Checks for invalid version comparison statements in runtime
|
||||
dependency relationships between packages (i.e. in
|
||||
<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>,
|
||||
and
|
||||
<link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
|
||||
variable values).
|
||||
Any invalid comparisons might trigger failures or undesirable
|
||||
behavior when passed to the package manager.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
|
||||
Checks for
|
||||
<link linkend='var-FILES'><filename>FILES</filename></link>
|
||||
variable values that contain "//", which is invalid.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
|
||||
Report when packages are excluded from being created due to
|
||||
being marked with a license that is in
|
||||
<link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
|
||||
Checks the <filename>do_compile</filename> log for indications
|
||||
that paths to locations on the build host were used.
|
||||
Using such paths might result in host contamination of the
|
||||
build output.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
|
||||
Checks the <filename>do_install</filename> log for indications
|
||||
that paths to locations on the build host were used.
|
||||
Using such paths might result in host contamination of the
|
||||
build output.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>libdir:</filename></emphasis>
|
||||
Checks for libraries being installed into incorrect
|
||||
(possibly hardcoded) installation paths.
|
||||
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".
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>packages-list:</filename></emphasis>
|
||||
Checks for the same package being listed multiple times through
|
||||
the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
|
||||
variable value.
|
||||
Installing the package in this manner can cause errors during
|
||||
packaging.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perm-config:</filename></emphasis>
|
||||
Reports lines in <filename>fs-perms.txt</filename> that have
|
||||
an invalid format.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perm-line:</filename></emphasis>
|
||||
Reports lines in <filename>fs-perms.txt</filename> that have
|
||||
an invalid format.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perm-link:</filename></emphasis>
|
||||
Reports lines in <filename>fs-perms.txt</filename> that
|
||||
specify 'link' where the specified target already exists.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgname:</filename></emphasis>
|
||||
Checks that all packages in
|
||||
<link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
|
||||
have names that do not contain invalid characters (i.e.
|
||||
characters other than 0-9, a-z, ., +, and -).
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
|
||||
Checks that a recipe does not have 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>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
|
||||
Reports when a binary installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, or
|
||||
<filename>${base_sbindir}</filename>, depends on another
|
||||
binary installed under <filename>${exec_prefix}</filename>.
|
||||
This dependency is a concern if you want the system to remain
|
||||
basically operable if <filename>/usr</filename> is mounted
|
||||
separately and is not mounted.
|
||||
<note>
|
||||
Defaults for binaries installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, and
|
||||
<filename>${base_sbindir}</filename> are
|
||||
<filename>/lib</filename>, <filename>/bin</filename>, and
|
||||
<filename>/sbin</filename>, respectively.
|
||||
The default for a binary installed
|
||||
under <filename>${exec_prefix}</filename> is
|
||||
<filename>/usr</filename>.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
|
||||
Reports when a script file installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, or
|
||||
<filename>${base_sbindir}</filename>, depends on files
|
||||
installed under <filename>${exec_prefix}</filename>.
|
||||
This dependency is a concern if you want the system to remain
|
||||
basically operable if <filename>/usr</filename> is mounted
|
||||
separately and is not mounted.
|
||||
<note>
|
||||
Defaults for binaries installed in
|
||||
<filename>${base_libdir}</filename>,
|
||||
<filename>${base_bindir}</filename>, and
|
||||
<filename>${base_sbindir}</filename> are
|
||||
<filename>/lib</filename>, <filename>/bin</filename>, and
|
||||
<filename>/sbin</filename>, respectively.
|
||||
The default for a binary installed
|
||||
under <filename>${exec_prefix}</filename> is
|
||||
<filename>/usr</filename>.
|
||||
</note>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
|
||||
Reports when variables fundamental to packaging (i.e.
|
||||
<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
|
||||
<link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
|
||||
<link linkend='var-D'><filename>D</filename></link>,
|
||||
<link linkend='var-PN'><filename>PN</filename></link>, and
|
||||
<link linkend='var-PKGD'><filename>PKGD</filename></link>) are
|
||||
undefined during <filename>do_package</filename>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
|
||||
Checks to see if the <filename>PKGV</filename> variable
|
||||
is undefined during <filename>do_package</filename>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
|
||||
Checks for paths to locations on the build host inside the
|
||||
output files.
|
||||
Currently, this test triggers too many false positives and
|
||||
thus is not normally enabled.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>perms:</filename></emphasis>
|
||||
Currently, this check is unused but reserved.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
|
||||
If Build History is enabled, reports when a package
|
||||
being written out has a lower version than the previously
|
||||
written package under the same name.
|
||||
If you are placing output packages into a feed and
|
||||
upgrading packages on a target system using that feed, the
|
||||
version of a package going backwards can result in the target
|
||||
system not correctly upgrading to the "new" version of the
|
||||
package.
|
||||
<note>
|
||||
If you are not using runtime package management on your
|
||||
target system, then you do not need to worry about
|
||||
this situation.
|
||||
</note>
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='ref-classes-rm-work'>
|
||||
<title>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue