mirror of
https://git.yoctoproject.org/poky
synced 2026-06-06 14:49:50 +00:00
ref-manual: gather all QA checks in qa-checks.rst
There was duplication between qa-checks.rst and the doc for the insane class, so move all of the QA checks in this qa-checks.rst. Remove the documentation for these checks from classes.rst and link to the qa-checks.rst document from there. For QA checks that were only documented only in classes.rst, add them to qa-checks.rst. Also sort qa-checks by their names in qa-checks.rst. (From yocto-docs rev: dc984e5f54c38748603243053fde8b4d078ba586) Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Antonin Godard
committed by
Richard Purdie
Richard Purdie
parent
9e6ab8e80f
commit
3dd31d3b29
@@ -1345,321 +1345,8 @@ are meant to detect real or potential problems in the packaged
|
||||
output. So exercise caution when disabling these checks.
|
||||
|
||||
The tests you can list with the :term:`WARN_QA` and
|
||||
:term:`ERROR_QA` variables are:
|
||||
|
||||
- ``already-stripped:`` 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 ``-dbg`` packages, this stripping must be
|
||||
disabled.
|
||||
|
||||
- ``arch:`` 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.
|
||||
|
||||
- ``buildpaths:`` Checks for paths to locations on the build host
|
||||
inside the output files. Not only can these leak information about
|
||||
the build environment, they also hinder binary reproducibility.
|
||||
|
||||
- ``build-deps:`` Determines if a build-time dependency that is
|
||||
specified through :term:`DEPENDS`, explicit
|
||||
:term:`RDEPENDS`, or task-level dependencies exists
|
||||
to match any runtime dependency. This determination is particularly
|
||||
useful to discover where runtime dependencies are detected and added
|
||||
during packaging. If no explicit dependency has been specified within
|
||||
the metadata, at the packaging stage it is too late to ensure that
|
||||
the dependency is built, and thus you can end up with an error when
|
||||
the package is installed into the image during the
|
||||
:ref:`ref-tasks-rootfs` task because the auto-detected
|
||||
dependency was not satisfied. An example of this would be where the
|
||||
:ref:`ref-classes-update-rc.d` class automatically
|
||||
adds a dependency on the ``initscripts-functions`` package to
|
||||
packages that install an initscript that refers to
|
||||
``/etc/init.d/functions``. The recipe should really have an explicit
|
||||
:term:`RDEPENDS` for the package in question on ``initscripts-functions``
|
||||
so that the OpenEmbedded build system is able to ensure that the
|
||||
``initscripts`` recipe is actually built and thus the
|
||||
``initscripts-functions`` package is made available.
|
||||
|
||||
- ``configure-gettext:`` Checks that if a recipe is building something
|
||||
that uses automake and the automake files contain an ``AM_GNU_GETTEXT``
|
||||
directive, that the recipe also inherits the :ref:`ref-classes-gettext`
|
||||
class to ensure that gettext is available during the build.
|
||||
|
||||
- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
|
||||
do not depend on ``-dbg`` packages, which would cause a packaging
|
||||
bug.
|
||||
|
||||
- ``debug-files:`` Checks for ``.debug`` directories in anything but
|
||||
the ``-dbg`` package. The debug files should all be in the ``-dbg``
|
||||
package. Thus, anything packaged elsewhere is incorrect packaging.
|
||||
|
||||
- ``dep-cmp:`` Checks for invalid version comparison statements in
|
||||
runtime dependency relationships between packages (i.e. in
|
||||
:term:`RDEPENDS`,
|
||||
:term:`RRECOMMENDS`,
|
||||
:term:`RSUGGESTS`,
|
||||
:term:`RPROVIDES`,
|
||||
:term:`RREPLACES`, and
|
||||
:term:`RCONFLICTS` variable values). Any invalid
|
||||
comparisons might trigger failures or undesirable behavior when
|
||||
passed to the package manager.
|
||||
|
||||
- ``desktop:`` Runs the ``desktop-file-validate`` program against any
|
||||
``.desktop`` files to validate their contents against the
|
||||
specification for ``.desktop`` files.
|
||||
|
||||
- ``dev-deps:`` Checks that all packages except ``-dev`` or
|
||||
``-staticdev`` packages do not depend on ``-dev`` packages, which
|
||||
would be a packaging bug.
|
||||
|
||||
- ``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. Thus, the
|
||||
``-dev`` package is the correct location for them. In very rare
|
||||
cases, such as dynamically loaded modules, these symlinks
|
||||
are needed instead in the main package.
|
||||
|
||||
- ``empty-dirs:`` Checks that packages are not installing files to
|
||||
directories that are normally expected to be empty (such as ``/tmp``)
|
||||
The list of directories that are checked is specified by the
|
||||
:term:`QA_EMPTY_DIRS` variable.
|
||||
|
||||
- ``file-rdeps:`` Checks that file-level dependencies identified by
|
||||
the OpenEmbedded build system at packaging time are satisfied. For
|
||||
example, a shell script might start with the line ``#!/bin/bash``.
|
||||
This line would translate to a file dependency on ``/bin/bash``. Of
|
||||
the three package managers that the OpenEmbedded build system
|
||||
supports, only RPM directly handles file-level dependencies,
|
||||
resolving them automatically to packages providing the files.
|
||||
However, the lack of that functionality in the other two package
|
||||
managers does not mean the dependencies do not still need resolving.
|
||||
This QA check attempts to ensure that explicitly declared
|
||||
:term:`RDEPENDS` exist to handle any file-level
|
||||
dependency detected in packaged files.
|
||||
|
||||
- ``files-invalid:`` Checks for :term:`FILES` variable
|
||||
values that contain "//", which is invalid.
|
||||
|
||||
- ``host-user-contaminated:`` Checks that no package produced by the
|
||||
recipe contains any files outside of ``/home`` with a user or group
|
||||
ID that matches the user running BitBake. A match usually indicates
|
||||
that the files are being installed with an incorrect UID/GID, since
|
||||
target IDs are independent from host IDs. For additional information,
|
||||
see the section describing the
|
||||
:ref:`ref-tasks-install` task.
|
||||
|
||||
- ``incompatible-license:`` Report when packages are excluded from
|
||||
being created due to being marked with a license that is in
|
||||
:term:`INCOMPATIBLE_LICENSE`.
|
||||
|
||||
- ``installed-vs-shipped:`` Reports when files have been installed
|
||||
within :ref:`ref-tasks-install` but have not been included in any package by
|
||||
way of the :term:`FILES` 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
|
||||
:ref:`ref-tasks-install` if the files are not needed in any package.
|
||||
|
||||
- ``invalid-chars:`` Checks that the recipe metadata variables
|
||||
:term:`DESCRIPTION`,
|
||||
:term:`SUMMARY`, :term:`LICENSE`, and
|
||||
:term:`SECTION` do not contain non-UTF-8 characters.
|
||||
Some package managers do not support such characters.
|
||||
|
||||
- ``invalid-packageconfig:`` Checks that no undefined features are
|
||||
being added to :term:`PACKAGECONFIG`. For
|
||||
example, any name "foo" for which the following form does not exist::
|
||||
|
||||
PACKAGECONFIG[foo] = "..."
|
||||
|
||||
- ``la:`` Checks ``.la`` files for any :term:`TMPDIR` paths. Any ``.la``
|
||||
file containing these paths is incorrect since ``libtool`` adds the
|
||||
correct sysroot prefix when using the files automatically itself.
|
||||
|
||||
- ``ldflags:`` Ensures that the binaries were linked with the
|
||||
:term:`LDFLAGS` options provided by the build system.
|
||||
If this test fails, check that the :term:`LDFLAGS` variable is being
|
||||
passed to the linker command.
|
||||
|
||||
- ``libdir:`` Checks for libraries being installed into incorrect
|
||||
(possibly hardcoded) installation paths. For example, this test will
|
||||
catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
|
||||
"lib32". Another example is when recipes install
|
||||
``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
|
||||
|
||||
- ``libexec:`` Checks if a package contains files in
|
||||
``/usr/libexec``. This check is not performed if the ``libexecdir``
|
||||
variable has been set explicitly to ``/usr/libexec``.
|
||||
|
||||
- ``mime:`` Check that if a package contains mime type files (``.xml``
|
||||
files in ``${datadir}/mime/packages``) that the recipe also inherits
|
||||
the :ref:`ref-classes-mime` class in order to ensure that these get
|
||||
properly installed.
|
||||
|
||||
- ``mime-xdg:`` Checks that if a package contains a .desktop file with a
|
||||
'MimeType' key present, that the recipe inherits the
|
||||
:ref:`ref-classes-mime-xdg` class that is required in order for that
|
||||
to be activated.
|
||||
|
||||
- ``missing-update-alternatives:`` Check that if a recipe sets the
|
||||
:term:`ALTERNATIVE` variable that the recipe also inherits
|
||||
:ref:`ref-classes-update-alternatives` such that the alternative will
|
||||
be correctly set up.
|
||||
|
||||
- ``packages-list:`` Checks for the same package being listed
|
||||
multiple times through the :term:`PACKAGES` variable
|
||||
value. Installing the package in this manner can cause errors during
|
||||
packaging.
|
||||
|
||||
- ``patch-fuzz:`` Checks for fuzz in patch files that may allow
|
||||
them to apply incorrectly if the underlying code changes.
|
||||
|
||||
- ``patch-status:`` Checks that the ``Upstream-Status`` is specified and valid
|
||||
in the headers of patches for recipes.
|
||||
|
||||
- ``pep517-backend:`` checks that a recipe inheriting
|
||||
:ref:`ref-classes-setuptools3` has a PEP517-compliant backend.
|
||||
|
||||
- ``perllocalpod:`` Checks for ``perllocal.pod`` being erroneously
|
||||
installed and packaged by a recipe.
|
||||
|
||||
- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
|
||||
invalid format.
|
||||
|
||||
- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
|
||||
invalid format.
|
||||
|
||||
- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
|
||||
'link' where the specified target already exists.
|
||||
|
||||
- ``perms:`` Currently, this check is unused but reserved.
|
||||
|
||||
- ``pkgconfig:`` Checks ``.pc`` files for any
|
||||
:term:`TMPDIR`/:term:`WORKDIR` paths.
|
||||
Any ``.pc`` file containing these paths is incorrect since
|
||||
``pkg-config`` itself adds the correct sysroot prefix when the files
|
||||
are accessed.
|
||||
|
||||
- ``pkgname:`` Checks that all packages in
|
||||
:term:`PACKAGES` have names that do not contain
|
||||
invalid characters (i.e. characters other than 0-9, a-z, ., +, and
|
||||
-).
|
||||
|
||||
- ``pkgv-undefined:`` Checks to see if the :term:`PKGV` variable is
|
||||
undefined during :ref:`ref-tasks-package`.
|
||||
|
||||
- ``pkgvarcheck:`` Checks through the variables
|
||||
:term:`RDEPENDS`,
|
||||
:term:`RRECOMMENDS`,
|
||||
:term:`RSUGGESTS`,
|
||||
:term:`RCONFLICTS`,
|
||||
:term:`RPROVIDES`,
|
||||
:term:`RREPLACES`, :term:`FILES`,
|
||||
:term:`ALLOW_EMPTY`, ``pkg_preinst``,
|
||||
``pkg_postinst``, ``pkg_prerm`` and ``pkg_postrm``, 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.
|
||||
|
||||
- ``pn-overrides:`` Checks that a recipe does not have a name
|
||||
(:term:`PN`) value that appears in
|
||||
:term:`OVERRIDES`. If a recipe is named such that
|
||||
its :term:`PN` value matches something already in :term:`OVERRIDES` (e.g.
|
||||
:term:`PN` happens to be the same as :term:`MACHINE` or
|
||||
:term:`DISTRO`), it can have unexpected consequences.
|
||||
For example, assignments such as ``FILES:${PN} = "xyz"`` effectively
|
||||
turn into ``FILES = "xyz"``.
|
||||
|
||||
- ``recipe-naming:`` Checks that the recipe name and recipe class match, so
|
||||
that ``*-native`` recipes inherit :ref:`ref-classes-native` and
|
||||
``nativesdk-*`` recipes inherit :ref:`ref-classes-nativesdk`.
|
||||
|
||||
- ``rpaths:`` Checks for rpaths in the binaries that contain build
|
||||
system paths such as :term:`TMPDIR`. If this test fails, bad ``-rpath``
|
||||
options are being passed to the linker commands and your binaries
|
||||
have potential security issues.
|
||||
|
||||
- ``shebang-size:`` Check that the shebang line (``#!`` in the first line)
|
||||
in a packaged script is not longer than 128 characters, which can cause
|
||||
an error at runtime depending on the operating system.
|
||||
|
||||
- ``staticdev:`` Checks for static library files (``*.a``) in
|
||||
non-``staticdev`` packages.
|
||||
|
||||
- ``src-uri-bad:`` Checks that the :term:`SRC_URI` value set by a recipe
|
||||
does not contain a reference to ``${PN}`` (instead of the correct
|
||||
``${BPN}``) nor refers to unstable Github archive tarballs.
|
||||
|
||||
- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
|
||||
into :term:`TMPDIR` on the host. Such symlinks will
|
||||
work on the host, but are clearly invalid when running on the target.
|
||||
|
||||
- ``textrel:`` Checks for ELF binaries that contain relocations in
|
||||
their ``.text`` sections, which can result in a performance impact at
|
||||
runtime. See the explanation for the ``ELF binary`` message in
|
||||
":doc:`/ref-manual/qa-checks`" for more information regarding runtime performance
|
||||
issues.
|
||||
|
||||
- ``unhandled-features-check:`` check that if one of the variables that
|
||||
the :ref:`ref-classes-features_check` class supports (e.g.
|
||||
:term:`REQUIRED_DISTRO_FEATURES`) is set by a recipe, then the recipe
|
||||
also inherits :ref:`ref-classes-features_check` in order for the
|
||||
requirement to actually work.
|
||||
|
||||
- ``unimplemented-ptest:`` Checks that ptests are implemented for upstream
|
||||
tests.
|
||||
|
||||
- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
|
||||
for a package are also declared on the recipe level (i.e. any license
|
||||
in ``LICENSE:*`` should appear in :term:`LICENSE`).
|
||||
|
||||
- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
|
||||
in the binaries that by default on a standard system are searched by
|
||||
the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
|
||||
not cause any breakage, they do waste space and are unnecessary.
|
||||
|
||||
- ``usrmerge:`` If ``usrmerge`` is in :term:`DISTRO_FEATURES`, this
|
||||
check will ensure that no package installs files to root (``/bin``,
|
||||
``/sbin``, ``/lib``, ``/lib64``) directories.
|
||||
|
||||
- ``var-undefined:`` Reports when variables fundamental to packaging
|
||||
(i.e. :term:`WORKDIR`,
|
||||
:term:`DEPLOY_DIR`, :term:`D`,
|
||||
:term:`PN`, and :term:`PKGD`) are undefined
|
||||
during :ref:`ref-tasks-package`.
|
||||
|
||||
- ``version-going-backwards:`` If the :ref:`ref-classes-buildhistory`
|
||||
class 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::
|
||||
|
||||
This is only relevant when you are using runtime package management
|
||||
on your target system.
|
||||
|
||||
- ``virtual-slash:`` Checks to see if ``virtual/`` is being used in
|
||||
:term:`RDEPENDS` or :term:`RPROVIDES`, which is not good practice ---
|
||||
``virtual/`` is a convention intended for use in the build context
|
||||
(i.e. :term:`PROVIDES` and :term:`DEPENDS`) rather than the runtime
|
||||
context.
|
||||
|
||||
- ``xorg-driver-abi:`` Checks that all packages containing Xorg
|
||||
drivers have ABI dependencies. 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
|
||||
``xorg-driver-input.inc`` or ``xorg-driver-video.inc`` will
|
||||
automatically get these versions. Consequently, you should only need
|
||||
to explicitly add dependencies to binary driver recipes.
|
||||
:term:`ERROR_QA` variables are documented in the :doc:`/ref-manual/qa-checks`
|
||||
document of the Yocto Project Reference Manual.
|
||||
|
||||
.. _ref-classes-kernel:
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user