Gentoo Policy Guide¶
Gentoo Policy Guide aims to become a definitive clear source of all Tree Policies that are currently binding to Gentoo developers. It combines both policies that are global by design (i.e. set by the QA team or the Council), as well as specific to other Gentoo projects. The policies are meant to be supplied with rationale and clear indication of the body setting the policy, and therefore the process in which the policy can be updated.
Preface¶
Introduction¶
Gentoo Policy Guide aims to become a definitive clear source of all Tree Policies that are currently binding to Gentoo developers. It combines both policies that are global by design (i.e. set by the QA team or the Council), as well as specific to other Gentoo projects. The policies are meant to be supplied with rationale and clear indication of the body setting the policy, and therefore the process in which the policy can be updated.
License¶
This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
Motivation and history¶
Historical state of policy documentation¶
At the time, Gentoo was lacking a clear and focused document listing all development-related policies in a concise and clear way.
PMS provided a technical specification for the ebuild files but did not provide a sufficient explanation on how to use it. Furthermore, PMS was focused on wider usage of the ebuild files than intended for the Gentoo repository, and therefore was partially restricted via tree policies.
Past Council decisions can be found in the Council meeting logs. However, their form makes it hard to find any particular decision, not to mention establishing a complete list of policies.
At some point, the QA team started listing QA policies on its wiki page. Only eight policies were listed so far. The policies were written out as a flat list with no particular order which is not going to scale well.
Finally, there was an attempt to turn devmanual into a source of reference policies. It was rejected by its maintainers as explicitly against the original purpose of this document. Furthermore, a large amount of stale information combined with ability to edit by every developer would make it unclear which parts are applicable policies, and which are obsolete or non-binding tips.
There are also project policies, scattered across wiki pages and other project documentation, and a lot of de facto policies that were established less or more formally in the past but were never really written down.
Purpose of the Policy Guide¶
The Policy Guide was created in order to address aforementioned documentation deficiencies. Its primary purpose is to collect all applicable policies from various sources and combine them into a single logically organized document.
Along with a wording of each policy, its rationale should be provided (if available) and an indication of which body set the policy. The former should make it possible to better understand the policy, and apply it in spirit rather than requiring very precise wording. The latter should make it clear who can be queried for additional information, and how the policy can be updated if need arises.
This Guide is going to replace the QA team policies page. All new QA policies will be documented directly in it. Other documentation (e.g. devmanual) should conform to policies stated here.
Basic information¶
Goals of policy making¶
The Gentoo policies focus on three aims:
Portability. By following the policies, it should be possible to package software so that it works on different system setups. This includes various supported architectures, basic system components, service managers, package managers, combinations of compiler and linker flags, etc.
Maintainability. The policies aim to provide consistent coding practices that make it easy for a different person to co-maintain the package or take over after previous maintainer. This also reduces the risk of mistakes experienced by the end users.
End-user experience. The policies try to help developers in providing a consistent end-user experience. The same concepts applied across different packages make it easier for user to achieve his goals and reduce the likeliness of surprising behavior.
Policy compliance checking¶
Currently, there are two kinds of tools involved in detecting policy violations:
Linting-class tools, including repoman and pkgcheck. Those tools analyze ebuilds and other files in the package repository for known policy violations. They are limited to checking for problems that can be detected without running the phase functions.
Build- and install-time QA checks, implemented in package managers. Those trigger while the ebuilds are executing. They are limited to testing the currently running code path.
Developers are expected to use both kinds of tools before pushing their commits. They should both lint the changed ebuilds using repoman or pkgcheck, and test whether their packages build and install correctly.
Additionally, Gentoo is running pkgcheck periodically as Gentoo CI. All non-trivial violations are reported to the gentoo-automated-testing mailing list and to the developers making the relevant commits. This supplements the direct use of linting tools by developers with reliable tree-wide scans.
Policy enforcement¶
The Gentoo QA team is tasked with enforcement of the tree policies. Its role is governed by GLEP 48. It focuses on documenting the policies, resolving doubts regarding them and educating the developers.
The QA team members can also take direct action in resolving minor quality problems (i.e. when fixing directly involves far less effort than if the developer was requested to fix it), or when developer refuses to resolve policy violations.
Finally, in case of repeated unwillingness to follow policies, the QA team can issue disciplinary measures against the developer in question.
Policy making, changes and appeals¶
The majority of policies are written down and maintained by the QA team. Other Gentoo projects also create policies that affect their specific areas of contributions (e.g. systemd project created policies related to installing systemd unit files).
Each policy listed in this document indicates the body maintaining it. In order to change or abolish the policy, that team should be contacted. If the project in question disagrees with the change, QA team can be asked to override the policy. All QA decisions and policies can further be appealed to the Council.
Other policy documents¶
Gentoo-specific documentation¶
Package Manager Specification¶
PMS provides the specification of ebuild format, as well as general guidelines for implementing package managers. All ebuilds in the Gentoo repository are required to conform to the PMS. Tree policies may enforce additional restrictions upon the format discussed in PMS.
PMS is maintained by the PMS project. All major changes are done in subsequent EAPIs that are approved by the Council. The project’s wiki page discusses how PMS can be changed via future EAPI process.
GLEPs¶
GLEPs provide the highest level policies applicable to Gentoo. Final or active GLEPs apply to all developers. Tree policies may impose additional restrictions on GLEPs but may not override them.
The process for creating and updating GLEPs is documented in GLEP 1. In general, all GLEP updates go through mailing list review and need to be approved by the Council.
Developer Manual¶
Devmanual is the basic guide for ebuild developers. Besides policies, it contains many general recommendations and detailed instructions. Developer Manual does not specify policies itself, and needs to comply with policies defined in this document.
Technically, devmanual can be changed by any developer. However, it is recommended that all changes are reviewed by the devmanual project.
External standards¶
POSIX¶
POSIX is the basic standard for operating systems. However, its rules apply to the software packaged in Gentoo rather than the distribution itself. Nevertheless, when no more specific policy applies, following POSIX is recommended.
FHS¶
FHS specifies the suggested filesystem layout for Linux systems. Gentoo follows FHS only partially. Whenever Gentoo policies and FHS disagree, Gentoo policies should be followed.
Editing and publishing updates to this Guide¶
Formatting and style¶
While editing the Guide, please respect the existing formatting rules. Notably:
wrap lines at 72 characters
two spaces between sentences (after full stop), one space otherwise
one empty line between titles and paragraphs, two empty lines between text and next section
indent using spaces, aligning to previous line
When adding a new rule, use the chapter with a fitting topic. Some rules match multiple chapters, choose the one that fits it best. Make sure to match existing keywords in index.
Getting sources¶
The reference repository is hosted at git.gentoo.org, and available via proj/policy-guide.git gitweb. To clone it:
# via https
git clone https://anongit.gentoo.org/git/proj/policy-guide.git
# via ssh
git clone git@git.gentoo.org:proj/policy-guide.git
Non-developers wishing to send pull requests may prefer to fork the GitHub gentoo/policy-guide repository and clone their own fork instead.
Building¶
A tox-file is provided to build the Guide in a virtualenv, installing all necessary dependencies. To build the HTML version, run:
tox
Another format (as well as other make arguments) can be specified as a command-line argument, e.g.:
tox latexpdf
Sending contributions¶
Changes to this document can be either submitted to Policy Manual Gentoo Bugzilla component as git-format patches attached to the bugs, or to gentoo/policy-guide repository as pull requests.
Merging pull requests¶
The recommended way to merge pull requests is to use
app-portage/pram. To configure the remote before the first use,
run the following command in your checkout:
git config --replace-all pram.repo gentoo/policy-guide
Afterwards, call the tool to merge pull request by number:
pram N
Publishing¶
The built version of Policy Guide is currently published via a git
repository. The recommended method is to clone the repository
into _build/html in order to make Sphinx output into the checkout:
rm -r _build/html
git clone git@git.gentoo.org:sites/projects/qa/policy-guide.git \
_build/html
Commit and push all the changes after rebuilding the Guide.
Dependencies¶
Optional runtime dependencies¶
- PG:
0001
- Source:
QA
- Reference:
- Reported:
no
Using USE flags to control optional runtime dependencies is not acceptable except under very specific circumstances, such as a package being nonfunctional unless at least one of a set of optional runtime dependencies is installed.
There is no specific preference as to how user should be informed
of optional runtime dependencies. Three possible ways are
optfeature eclass, readme.gentoo-r1 eclass and plain elog
messages.
Rationale: toggling USE flags in order to enable or disable optional runtime dependencies causes needless rebuilds of packages in question. This is especially important for packages that take long time to build.
Note
GLEP 62 proposes a solution permitting flipping USE flags without rebuilding package in question. It has been tentatively approved by the Council but no reference implementation has been written.
=-dependencies with no revision¶
- PG:
0002
- Source:
QA
- Reported:
by repoman and pkgcheck
Whenever a non-wildcard = (equals) dependency is used on a package,
the requested revision must be specified explicitly. When the zeroth
revision is requested, -r0 must be used. When no specific revision
is necessary, the ~ (tilde) operator must be used instead.
Example:
# BAD:
=dev-libs/libfrobnicate-1.2.3
# GOOD:
=dev-libs/libfrobnicate-1.2.3-r0
=dev-libs/libfrobnicate-1.2.3-r3
~dev-libs/libfrobnicate-1.2.3
Rationale: using = operator in place of ~ to mean a specific
version has been a common mistake. This policy uses the fact that
no revision and explicit -r0 are equivalent. By explicitly
requesting the latter, it warns developers to reconsider whether they
used the correct operator.
Slot and subslot dependencies¶
on (sub-)slotted packages¶
- PG:
0011
- Source:
QA
- Reference:
https://archives.gentoo.org/gentoo-portage-dev/message/9cae3a92412a007febe7ac0612d50f5f
- Reported:
by repoman and pkgcheck
Whenever a package dependency specification matches a range of versions
that span different slots or subslots, the package must explicitly
include slot specification. If the := operator is not applicable
and any slot is acceptable, explicit :* operator must be used.
If the :<slot>= operator is not applicable and only a specific slot
can be used, :<slot> value must be explicitly specified.
Package dependency specification without explicit slot specifier can be used on packages that are not slotted nor subslotted at the moment.
Rationale: this policy aims to help detecting missing slot operators
when dependencies start using slots or subslots. It uses the fact that
the explicit :* operator is equivalent to no slot specification,
and therefore can be used interchangeably. In this case, we assume
that the latter means ‘dependency not verified yet’, while the former
means ‘verified that any slot is acceptable’.
Note
The Paludis package manager applies different logic when no slot is specified on the dependency. It pulls in the slot corresponding to the newest package version available.
special case: Qt packages¶
- PG:
0012
- Source:
Qt project
- Reference:
https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies
- Reported:
no
The Qt packages use subslots in an uncommon way. The public ABI of Qt
libraries is stable within each slot, and the subslot is used to refer
to private ABI. Therefore, the := operator must only be used
if your package uses one of the private API parts, and plain :5
or likewise dependency must be used otherwise.
proactive use of slot operators¶
There is an open debate on whether developers should be proactively
adding := slot operators on packages that do not define subslots
yet.
Proponents of the idea point out that adding slot operators to reverse dependencies after the package becomes slotted is cumbersome and usually results in losing the subslot rebuild opportunity at least once. They argue that in many cases the future use of subslots is reasonably predictable.
Opponents claim that the future use of subslots is not 100% predictable. They point out the case of Qt packages as an example.
Revision bumps on runtime dependency changes¶
- PG:
0003
- Source:
Council
- Reference:
https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt
- Reported:
no
It must not be assumed that changes to package’s dependencies will be implicitly propagated to users who have installed the package already. Whenever the change needs to be propagated (e.g. to prevent a missing runtime dependency from being cleaned), the package revision must be increased.
This does not apply to build-time dependencies.
Rationale: developers were historically relying on Portage’s behavior called dynamic dependencies which caused Portage to implicitly use dependencies specified in matching ebuilds for installed packages. This is non-portable and unreliable. Users using different package managers, disabling the feature or simply missing the timeframe during which the old ebuild version existed had experienced dependency graph breakage and other problems due to it.
The policy requires developers to explicitly account for that possibility. Revision bumps ensure that users who installed the package from the previous ebuild version rebuild it and get the updated dependencies as a result.
Note
The dynamic dependency usage problem has a flip side. You can’t rely on in-place dependency changes not being propagated either. For example, if you notice that a package linked to libfoo unnecessarily, and decide to remove the dependency and code responsible for linking to it in place, Portage may apply the former immediately even if the package installed by the user still links to libfoo.
USE dependencies¶
on packages without the flag¶
- PG:
0021
- Source:
QA (inferred from PMS)
- Reported:
by pkgcheck
Whenever a package uses a 2-style USE-dependency on another package,
all package versions matching the dependency must have the flag
in question. If the dependency matches at least one version missing
the flag, either 4-style USE-dependency (i.e. having (-) or (+)
indicator) must be used, or the restriction must be refined to match
only versions having the flag.
Example:
# BAD: USE=gtk2 is not supported by v2
dev-foo/libfrobnicate[gtk2]
# GOOD: all matching versions have USE=tools
<dev-foo/libfrobnicate-2[gtk2]
# GOOD: indicate the default
dev-foo/libfrobnicate[gtk2(-)]
# BAD: USE=tools is no longer needed with v2
dev-foo/libbar[tools]
# GOOD: indicate the default
dev-foo/libbar[tools(+)]
Rationale: according to the PMS section on 2-style and 4-style USE dependencies, it is an error to apply 2-style USE dependency to a package missing the flag. Furthermore, checking for this makes it possible to report whenever USE flags on a package are changed without updating its reverse dependencies.
Deprecations¶
Deprecated EAPIs¶
- PG:
1001
- Source:
Council
- Reference:
https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/layout.conf
- Reported:
by pkgcheck and repoman
Deprecated EAPIs should not be used in new ebuilds. Existing packages should be migrated to newer EAPIs on version bumps, or proactively when no version bumps are expected.
The current list of deprecated EAPIs is stored as eapis-deprecated
in metadata/layout.conf.
Deprecated eclasses¶
- PG:
1003
- Source:
individual eclass maintainers
- Reported:
by pkgcheck and repoman
Deprecated eclasses should not be used in new ebuilds. Existing packages should be updated not to use these eclasses on version bumps, or proactively when no version bumps are expected.
Deprecations are indicated using the @DEPRECATED eclassdoc tag
inside the eclass files.
Ebuild file format¶
Coding style¶
- PG:
0101
- Source:
QA
- Reported:
partially via repoman and pkgcheck
While Gentoo leaves most of the coding style choices to developers, there are a few rules which we try to enforce. Those are:
Always indent using a single tab for indentation level. Do not attempt to align, as it will not work with different tab widths.
Whenever using named variables, use bracketed variable form, i.e.
${foo}rather than$foo.Use bash conditions
[[ ... ]]rather than POSIX-ish[ ... ]ortestbuiltin.
Rationale: the recommended constructs are less error-prone. Consistency avoids unnecessary changes when other developers edit the ebuild.
Code must be contained within ebuild and eclasses¶
- PG:
0102
- Source:
QA
- Reference:
- Reported:
no
The ebuild code must be fully contained within .ebuild and .eclass
files. It is forbidden to load additional ebuild code from other files
via source, eval or any other possible method.
This affects historical use of ‘eblits’ to include phase functions from external files. The eblits used by the few affected packages were converted into eclasses.
Rationale: moving ebuild code to non-standard locations is against the principle of least surprise. It makes the maintenance harder, confuses other developers and tools that do not explicitly account for that possibility, including linting tools.
HOMEPAGE must not contain variables¶
- PG:
0103
- Source:
QA
- Reported:
by pkgcheck, highlighted as error by gentoo-syntax
The HOMEPAGE variable in ebuild must specify all the URIs verbatim,
without referring to any variables. Variable references are allowed
when setting generic values in eclasses.
Rationale: since homepage URIs do not contain dynamic parts (such as package versions), there is little advantage to using variables there. On the other hand, variables render the URIs unusable without preprocessing, breaking URI support in terminals and editors, as well as reducing the usefulness of plain tools such as grep.
SRC_URI must not refer to HOMEPAGE¶
- PG:
0104
- Source:
QA
- Reported:
by pkgcheck
The SRC_URI variable in ebuild must not refer to ${HOMEPAGE}.
If both overlap, the common part must be repeated verbatim.
Rationale: HOMEPAGE permits multiple entries by design,
and developers are generally encouraged to add more helpful entries
(e.g. project pages on PyPI, GitHub…). Making individual URIs
incidentally depend on multi-valued variable having a single value
goes against the principle of least surprise. Furthermore, it makes
it hard to copy-paste part of the URI e.g. to investigate the directory
index.
KEYWORDS must be defined on a single line¶
- PG:
0105
- Source:
QA
- Reported:
no
The KEYWORDS variable must be defined at most once in an ebuild,
on a single line, with literal content (no variable references, line
wrapping, appending, etc.).
Rationale: it is common for arch teams to use the ekeyword tool
when working with large number of ebuilds. The tool has only limited
ability to process and modify ebuilds, and therefore developers must
make sure that it works correctly on their ebuilds.
LICENSE must not contain variables¶
- PG:
0106
- Source:
QA
- Reported:
no
The LICENSE variable in an ebuild must specify all the license names
verbatim, without referring to any variables. The only exception is
(implicit or explicit) use of LICENSE itself, i.e. appending is
allowed.
Rationale: since license names do not contain dynamic parts (such as package versions), using variables there has little advantage. On the other hand, variables reduce the usefulness of plain tools such as grep.
D must be used only in src_install and pkg_preinst¶
- PG:
0107
- Source:
QA
- Reported:
by pkgcheck
The D and ED variables must be used only in the src_install
and pkg_preinst phase functions. Exceptions to this policy can be
granted by the QA team.
Rationale: using D in other phases (e.g. src_configure) is
error-prone and may lead to the path being embedded in files of the
installed image. In addition, the directory pointed to by ${D}
does not exist in other phases.
File system layout¶
Installation paths¶
- PG:
0201
- Source:
QA
- Reference:
https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths
- Reported:
via install-qa-check.d
Gentoo packages may only install into one of the following top-level directories:
|
|
|
|
|
There must be no subdirectories in /bin and /sbin.
Furthermore, only the following subdirectories of /usr are permitted:
|
|
|
|
There must be no subdirectories in /usr/bin and /usr/sbin.
Furthermore, within /usr/share/doc hierarchy only a subdirectory named after full package name and version with revision (PF) is permitted.
In the aforementioned lists, ‘lib*’ indicates lib and its appropriate suffixed variants for the architecture in question. ‘<triplet>’ indicates either CHOST or CTARGET value, as used by toolchain packages.
Additional exceptions can be granted by the QA team. Currently those exceptions are:
/gnu for the guix package manager
/nix for the nix package manager
Support for separate /usr¶
- PG:
0202
- Source:
QA
- Reference:
https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt
- Reported:
no
Developers are not required to support using separate /usr filesystem without an initramfs.
Rationale: upstream software (as of 2013) is already making support for early boot without /usr mounted difficult, and whenever it is still works, it is either subtly broken or relying on hacks (udev). In setups using initramfs, some of the boot and repair functionality can be moved from rootfs to initramfs.
Strict multilib layout¶
- PG:
0203
- Source:
QA
- Reference:
https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict
- Reported:
via install-qa-check.d, fatal
Libraries must be installed into an appropriate /lib* or /usr/lib* directory corresponding to their ABI. For example, 64-bit libraries on amd64 must be installed into lib64 and not lib.
Libraries installed as a part of larger software package can be installed along with it into a subdirectory of lib.
Rationale: historically, Gentoo has been symlinking /lib to /lib64 in order to maintain compatibility with old packages hardcoding /lib path. With modern Gentoo profiles, this is no longer the case and packages must install libraries into appropriate directory for them to be correctly found by the dynamic loader.
Static libraries and libtool files¶
- PG:
0204
- Source:
QA
- Reference:
https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries
- Reported:
via install-qa-check.d, fatal
Static libraries and libtool files (.la) must be installed into /usr hierarchy and never to root filesystem (/lib*). If an additional shared version of the library is installed to /lib*, a .so linker script must be installed into /usr/lib* in order to ensure correct linking.
Rationale: historically, the purpose of root filesystem was to hold files strictly needed at boot. For this reason, many old Gentoo installations may still use small / partition. Static libraries are used only during package builds, and installing them to rootfs would be a waste of space.
Game install locations and ownership¶
- PG:
0205
- Source:
Council, clarified by QA
- Reference:
https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt
- Reported:
via install-qa-check.d
The historical game install locations (/usr/games and /etc/games) must not be used anymore. Instead, games should follow normal guidelines for install locations. As an exception, /usr/share/games can be used if this location is used upstream, and /var/games can be used for shared game files (e.g. high scores, game state files).
The historical games group must no longer be used. Games must work for users that are not in this group. The aforementioned install locations must therefore be owned by root and be world-readable.
If games need privileged access to shared files, the group gamestat can be used for this purpose. The game executables should be owned by that group and made setgid. The shared files must be installed into /var/games hierarchy, and writable to gamestat group.
Rationale: there is no technical reason to isolate games from other applications on the system, or to restrict access to them. The boundary between game and non-game packages is very blurry on modern systems, especially due to web browsers.
The historical use of games group on Gentoo to control access is inconsistent with the use in other distributions where it was used to share data files. Since the latter implied users must not be added to the games group, a new group (gamestat) needed to be created to fulfill that purpose.
Absolute symbolic link targets¶
- PG:
0206
- Source:
QA
- Reported:
by repoman and pkgcheck (when ebuild-generated)
Packages must not install symbolic links with absolute targets. Instead, relative paths must be used. An exception is granted for symlinks to specially mounted filesystems (such as /proc, /run) when symlinks are supposed to always reference the running host system.
Example:
# BAD:
dosym /usr/lib/frobnicate/frobnicate /usr/bin/frobnicate
# GOOD:
dosym ../lib/frobnicate/frobnicate /usr/bin/frobnicate
# ACCEPTABLE EXCEPTION:
dosym /proc/self/mounts /etc/mtab
Rationale: absolute symlinks work correctly only when the root filesystem is mounted at /. They point at the wrong location whenever it is mounted in another location, e.g. for the purposes of recovery.
Installed files¶
Installation of small files¶
- PG:
0301
- 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.
Installation of static libraries¶
- PG:
0302
- 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.
Note
If the package’s build system does not support disabling static
library build, it is recommended to patch it and submit the patch
upstream. However, if that is not feasible and building both shared
and static libraries does not require compiling source files twice,
it is acceptable to strip static libraries in src_install().
Installation of libtool (.la) files¶
- PG:
0303
- Source:
QA
- Reported:
no
Packages must not install libtool .la files unless they are explicitly required. Generally, they might be required if:
the package is using a plugin loader that requires .la files in order to locate plugins and does not have .so fallback (very uncommon),
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}" -type f -name '*.la' -delete || 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.
Virtuals¶
- PG:
0304
- Source:
QA
- Reported:
no
Packages in the virtual category must not install any files.
Rationale: The virtual category is reserved for packages with
an empty installation image. Package managers rely on this for some
optimizations. Also QA tools make certain assumptions about virtuals,
e.g., that they must not assign the LICENSE variable (which would
be impossible if they installed any files).
Installation of manpages¶
- PG:
0305
- Source:
QA
- Reported:
no
Packages must not disable installing manpages via USE flags (e.g.
USE=man or USE=doc). If upstream does not ship prebuilt
manpages and building them requires additional dependencies,
the maintainer should build them and ship along with the package.
Rationale: Manpages are basic documentation for installed software. While additional dependencies are inconvenient for users, not building manpages is harmful. Including (optionally or unconditionally) prebuilt manpages is a good compromise.
Keywording and stabilization¶
Rekeywording on dropped keywords¶
- PG:
0401
- Source:
QA
- Reported:
by pkgcheck and repoman
The developer removing keywords from a package (e.g. due to new dependencies) must file a rekeywording bug asking for the package being retested. This rule can be exempted if the package is known not to work (anymore) on the arch in question.
Rationale: rekeywording on minor architectures often takes a long time. If a developer neglects to request it immediately, it negatively affects other developers who in the future either want to stabilize a new version or to remove an old version.
Stabilizing new versions¶
- PG:
0402
- Source:
QA
- Reported:
by pkgcheck
Whenever requesting a stabilization of a new version of the package, the developer must CC all arches that had at least one previous stable version of the package in question, and that still have ~arch keywords in the stabilized version. This applies to experimental architectures as well.
The stabilization request can be closed and old stable version removed once all non-experimental architectures have processed the stabilization request. However, the remaining arch teams should be kept CC-ed in case they wanted to process the bug.
Rationale: there were some cases of developers requesting stabilization only of a subset of architectures they were personally interested in. This meant some other developer had to independently request stabilization on remaining architectures which only meant a duplication of effort and unnecessary confusion over which version is stable and whether arch teams are slacking or stabilization was not requested on remaining architectures in the first place.
Removing stable keywords¶
- PG:
0403
- Source:
QA
- Reference:
- Reported:
n/a
Stable keywords (or the last stable version) can be removed from a package if the relevant arch team does not respond within 90 days. If the removal causes a breakage of dependency graph, the developer must work with maintainers of the depending packages before proceeding with it.
The policy for removing a package must be followed here, with exception of last rite mails.
Language-specific policies¶
Python¶
Eclass usage¶
- PG:
0501
- Source:
Python project
- Reference:
- Reported:
by pkgcheck
All packages using Python (either through installing Python modules or scripts, linking to libpython, calling Python at runtime or build time) must do it through one of the python-r1 eclasses. Packages must not directly depend on Python, directly use PYTHON_SINGLE_TARGET or PYTHON_TARGETS. The variables and functions provided by the eclasses must be used instead.
All ebuilds must explicitly define supported Python implementations in PYTHON_COMPAT. Dependencies between Python packages must use PYTHON_USEDEP, PYTHON_SINGLE_USEDEP or python_gen_cond_dep in order to ensure implementation match.
Rationale: the eclass code guarantees consistent and reliable handling of slotted Python. It ensures that the whole dependency graph uses matching implementation and that programs will not accidentally break if user changes his Python preferences. The helper functions and variables also make it possible to gracefully retire old implementations with minimal changes to existing ebuilds.
Python 2 deprecation¶
- PG:
0502
- Source:
Python project
- Reference:
https://wiki.gentoo.org/wiki/Project:Python#Python_2_end-of-life
- Reported:
no
Python 2 is being phased out of Gentoo packages. Python 2 support must not be introduced in new packages, unless explicitly required to maintain compatibility with existing packages. Packages that do not support Python 3 should be removed sooner or later, depending on Python 3 porting chances.
In packages that support both Python 2 and Python 3, the Python 2 support should be gracefully retired, as soon as their reverse dependencies are ready or removed.
Rationale: Python 2 has reached its (deferred) end-of-life by the end of 2019. Many important upstream projects have already removed support for Python 2. Those packages are frequently dependencies of other packages, causing the cost of maintaining Python 2 support to grow exponentially.
Early removal of unnecessary Python 2 support will both reduce the long-term maintenance costs, and give users better chance to prepare than delaying it until the number of packages losing Python 2 support will cause major upgrade issues.
Package Maintainers¶
Adding new maintainers¶
- PG:
0601
- Source:
QA
- Reported:
no
Developers must not add other developers as package maintainers, unless the developers in question consent to that. Developers must not add projects that they are not members of as package maintainers, unless one of the project members explicitly agrees to that or the project policy explicitly permits it.
Rationale: this policy aims to prevent package maintainers being added as backup maintainers without their consent or knowledge. What’s worse, once the original maintainer resigns the packages frequently drop to backup maintainers who are neither interested in maintaining them, nor often aware why they are listed as maintainers.
For example, developers used to frequently add Python team as a backup maintainer to various packages not fitting the project’s profile. This includes various end-user programs written in Python. Many of those packages ended up being maintained solely by Python, and distinguishing them from packages actually within project’s profile was hard.
New packages without a maintainer¶
- PG:
0602
- Source:
QA
- Reported:
no
It is explicitly forbidden to add new packages without a dedicated maintainer. This does not apply if the package in question is not technically a new one but merely split out of unmaintained package.
Rationale: Gentoo is currently suffering from a very large number of packages without a maintainer. There is a small group of developers trying to fix them as necessary. It is unfair and inappropriate to increase their maintenance burden by adding new packages and refusing to take care of them.
Removing package maintainers¶
- PG:
0603
- Source:
QA
- Reported:
no
When removing maintainers from a package, the developer must reassign
all bugs filed for it. Furthermore, when removing the last maintainer
for a package, the developer must add the following comment
to metadata.xml:
<!-- maintainer-needed -->
Furthermore, the developer must send an ‘up for grabs’ mail to gentoo-dev mailing list, containing the list of packages with no maintainer. If possible, please include any information that could be helpful to future maintainers.
Rationale: reassigning bugs is necessary to make sure that old bugs are not lost assigned to developers who are no longer interested in them. The maintainer-needed comment is meant to make it possible to easily grep for unmaintained packages. The ‘up for grabs’ mails aim to increase the chances of packages finding a new maintainers (compared to them silently becoming maintainer-needed).
Other metadata variables¶
Dynamic slots (multislot flag)¶
- PG:
0701
- Source:
QA (inferred from PMS)
- Reference:
https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT, https://bugs.gentoo.org/174407
- Reported:
usein global scope triggers fatal error
The use of multislot to alter SLOT values (as well as any other
USE-dependent slot values) in the Gentoo repository is forbidden.
Such a feature can be used in overlays, and it is acceptable to provide
such support in eclasses as long as it is not used in ::gentoo.
This policy has been explicitly declared in response to historical
(pre-2016) use of USE=multislot in toolchain ebuilds. When the flag
was disabled, all package versions used the same slot, and upgrades were
handled as for non-slotted packages. When the flag was enabled, each
version used a separate slot, permitting multiple versions being
installed simultaneously. This allowed the user to choose between
the two options.
The original violation has been resolved by unconditionally slotting
the packages. This permitted the users to install multiple versions
in parallel, while removal of old versions was to be handled via
emerge --depclean.
Rationale: this feature was in direct violation of PMS metadata
invariance requirements. It caused the cached slot value to depend
on the state of querying the USE flag (which in turn could technically
depend on slot, via package.use). This caused undefined package
manager behavior which could include use of unpredictable slot, cache
invalidation or explicit errors.
HOMEPAGE value must be meaningful¶
- PG:
0702
- Source:
QA
- Reference:
https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035
- Reported:
known bad values are reported by pkgcheck
The HOMEPAGE specified for the package should either be dedicated
to the package in question or make it easy to find dedicated
information. Packages must not use https://www.gentoo.org/
or a similar generic homepage. If no homepage is available, the special
value of https://wiki.gentoo.org/wiki/No_homepage must be used.
Rationale: The homepage specified in ebuilds is normally used to locate information about the upstream project, e.g. downloads, source code repository, bug tracker, documentation. Homepages that make it hard to locate information about a specific project have little value, and the Gentoo homepage generally does not do a good job at linking even major Gentoo projects. Furthermore, many of the projects did not even have a single dedicated subpage anywhere in Gentoo web space. In all those cases, using the explicit No_homepage marker at least makes it easy to identify such packages.
RESTRICT=test for USE=-test¶
- PG:
0703
- Source:
QA
- Reported:
by pkgcheck
Whenever the package uses test flag to control test prerequisites
(or another flag with a similar purpose), it must explicitly restrict
tests when the flag is unset.
Example:
IUSE="test"
RESTRICT="!test? ( test )"
Rationale: contrary to common assumption, test flag is not special
and the package manager can execute tests when the flag is disabled.
The explicit restriction guarantees that tests will be skipped under
this circumstance, and they will not fail for users.
Note
Technically there are packages that do not strictly require this restriction since they handle missing test prerequisites gracefully (e.g. by skipping the tests). However, we enforce the rule for all packages since omitting the restriction by mistake is much more common, and there is little harm in overspecifying it.
LICENSE¶
- PG:
0704
- Source:
QA
- Reported:
no
The LICENSE variable must explicitly list all licenses pertaining
to the “corresponding source” of the files installed by the package.
This includes all their source code, but also all scripts used to
control compilation and installation. If some of the applicable
licenses are conditional to USE flags, appropriate USE conditionals
need to be expressed in the variable.
If a package bundles any dependencies that are either installed, statically linked or in any other way combined with installed files, the licenses of these dependencies need to be listed as well. This is not presently required when statically linking to dependencies installed by separate packages in the repository.
The licenses for files that are neither installed nor used at build time shall not be listed.
Rationale: the primary purpose of the license support in the package manager is to provide the users with ability to decide on acceptable licenses for their installed systems (and binary packages). In order for this to work effectively, the packages must provide a correct and complete license list.
Static linking combines code from multiple packages, potentially covered by different licenses. Listing all licenses is the simplest way of ensuring that nothing is missed, as well as protecting against wrong derivative work licenses stated upstream (i.e. when a less restrictively licensed package links to a more restrictively licensed dependency).
Listing of licenses is enforced for bundled dependencies but not for static linking to other packages, as in the latter case it is non-trivial to implement and the package manager already verifies the license while building dependencies (but not when installing binary packages).
Note
Please remember to include the licenses of support files provided by the ebuild, e.g. init.d scripts (usually GPL-2).
USE flags¶
Versioned USE flags¶
- PG:
0801
- Source:
QA
- Reference:
- Reported:
no
If a need arises to create new USE flags responsible for switching
between multiple versions of a specific dependency, it is recommended
that flat, explicitly versioned flags are used (e.g. qt4, qt5).
The hierarchical form used e.g. by GTK+ (gtk meaning 2-or-3,
then optionally gtk2 or gtk3 to switch between both)
is discouraged.
Any future set of USE flags introduced in this way needs to be discussed with the QA team before introduction.
Note
This policy has historically been defined as an generalization of the QA policy on gtk/gtk2/gtk3 flags. The latter policy has been removed since.
USE=gui flag¶
- PG:
0802
- Source:
QA
- Reference:
https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722
- Reported:
no
Whenever a package offers an optional GUI support, the gui flag must
be used to control that support rather than historically used X
or toolkit flags. Toolkit flags can still be used to choose between
multiple available GUIs, or when the toolkit is used in a more
specialized way than for GUI (e.g. to control installing widgets).
Rationale: the historical use of toolkit flags to control building GUIs made it very hard for users to express the simple wish of ‘I want any GUI’. Installing various packages made it necessary to either adjust flags per package (manually discovering which flags are necessary to obtain the GUI) or enabling multiple toolkits globally which afterwards caused issues with packages supporting a choice between multiple GUIs.
Underscores in USE flag names¶
- PG:
0803
- Source:
Council
- Reference:
https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt
- Reported:
by pkgcheck
Underscores are reserved for USE_EXPAND flags, and must not be used within names of newly-defined regular flags. Existing uses are considered technically valid, and phasing them out has low priority.
Flags that attempt to resemble USE_EXPAND should be either converted into proper (global) USE_EXPAND, or made into shorter (unprefixed) local flags. In other flags, replacing underscore with hyphen is recommended.
Rationale: a few packages in Gentoo attempted to imitate USE_EXPAND via local USE flags. This has no clear advantage, may be confusing to end users who assume that they will work like USE_EXPAND and in the end unnecessarily lengthens flag names or even causes unnecessary mismatches between global flags and local flags.
Extending the rule to all flags containing underscores aims to make distinguishing USE_EXPAND and regular flags easier. It also improves consistency between flag names that historically used hyphens or underscores depending on developer’s personal preference.
Users and groups¶
User and group account policy¶
- PG:
0901
- Source:
QA
- Reference:
- Reported:
by repoman and pkgcheck (as deprecated eclass)
All new user/group accounts must be created via GLEP 81 packages. The existing packages should be migrated on the next version bump or major update.
Existing and historical fixed UIDs/GIDs in range 0..499 (used in baselayout or via user.eclass) as listed in uid-gid.txt can be reused as-is in acct-* packages.
UIDs and GIDs in range 0..100 are reserved for important system accounts. New assignments in that range need to be explicitly approved by the QA lead, in response to a justified request from the developer.
The range 101..749 is provided for regular use by packages. The assignments from this range follow the following rules:
A developer can select an arbitrary free UID/GID from this range. If in doubt, it is recommended to select successive numbers from 101 upwards.
Unless there is a very good reason not to, matching users and groups should use the same number. It is acceptable to leave gaps in assignments as a result of that.
Before pushing the new acct-* packages, the developer must push an update to uid-gid.txt adding the ‘acct’ entry for the desired UID/GID. This serves as a synchronization primitive to prevent collisions.
Further UID/GID ranges will be open in the future as the need arises.
Rationale: this is the second version of the policy for GLEP 81 packages. It simplifies the process to aid rapid adoption of the new system. Review requirement and pointless cross-distro syncing were removed, in favor of a simple process of allocating the next free number and using it.
The ranges have been chosen to delay the imminent collision between explicitly reserved UIDs / GIDs and the ones allocated dynamically by user.eclass (starting from 999 downwards). The lowest GID range has been reserved for true system users and groups.