From 192d0a5295eff64de6f6dd598bff62f34a1c10c4 Mon Sep 17 00:00:00 2001
From: Michał Górny <mgorny@gentoo.org>
Date: Thu, 9 Jan 2020 17:29:16 +0100
Subject: Installed file policies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Michał Górny <mgorny@gentoo.org>
---
 filesystem.rst      |  5 +--
 installed-files.rst | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+), 2 deletions(-)
 create mode 100644 installed-files.rst

diff --git a/filesystem.rst b/filesystem.rst
index 4c98ba8..b0a686e 100644
--- a/filesystem.rst
+++ b/filesystem.rst
@@ -78,8 +78,9 @@ and packages must install libraries into appropriate directory for them
 to be correctly found by the dynamic loader.
 
 
-.. index:: file system; static library
-.. index:: file system; libtool file
+.. index::
+   pair: file system; static library
+   pair: file system; libtool file
 
 Static libraries and libtool files
 ----------------------------------
diff --git a/installed-files.rst b/installed-files.rst
new file mode 100644
index 0000000..b77bc02
--- /dev/null
+++ b/installed-files.rst
@@ -0,0 +1,87 @@
+Installed files
+===============
+
+.. index::
+   single: installed files; small files
+   single: USE flags; small files
+
+Installation of small files
+---------------------------
+:Source: QA
+:Reported: no
+
+Ebuilds must not introduce USE flags to control installing files that
+are small in size, require no additional dependencies and not cause any
+negative consequences to the program behavior by being installed.  Such
+files must be installed unconditionally.  Examples include shell
+completion files, systemd service units, localization files.
+
+Users wishing to strip unnecessary files of this category should use
+INSTALL_MASK to do so.
+
+*Rationale*: the goal of this policy is to avoid unnecessary rebuilds
+of packages when the cost of installing additional files is much smaller
+than the cost of rebuild.  It has been specifically brought in context
+of bash completions in LibreOffice -- a user who did not notice that he
+did not enable the flag should not be required to spend hours rebuilding
+such a huge package in order to install one tiny file.
+
+.. Note::
+
+   While technically e.g. ``app-shells/bash-completion`` could be
+   considered a dependency of installed bash completions, it is not
+   applicable here since this package needs to be installed by the user
+   if he wishes to use completions in the first place, and if it is not
+   installed, completion files are not used at all.
+
+
+.. index::
+   pair: installed files; static library
+
+Installation of static libraries
+--------------------------------
+:Source: QA
+:Reported: no
+
+Packages must not install static libraries unless they are explicitly
+required, either by themselves or their reverse dependencies.  If both
+shared and static libraries are supported, shared libraries must be
+installed by default and ``USE=static-libs`` may be added for static
+libraries if they are necessary.
+
+*Rationale*: static linking is strongly discouraged as it makes security
+support for packages practically impossible.  It may be used whenever
+really necessary (e.g. for recovery tools) but otherwise proliferating
+it is considered harmful.  There is no point in installing static
+libraries if they are never going to be used.
+
+
+.. index::
+   pair: installed files; libtool file
+
+Installation of libtool (.la) files
+-----------------------------------
+:Source: QA
+:Reported: no
+
+Packages must not install libtool .la files unless they are explicitly
+required.  Generally, they might be required if:
+
+a. the package is using a plugin loader that requires .la files in order
+   to locate plugins and does not have .so fallback (very uncommon),
+
+b. the package is installing static libraries that have additional
+   dependencies and no pkg-config files or other tools that provide
+   the list of dependencies to build systems.
+
+It is recommended to use the following one-liner to remove .la files::
+
+    find "${ED}" -name '*.la' -remove || die
+
+*Rationale*: libtool files were historically introduced as an attempt
+to supplement static library archives with dependent library list.
+However, they were only supported by libtool-based (autotools) projects
+and caused many issues, in particular due to hardcoding full paths.
+Today they are practically replaced by more portable pkg-config files,
+and while libtool keeps generating them, they are considered
+unnecessary and potentially harmful.
-- 
cgit v1.2.3-65-gdbad