ref-manual: add empty-dirs QA check and QA_EMPTY_DIRS*

This check is new in kirkstone.

(From yocto-docs rev: baa483e75538013be3261f8c115b8a5364b24c60)

Signed-off-by: Paul Eggleton <paul.eggleton@microsoft.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

3 files changed, 37 insertions, 1 deletions

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 60423d8533..a6dafe8f90 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -1040,6 +1040,11 @@ Here are the tests you can list with the :term:`WARN_QA` and
    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``.
diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index 3364311219..8c475d0f72 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -154,7 +154,16 @@ Errors and Warnings
    ``FILES:${PN}-dbg``. See :term:`FILES` for additional
    information on :term:`FILES`.
 
-    
+.. _qa-check-empty-dirs:
+
+-  ``<packagename> installs files in <path>, but it is expected to be empty [empty-dirs]``
+
+   The specified package is installing files into a directory that is
+   normally expected to be empty (such as ``/tmp``). These files may
+   be more appropriately installed to a different location, or
+   perhaps alternatively not installed at all, usually by updating the
+   ``do_install`` task/function.
+
 .. _qa-check-arch:
 
 -  ``Architecture did not match (<file_arch>, expected <machine_arch>) in <file> [arch]``
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 39801837ba..754e05c35a 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6084,6 +6084,28 @@ system and gives an overview of their function and contents.
       In the previous example,
       the version of the dependency is :term:`PYTHON_PN`.
 
+   :term:`QA_EMPTY_DIRS`
+      Specifies a list of directories that are expected to be empty when
+      packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or
+      :term:`WARN_QA` these will be checked and an error or warning
+      (respectively) will be produced.
+
+      The default :term:`QA_EMPTY_DIRS` value is set in
+      :ref:`insane.bbclass <ref-classes-insane>`.
+
+   :term:`QA_EMPTY_DIRS_RECOMMENDATION`
+      Specifies a recommendation for why a directory must be empty,
+      which will be included in the error message if a specific directory
+      is found to contain files. Must be overridden with the directory
+      path to match on.
+
+      If no recommendation is specified for a directory, then the default
+      "but it is expected to be empty" will be used.
+
+      An example message shows if files were present in '/dev'::
+
+         QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime"
+
    :term:`RANLIB`
       The minimal command and arguments to run ``ranlib``.