diff options
authorMichał Górny <>2020-01-09 17:29:16 +0100
committerMichał Górny <>2020-01-09 17:29:16 +0100
commit192d0a5295eff64de6f6dd598bff62f34a1c10c4 (patch)
parentUSE=gui (diff)
Installed file policies
Signed-off-by: Michał Górny <>
2 files changed, 90 insertions, 2 deletions
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.