diff options
| -rw-r--r-- | combined.html | 1868 | ||||
| -rw-r--r-- | std-policy-index.html | 444 |
2 files changed, 2312 insertions, 0 deletions
diff --git a/combined.html b/combined.html new file mode 100644 index 0000000..5ec70aa --- /dev/null +++ b/combined.html @@ -0,0 +1,1868 @@ + +<!doctype html> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Gentoo Policy Guide documentation</title> + <link rel="stylesheet" href="_static/tyrian-sphinx-theme.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + <link rel="icon" href="https://www.gentoo.org/favicon.ico" type="image/x-icon"> + <link href="https://assets.gentoo.org/tyrian/bootstrap.min.css" rel="stylesheet" media="screen"> + <link href="https://assets.gentoo.org/tyrian/tyrian.min.css" rel="stylesheet" media="screen"> + <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <script src="_static/language_data.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + </head><body> + <header> + <div class="site-title"> + <div class="container"> + <div class="row"> + <div class="site-title-buttons"> + <div class="btn-group btn-group-sm"> + <a href="https://get.gentoo.org/" role="button" class="btn get-gentoo"><span class="fa fa-fw fa-download"></span> <strong>Get Gentoo!</strong></a> + <div class="btn-group btn-group-sm"> + <a class="btn gentoo-org-sites dropdown-toggle" data-toggle="dropdown" data-target="#" href="#"> + <span class="fa fa-fw fa-map-o"></span> <span class="hidden-xs">gentoo.org sites</span> <span class="caret"></span> + </a> + <ul class="dropdown-menu dropdown-menu-right"> + <li><a href="https://www.gentoo.org/" title="Main Gentoo website"><span class="fa fa-home fa-fw"></span> gentoo.org</a></li> + <li><a href="https://wiki.gentoo.org/" title="Find and contribute documentation"><span class="fa fa-file-text-o fa-fw"></span> Wiki</a></li> + <li><a href="https://bugs.gentoo.org/" title="Report issues and find common issues"><span class="fa fa-bug fa-fw"></span> Bugs</a></li> + <li><a href="https://forums.gentoo.org/" title="Discuss with the community"><span class="fa fa-comments-o fa-fw"></span> Forums</a></li> + <li><a href="https://packages.gentoo.org/" title="Find software for your Gentoo"><span class="fa fa-hdd-o fa-fw"></span> Packages</a></li> + <li class="divider"></li> + <li><a href="https://planet.gentoo.org/" title="Find out what's going on in the developer community"><span class="fa fa-rss fa-fw"></span> Planet</a></li> + <li><a href="https://archives.gentoo.org/" title="Read up on past discussions"><span class="fa fa-archive fa-fw"></span> Archives</a></li> + <li><a href="https://sources.gentoo.org/" title="Browse our source code"><span class="fa fa-code fa-fw"></span> Sources</a></li> + <li class="divider"></li> + <li><a href="https://infra-status.gentoo.org/" title="Get updates on the services provided by Gentoo"><span class="fa fa-server fa-fw"></span> Infra Status</a></li> + </ul> + </div> + </div> + </div> + <div class="logo"> + <a href="index.html" title="Back to the homepage" class="site-logo"></a> + <span class="site-label"> Policy Guide </span> + </div> + </div> + </div> + </div> + <nav class="tyrian-navbar" role="navigation"> + <div class="container"> + <div class="row"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + </div> + <div class="collapse navbar-collapse navbar-main-collapse"> + <ul class="nav navbar-nav"> + <li class="active"> + <a href="index.html">Home</a></li> + <li class=""><a href="https://gitweb.gentoo.org/proj/policy-guide.git/">Source</a></li> + + + + </ul> + + <form action="index.html" class="navbar-form navbar-right" method="get" onsubmit="if (this.quicksearch.value == '') + { alert('Please enter one or more search terms first.'); + return false; } return true;"> + + <div class="input-group" style="margin-top:2px;"> + <span class="input-group-addon" style="background:#61597b;color:#FFF;border:0px;" id="basic-addon1"><i class="fa fa-search" aria-hidden="true"></i></span> + <input class="form-control" style="height:30px;border:0px;background:#61597b;color:#FFF;padding-left:0px;box-shadow: none;" type="text" id="highlight" name="highlight" title="Quick Search" placeholder="Quick Search" value=""> + </div> + <button class="btn btn-default hidden" type="submit" value="Search" id="find_top">Search</button> + </form> + + </div> + </div> + </div> + </nav> + </header> + + + <div class="container"> + <div class="row"> + + + + <div class="col-md-9 col-sm-12 col-xs-12" role="main"> + + + + + + + <div class="section" id="gentoo-policy-guide"> +<h1>Gentoo Policy Guide<a class="headerlink" href="#gentoo-policy-guide" title="Permalink to this headline">¶</a></h1> +<p>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.</p> +<div class="toctree-wrapper compound"> +<span id="document-preface"></span><div class="section" id="preface"> +<h2>Preface<a class="headerlink" href="#preface" title="Permalink to this headline">¶</a></h2> +<div class="section" id="introduction"> +<h3>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h3> +<p>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.</p> +</div> +<div class="section" id="authors"> +<h3>Authors<a class="headerlink" href="#authors" title="Permalink to this headline">¶</a></h3> +<p>This document is maintained by the Gentoo <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA project</a>.</p> +<p>The current text authors are:</p> +<ul class="simple"> +<li><p>Michał Górny (mgorny)</p></li> +</ul> +</div> +<div class="section" id="license"> +<h3>License<a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h3> +<p>This work is licensed under the <a class="reference external" href="https://creativecommons.org/licenses/by-sa/4.0/.">Creative Commons Attribution-ShareAlike +4.0 International License</a>.</p> +</div> +</div> +<span id="document-motivation"></span><div class="section" id="motivation-and-history"> +<h2>Motivation and history<a class="headerlink" href="#motivation-and-history" title="Permalink to this headline">¶</a></h2> +<div class="section" id="historical-state-of-policy-documentation"> +<h3>Historical state of policy documentation<a class="headerlink" href="#historical-state-of-policy-documentation" title="Permalink to this headline">¶</a></h3> +<p>At the time, Gentoo was lacking a clear and focused document listing all +development-related policies in a concise and clear way.</p> +<p><a class="reference external" href="https://projects.gentoo.org/pms/latest/pms.html">PMS</a> 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.</p> +<p>Past Council decisions can be found in the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Council/Meeting_logs">Council meeting logs</a>. +However, their form makes it hard to find any particular decision, +not to mention establishing a complete list of policies.</p> +<p>At some point, the QA team started listing <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Policies">QA policies</a> 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.</p> +<p>Finally, there was an attempt to turn <a class="reference external" href="https://devmanual.gentoo.org/">devmanual</a> 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.</p> +<p>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.</p> +</div> +<div class="section" id="purpose-of-the-policy-guide"> +<h3>Purpose of the Policy Guide<a class="headerlink" href="#purpose-of-the-policy-guide" title="Permalink to this headline">¶</a></h3> +<p>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.</p> +<p>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.</p> +<p>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.</p> +</div> +</div> +<span id="document-basics"></span><div class="section" id="basic-information"> +<h2>Basic information<a class="headerlink" href="#basic-information" title="Permalink to this headline">¶</a></h2> +<div class="section" id="goals-of-policy-making"> +<h3>Goals of policy making<a class="headerlink" href="#goals-of-policy-making" title="Permalink to this headline">¶</a></h3> +<p>The Gentoo policies focus on three aims:</p> +<ol class="arabic simple"> +<li><p><em>Portability</em>. 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.</p></li> +<li><p><em>Maintainability</em>. 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.</p></li> +<li><p><em>End-user experience</em>. 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.</p></li> +</ol> +</div> +<div class="section" id="policy-compliance-checking"> +<h3>Policy compliance checking<a class="headerlink" href="#policy-compliance-checking" title="Permalink to this headline">¶</a></h3> +<p>Currently, there are two kinds of tools involved in detecting policy +violations:</p> +<ol class="arabic simple"> +<li><p>Linting-class tools, including <a class="reference external" href="https://wiki.gentoo.org/wiki/Repoman">repoman</a> and <a class="reference external" href="https://github.com/pkgcore/pkgcheck">pkgcheck</a>. 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.</p></li> +<li><p>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.</p></li> +</ol> +<p>Developers are expected to use both kinds of tools before pushing their +commits. They should both lint the changed ebuilds using <a class="reference external" href="https://wiki.gentoo.org/wiki/Repoman">repoman</a> +or <a class="reference external" href="https://github.com/pkgcore/pkgcheck">pkgcheck</a>, and test whether their packages build and install +correctly.</p> +<p>Additionally, Gentoo is running <a class="reference external" href="https://github.com/pkgcore/pkgcheck">pkgcheck</a> periodically as <a class="reference external" href="https://qa-reports.gentoo.org/output/gentoo-ci/output.html">Gentoo CI</a>. +All non-trivial violations are reported to the <a class="reference external" href="https://archives.gentoo.org/gentoo-automated-testing/">gentoo-automated-testing</a> +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.</p> +</div> +<div class="section" id="policy-enforcement"> +<h3>Policy enforcement<a class="headerlink" href="#policy-enforcement" title="Permalink to this headline">¶</a></h3> +<p>The Gentoo <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA team</a> is tasked with enforcement of the tree policies. +Its role is governed by <a class="reference external" href="https://www.gentoo.org/glep/glep-0048.html">GLEP 48</a>. It focuses on documenting +the policies, resolving doubts regarding them and educating +the developers.</p> +<p>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.</p> +<p>Finally, in case of repeated unwillingness to follow policies, the QA +team can issue disciplinary measures against the developer in question.</p> +</div> +<div class="section" id="policy-making-changes-and-appeals"> +<h3>Policy making, changes and appeals<a class="headerlink" href="#policy-making-changes-and-appeals" title="Permalink to this headline">¶</a></h3> +<p>The majority of policies are written down and maintained by the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA +team</a>. Other Gentoo projects also create policies that affect their +specific areas of contributions (e.g. <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Systemd">systemd project</a> created +policies related to installing systemd unit files).</p> +<p>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, <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Quality_Assurance">QA team</a> can be +asked to override the policy. All QA decisions and policies can further +be appealed to the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Council">Council</a>.</p> +</div> +</div> +<span id="document-other-docs"></span><div class="section" id="other-policy-documents"> +<h2>Other policy documents<a class="headerlink" href="#other-policy-documents" title="Permalink to this headline">¶</a></h2> +<div class="section" id="gentoo-specific-documentation"> +<h3>Gentoo-specific documentation<a class="headerlink" href="#gentoo-specific-documentation" title="Permalink to this headline">¶</a></h3> +<div class="section" id="package-manager-specification"> +<h4>Package Manager Specification<a class="headerlink" href="#package-manager-specification" title="Permalink to this headline">¶</a></h4> +<p><a class="reference external" href="https://projects.gentoo.org/pms/latest/pms.html">PMS</a> 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.</p> +<p>PMS is maintained by the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:PMS">PMS project</a>. 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 <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification/Future_EAPI_process">future EAPI process</a>.</p> +</div> +<div class="section" id="gleps"> +<h4>GLEPs<a class="headerlink" href="#gleps" title="Permalink to this headline">¶</a></h4> +<p><a class="reference external" href="https://www.gentoo.org/glep/">GLEPs</a> 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.</p> +<p>The process for creating and updating GLEPs is documented in <a class="reference external" href="https://www.gentoo.org/glep/glep-0001.html">GLEP 1</a>. +In general, all GLEP updates go through mailing list review and need +to be approved by the Council.</p> +</div> +<div class="section" id="developer-manual"> +<h4>Developer Manual<a class="headerlink" href="#developer-manual" title="Permalink to this headline">¶</a></h4> +<p><a class="reference external" href="https://devmanual.gentoo.org/">Devmanual</a> 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.</p> +<p>Technically, devmanual can be changed by any developer. However, it is +recommended that all changes are reviewed by the <a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Devmanual">devmanual project</a>.</p> +</div> +</div> +<div class="section" id="external-standards"> +<h3>External standards<a class="headerlink" href="#external-standards" title="Permalink to this headline">¶</a></h3> +<div class="section" id="posix"> +<h4>POSIX<a class="headerlink" href="#posix" title="Permalink to this headline">¶</a></h4> +<p><a class="reference external" href="http://get.posixcertified.ieee.org/">POSIX</a> 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.</p> +</div> +<div class="section" id="fhs"> +<h4>FHS<a class="headerlink" href="#fhs" title="Permalink to this headline">¶</a></h4> +<p><a class="reference external" href="https://refspecs.linuxfoundation.org/fhs.shtml">FHS</a> specifies the suggested filesystem layout for Linux systems. +Gentoo follows FHS only partially. Whenever Gentoo policies and FHS +disagree, Gentoo policies should be followed.</p> +</div> +</div> +</div> +<span id="document-dependencies"></span><div class="section" id="dependencies"> +<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2> +<span class="target" id="index-0"></span><div class="section" id="pg0001"> +<span id="optional-runtime-dependencies"></span><span id="index-1"></span><h3>Optional runtime dependencies<a class="headerlink" href="#pg0001" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0001</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=104017#USE-Controlled_Optional_RDEPENDS">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=104017#USE-Controlled_Optional_RDEPENDS</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>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.</p> +<p>There is no specific preference as to how user should be informed +of optional runtime dependencies. Three possible ways are +<code class="docutils literal notranslate"><span class="pre">optfeature</span></code> from <code class="docutils literal notranslate"><span class="pre">eutils</span></code> eclass, <code class="docutils literal notranslate"><span class="pre">readme.gentoo-r1</span></code> eclass +and plain <code class="docutils literal notranslate"><span class="pre">elog</span></code> messages.</p> +<p><em>Rationale</em>: 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.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p><a class="reference external" href="https://www.gentoo.org/glep/glep-0062.html">GLEP 62</a> 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.</p> +</div> +</div> +<div class="section" id="pg0002"> +<span id="dependencies-with-no-revision"></span><span id="index-2"></span><h3>=-dependencies with no revision<a class="headerlink" href="#pg0002" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0002</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by repoman and pkgcheck</p> +</dd> +</dl> +<p>Whenever a non-wildcard <code class="docutils literal notranslate"><span class="pre">=</span></code> (equals) dependency is used on a package, +the requested revision must be specified explicitly. When the zeroth +revision is requested, <code class="docutils literal notranslate"><span class="pre">-r0</span></code> must be used. When no specific revision +is necessary, the <code class="docutils literal notranslate"><span class="pre">~</span></code> (tilde) operator must be used instead.</p> +<p><em>Example</em>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># BAD:</span> +<span class="o">=</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2</span><span class="o">.</span><span class="mi">3</span> +<span class="c1"># GOOD:</span> +<span class="o">=</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2</span><span class="o">.</span><span class="mi">3</span><span class="o">-</span><span class="n">r0</span> +<span class="o">=</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2</span><span class="o">.</span><span class="mi">3</span><span class="o">-</span><span class="n">r3</span> +<span class="o">~</span><span class="n">dev</span><span class="o">-</span><span class="n">libs</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mf">1.2</span><span class="o">.</span><span class="mi">3</span> +</pre></div> +</div> +<p><em>Rationale</em>: using <code class="docutils literal notranslate"><span class="pre">=</span></code> operator in place of <code class="docutils literal notranslate"><span class="pre">~</span></code> to mean a specific +version has been a common mistake. This policy uses the fact that +no revision and explicit <code class="docutils literal notranslate"><span class="pre">-r0</span></code> are equivalent. By explicitly +requesting the latter, it warns developers to reconsider whether they +used the correct operator.</p> +</div> +<div class="section" id="slot-and-subslot-dependencies"> +<span id="index-3"></span><h3>Slot and subslot dependencies<a class="headerlink" href="#slot-and-subslot-dependencies" title="Permalink to this headline">¶</a></h3> +<div class="section" id="pg0011"> +<span id="on-sub-slotted-packages"></span><h4>on (sub-)slotted packages<a class="headerlink" href="#pg0011" title="Permalink to this headline">¶</a></h4> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0011</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://archives.gentoo.org/gentoo-portage-dev/message/9cae3a92412a007febe7ac0612d50f5f">https://archives.gentoo.org/gentoo-portage-dev/message/9cae3a92412a007febe7ac0612d50f5f</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>by repoman and pkgcheck</p> +</dd> +</dl> +<p>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 <code class="docutils literal notranslate"><span class="pre">:=</span></code> operator is not applicable +and any slot is acceptable, explicit <code class="docutils literal notranslate"><span class="pre">:*</span></code> operator must be used. +If the <code class="docutils literal notranslate"><span class="pre">:<slot>=</span></code> operator is not applicable and only a specific slot +can be used, <code class="docutils literal notranslate"><span class="pre">:<slot></span></code> value must be explicitly specified.</p> +<p>Package dependency specification without explicit slot specifier can +be used on packages that are not slotted nor subslotted at the moment.</p> +<p><em>Rationale</em>: this policy aims to help detecting missing slot operators +when dependencies start using slots or subslots. It uses the fact that +the explicit <code class="docutils literal notranslate"><span class="pre">:*</span></code> 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’.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>The <a class="reference external" href="https://paludis.exherbo.org/">Paludis</a> 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.</p> +</div> +</div> +<div class="section" id="pg0012"> +<span id="special-case-qt-packages"></span><span id="index-4"></span><h4>special case: Qt packages<a class="headerlink" href="#pg0012" title="Permalink to this headline">¶</a></h4> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0012</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>Qt project</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies">https://wiki.gentoo.org/wiki/Project:Qt/Policies#Dependencies</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>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 <code class="docutils literal notranslate"><span class="pre">:=</span></code> operator must only be used +if your package uses one of the private API parts, and plain <code class="docutils literal notranslate"><span class="pre">:5</span></code> +or likewise dependency must be used otherwise.</p> +</div> +<div class="section" id="proactive-use-of-slot-operators"> +<h4>proactive use of slot operators<a class="headerlink" href="#proactive-use-of-slot-operators" title="Permalink to this headline">¶</a></h4> +<p>There is an open debate on whether developers should be proactively +adding <code class="docutils literal notranslate"><span class="pre">:=</span></code> slot operators on packages that do not define subslots +yet.</p> +<p>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.</p> +<p>Opponents claim that the future use of subslots is not 100% predictable. +They point out the case of Qt packages as an example.</p> +</div> +</div> +<div class="section" id="pg0003"> +<span id="revision-bumps-on-runtime-dependency-changes"></span><span id="index-5"></span><h3>Revision bumps on runtime dependency changes<a class="headerlink" href="#pg0003" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0003</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>Council</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt">https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>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.</p> +<p>This does not apply to build-time dependencies.</p> +<p><em>Rationale</em>: developers were historically relying on Portage’s behavior +called <em>dynamic dependencies</em> 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.</p> +<p>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.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>The dynamic dependency usage problem has a flip side. You can’t rely +on in-place dependency changes <em>not</em> 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.</p> +</div> +</div> +<div class="section" id="use-dependencies"> +<span id="index-6"></span><h3>USE dependencies<a class="headerlink" href="#use-dependencies" title="Permalink to this headline">¶</a></h3> +<div class="section" id="pg0021"> +<span id="on-packages-without-the-flag"></span><h4>on packages without the flag<a class="headerlink" href="#pg0021" title="Permalink to this headline">¶</a></h4> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0021</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA (inferred from PMS)</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by pkgcheck</p> +</dd> +</dl> +<p>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 <code class="docutils literal notranslate"><span class="pre">(-)</span></code> or <code class="docutils literal notranslate"><span class="pre">(+)</span></code> +indicator) must be used, or the restriction must be refined to match +only versions having the flag.</p> +<p><em>Example</em>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># BAD: USE=gtk2 is not supported by v2</span> +<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="p">[</span><span class="n">gtk2</span><span class="p">]</span> +<span class="c1"># GOOD: all matching versions have USE=tools</span> +<span class="o"><</span><span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="o">-</span><span class="mi">2</span><span class="p">[</span><span class="n">gtk2</span><span class="p">]</span> +<span class="c1"># GOOD: indicate the default</span> +<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libfrobnicate</span><span class="p">[</span><span class="n">gtk2</span><span class="p">(</span><span class="o">-</span><span class="p">)]</span> + +<span class="c1"># BAD: USE=tools is no longer needed with v2</span> +<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libbar</span><span class="p">[</span><span class="n">tools</span><span class="p">]</span> +<span class="c1"># GOOD: indicate the default</span> +<span class="n">dev</span><span class="o">-</span><span class="n">foo</span><span class="o">/</span><span class="n">libbar</span><span class="p">[</span><span class="n">tools</span><span class="p">(</span><span class="o">+</span><span class="p">)]</span> +</pre></div> +</div> +<p><em>Rationale</em>: according to the PMS section on <a class="reference external" href="https://projects.gentoo.org/pms/7/pms.html#x1-790008.2.6.4">2-style and 4-style USE +dependencies</a>, 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.</p> +</div> +</div> +</div> +<span id="document-ebuild-format"></span><div class="section" id="ebuild-file-format"> +<h2>Ebuild file format<a class="headerlink" href="#ebuild-file-format" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0101"> +<span id="coding-style"></span><span id="index-0"></span><h3>Coding style<a class="headerlink" href="#pg0101" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0101</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>partially via repoman and pkgcheck</p> +</dd> +</dl> +<p>While Gentoo leaves most of the coding style choices to developers, +there are a few rules which we try to enforce. Those are:</p> +<ul class="simple"> +<li><p>Always indent using a single tab for indentation level. Do not +attempt to align, as it will not work with different tab widths.</p></li> +<li><p>Whenever using named variables, use bracketed variable form, i.e. +<code class="docutils literal notranslate"><span class="pre">${foo}</span></code> rather than <code class="docutils literal notranslate"><span class="pre">$foo</span></code>.</p></li> +<li><p>Use bash conditions <code class="docutils literal notranslate"><span class="pre">[[</span> <span class="pre">...</span> <span class="pre">]]</span></code> rather than POSIX-ish <code class="docutils literal notranslate"><span class="pre">[</span> <span class="pre">...</span> <span class="pre">]</span></code> +or <code class="docutils literal notranslate"><span class="pre">test</span></code> builtin.</p></li> +</ul> +<p><em>Rationale</em>: the recommended constructs are less error-prone. +Consistency avoids unnecessary changes when other developers edit +the ebuild.</p> +</div> +<div class="section" id="pg0102"> +<span id="code-must-be-contained-within-ebuild-and-eclasses"></span><span id="index-1"></span><h3>Code must be contained within ebuild and eclasses<a class="headerlink" href="#pg0102" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0102</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://bugs.gentoo.org/612630">https://bugs.gentoo.org/612630</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>The ebuild code must be fully contained within .ebuild and .eclass +files. It is forbidden to load additional ebuild code from other files +via <code class="docutils literal notranslate"><span class="pre">source</span></code>, <code class="docutils literal notranslate"><span class="pre">eval</span></code> or any other possible method.</p> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0103"> +<span id="homepage-must-not-contain-variables"></span><span id="index-2"></span><h3>HOMEPAGE must not contain variables<a class="headerlink" href="#pg0103" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0103</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by pkgcheck, highlighted as error by gentoo-syntax</p> +</dd> +</dl> +<p>The <code class="docutils literal notranslate"><span class="pre">HOMEPAGE</span></code> variable in ebuild must specify all the URIs verbatim, +without referring to any variables. Variable references are allowed +when setting generic values in eclasses.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0104"> +<span id="src-uri-must-not-refer-to-homepage"></span><span id="index-3"></span><h3>SRC_URI must not refer to HOMEPAGE<a class="headerlink" href="#pg0104" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0104</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by pkgcheck</p> +</dd> +</dl> +<p>The <code class="docutils literal notranslate"><span class="pre">SRC_URI</span></code> variable in ebuild must not refer to <code class="docutils literal notranslate"><span class="pre">${HOMEPAGE}</span></code>. +If both overlap, the common part must be repeated verbatim.</p> +<p><em>Rationale</em>: <code class="docutils literal notranslate"><span class="pre">HOMEPAGE</span></code> 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.</p> +</div> +<div class="section" id="pg0105"> +<span id="keywords-must-be-defined-on-a-single-line"></span><span id="index-4"></span><h3>KEYWORDS must be defined on a single line<a class="headerlink" href="#pg0105" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0105</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>The <code class="docutils literal notranslate"><span class="pre">KEYWORDS</span></code> variable must be defined at most once in an ebuild, +on a single line, with literal content (no variable references, line +wrapping, appending, etc.).</p> +<p><em>Rationale</em>: it is common for arch teams to use the <code class="docutils literal notranslate"><span class="pre">ekeyword</span></code> 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.</p> +</div> +</div> +<span id="document-filesystem"></span><div class="section" id="file-system-layout"> +<h2>File system layout<a class="headerlink" href="#file-system-layout" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0201"> +<span id="installation-paths"></span><span id="index-0"></span><h3>Installation paths<a class="headerlink" href="#pg0201" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0201</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths">https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>via install-qa-check.d</p> +</dd> +</dl> +<p>Gentoo packages may only install into one of the following top-level +directories:</p> +<table class="hlist"><tr><td><ul class="simple"> +<li><p>/bin</p></li> +<li><p>/boot</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/dev</p></li> +<li><p>/etc</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/lib*</p></li> +<li><p>/opt</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/sbin</p></li> +<li><p>/srv</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr</p></li> +<li><p>/var</p></li> +</ul> +</td></tr></table> +<p>Furthermore, only the following subdirectories of /usr are permitted:</p> +<table class="hlist"><tr><td><ul class="simple"> +<li><p>/usr/bin</p></li> +<li><p>/usr/include</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr/lib*</p></li> +<li><p>/usr/libexec</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr/sbin</p></li> +<li><p>/usr/share</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr/src</p></li> +<li><p>/usr/<triplet></p></li> +</ul> +</td></tr></table> +<p>Furthermore, within /usr/share/doc hierarchy only a subdirectory named +after full package name and version with revision (PF) is permitted.</p> +<p>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.</p> +<p>Additional exceptions can be granted by the QA team. Currently those +exceptions are:</p> +<ul class="simple"> +<li><p>/gnu for the guix package manager</p></li> +<li><p>/nix for the nix package manager</p></li> +</ul> +</div> +<div class="section" id="pg0202"> +<span id="support-for-separate-usr"></span><span id="index-1"></span><h3>Support for separate /usr<a class="headerlink" href="#pg0202" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0202</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt">https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt</a> +<a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt">https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>Developers are not required to support using separate /usr filesystem +without an initramfs.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0203"> +<span id="strict-multilib-layout"></span><span id="index-2"></span><h3>Strict multilib layout<a class="headerlink" href="#pg0203" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0203</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict">https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>via install-qa-check.d, fatal</p> +</dd> +</dl> +<p>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.</p> +<p>Libraries installed as a part of larger software package can be +installed along with it into a subdirectory of lib.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0204"> +<span id="static-libraries-and-libtool-files"></span><span id="index-3"></span><h3>Static libraries and libtool files<a class="headerlink" href="#pg0204" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0204</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries">https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>via install-qa-check.d, fatal</p> +</dd> +</dl> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0205"> +<span id="game-install-locations-and-ownership"></span><span id="index-4"></span><h3>Game install locations and ownership<a class="headerlink" href="#pg0205" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0205</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>Council, clarified by QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt">https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt</a> +<a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt">https://projects.gentoo.org/council/meeting-logs/20151011-summary.txt</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>via install-qa-check.d</p> +</dd> +</dl> +<p>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).</p> +<p>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.</p> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +<p>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.</p> +</div> +<div class="section" id="pg0206"> +<span id="absolute-symbolic-link-targets"></span><span id="index-5"></span><h3>Absolute symbolic link targets<a class="headerlink" href="#pg0206" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0206</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by repoman and pkgcheck (when ebuild-generated)</p> +</dd> +</dl> +<p>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.</p> +<p><em>Example</em>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># BAD:</span> +<span class="n">dosym</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">lib</span><span class="o">/</span><span class="n">frobnicate</span><span class="o">/</span><span class="n">frobnicate</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">frobnicate</span> +<span class="c1"># GOOD:</span> +<span class="n">dosym</span> <span class="o">../</span><span class="n">lib</span><span class="o">/</span><span class="n">frobnicate</span><span class="o">/</span><span class="n">frobnicate</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">frobnicate</span> +<span class="c1"># ACCEPTABLE EXCEPTION:</span> +<span class="n">dosym</span> <span class="o">/</span><span class="n">proc</span><span class="o">/</span><span class="bp">self</span><span class="o">/</span><span class="n">mounts</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">mtab</span> +</pre></div> +</div> +<p><em>Rationale</em>: 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.</p> +</div> +</div> +<span id="document-installed-files"></span><div class="section" id="installed-files"> +<h2>Installed files<a class="headerlink" href="#installed-files" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0301"> +<span id="installation-of-small-files"></span><span id="index-0"></span><h3>Installation of small files<a class="headerlink" href="#pg0301" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0301</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>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.</p> +<p>Users wishing to strip unnecessary files of this category should use +INSTALL_MASK to do so.</p> +<p><em>Rationale</em>: 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.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>While technically e.g. <code class="docutils literal notranslate"><span class="pre">app-shells/bash-completion</span></code> 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.</p> +</div> +</div> +<div class="section" id="pg0302"> +<span id="installation-of-static-libraries"></span><span id="index-1"></span><h3>Installation of static libraries<a class="headerlink" href="#pg0302" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0302</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>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 <code class="docutils literal notranslate"><span class="pre">USE=static-libs</span></code> may be added for static +libraries if they are necessary.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0303"> +<span id="installation-of-libtool-la-files"></span><span id="index-2"></span><h3>Installation of libtool (.la) files<a class="headerlink" href="#pg0303" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0303</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>Packages must not install libtool .la files unless they are explicitly +required. Generally, they might be required if:</p> +<ol class="loweralpha simple"> +<li><p>the package is using a plugin loader that requires .la files in order +to locate plugins and does not have .so fallback (very uncommon),</p></li> +<li><p>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.</p></li> +</ol> +<p>It is recommended to use the following one-liner to remove .la files:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">find</span> <span class="s2">"$</span><span class="si">{ED}</span><span class="s2">"</span> <span class="o">-</span><span class="n">name</span> <span class="s1">'*.la'</span> <span class="o">-</span><span class="n">remove</span> <span class="o">||</span> <span class="n">die</span> +</pre></div> +</div> +<p><em>Rationale</em>: 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.</p> +</div> +</div> +<span id="document-keywords"></span><div class="section" id="keywording-and-stabilization"> +<h2>Keywording and stabilization<a class="headerlink" href="#keywording-and-stabilization" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0401"> +<span id="rekeywording-on-dropped-keywords"></span><span id="index-0"></span><h3>Rekeywording on dropped keywords<a class="headerlink" href="#pg0401" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0401</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by pkgcheck and repoman</p> +</dd> +</dl> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0402"> +<span id="stabilizing-new-versions"></span><span id="index-1"></span><h3>Stabilizing new versions<a class="headerlink" href="#pg0402" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0402</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by pkgcheck</p> +</dd> +</dl> +<p>Whenever requesting a stabilization of a new version of the package, +the developer must CC <em>all</em> 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.</p> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0403"> +<span id="removing-stable-keywords"></span><span id="index-2"></span><h3>Removing stable keywords<a class="headerlink" href="#pg0403" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0403</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=126033#Dropping_Stable_KEYWORDs">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=126033#Dropping_Stable_KEYWORDs</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>n/a</p> +</dd> +</dl> +<p>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.</p> +<p>The policy for removing a package must be followed here, with exception +of last rite mails.</p> +</div> +</div> +<span id="document-languages"></span><div class="section" id="language-specific-policies"> +<h2>Language-specific policies<a class="headerlink" href="#language-specific-policies" title="Permalink to this headline">¶</a></h2> +<div class="section" id="python"> +<span id="index-0"></span><h3>Python<a class="headerlink" href="#python" title="Permalink to this headline">¶</a></h3> +<span class="target" id="index-1"></span><span class="target" id="index-2"></span><span class="target" id="index-3"></span><div class="section" id="pg0501"> +<span id="eclass-usage"></span><span id="index-4"></span><h4>Eclass usage<a class="headerlink" href="#pg0501" title="Permalink to this headline">¶</a></h4> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0501</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>Python project</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Python/Eclasses">https://wiki.gentoo.org/wiki/Project:Python/Eclasses</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>by pkgcheck</p> +</dd> +</dl> +<p>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.</p> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0502"> +<span id="python-2-deprecation"></span><span id="index-5"></span><h4>Python 2 deprecation<a class="headerlink" href="#pg0502" title="Permalink to this headline">¶</a></h4> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0502</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>Python project</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/wiki/Project:Python#Python_2_end-of-life">https://wiki.gentoo.org/wiki/Project:Python#Python_2_end-of-life</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>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.</p> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +<p>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.</p> +</div> +</div> +</div> +<span id="document-maintainer"></span><div class="section" id="package-maintainers"> +<h2>Package Maintainers<a class="headerlink" href="#package-maintainers" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0601"> +<span id="adding-new-maintainers"></span><span id="index-0"></span><h3>Adding new maintainers<a class="headerlink" href="#pg0601" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0601</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +<p>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.</p> +</div> +<div class="section" id="pg0602"> +<span id="new-packages-without-a-maintainer"></span><span id="index-1"></span><h3>New packages without a maintainer<a class="headerlink" href="#pg0602" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0602</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +<span class="target" id="index-2"></span></div> +<div class="section" id="pg0603"> +<span id="removing-package-maintainers"></span><span id="index-3"></span><h3>Removing package maintainers<a class="headerlink" href="#pg0603" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0603</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>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 <code class="docutils literal notranslate"><span class="pre">metadata.xml</span></code>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><!-- maintainer-needed --> +</pre></div> +</div> +<p>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.</p> +<p><em>Rationale</em>: 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).</p> +</div> +</div> +<span id="document-other-metadata"></span><div class="section" id="other-metadata-variables"> +<h2>Other metadata variables<a class="headerlink" href="#other-metadata-variables" title="Permalink to this headline">¶</a></h2> +<span class="target" id="index-0"></span><div class="section" id="pg0701"> +<span id="dynamic-slots-multislot-flag"></span><span id="index-1"></span><h3>Dynamic slots (multislot flag)<a class="headerlink" href="#pg0701" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0701</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA (inferred from PMS)</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#multislot.2FUSE-dependent_SLOT</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p><code class="docutils literal notranslate"><span class="pre">use</span></code> in global scope triggers fatal error</p> +</dd> +</dl> +<p>The use of <code class="docutils literal notranslate"><span class="pre">multislot</span></code> to alter <code class="docutils literal notranslate"><span class="pre">SLOT</span></code> 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.</p> +<p>This policy has been explicitly declared in response to historical +(pre-2016) use of <code class="docutils literal notranslate"><span class="pre">USE=multislot</span></code> 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.</p> +<p>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 +<code class="docutils literal notranslate"><span class="pre">emerge</span> <span class="pre">--depclean</span></code>.</p> +<p><em>Rationale</em>: this feature was in direct violation of PMS <a class="reference external" href="https://projects.gentoo.org/pms/7/pms.html#x1-600007.1">metadata +invariance</a> 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 <code class="docutils literal notranslate"><span class="pre">package.use</span></code>). This caused undefined package +manager behavior which could include use of unpredictable slot, cache +invalidation or explicit errors.</p> +</div> +<div class="section" id="pg0702"> +<span id="homepage-value-must-be-meaningful"></span><span id="index-2"></span><h3>HOMEPAGE value must be meaningful<a class="headerlink" href="#pg0702" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0702</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035">https://archives.gentoo.org/gentoo-dev/message/83cc5bbd7bbe8bdf04dd3c3bc7f8a035</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>known bad values are reported by pkgcheck</p> +</dd> +</dl> +<p>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 <code class="docutils literal notranslate"><span class="pre">https://www.gentoo.org/</span></code> +or a similar generic homepage. If no homepage is available, the special +value of <code class="docutils literal notranslate"><span class="pre">https://wiki.gentoo.org/wiki/No_homepage</span></code> must be used.</p> +<p><em>Rationale</em>: 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.</p> +</div> +<div class="section" id="pg0703"> +<span id="restrict-test-for-use-test"></span><span id="index-3"></span><h3>RESTRICT=test for USE=-test<a class="headerlink" href="#pg0703" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0703</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by pkgcheck</p> +</dd> +</dl> +<p>Whenever the package uses <code class="docutils literal notranslate"><span class="pre">test</span></code> flag to control test prerequisites +(or another flag with a similar purpose), it must explicitly restrict +tests when the flag is unset.</p> +<p><em>Example</em>:</p> +<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">IUSE</span><span class="o">=</span><span class="s2">"test"</span> +<span class="n">RESTRICT</span><span class="o">=</span><span class="s2">"!test? ( test )"</span> +</pre></div> +</div> +<p><em>Rationale</em>: contrary to common assumption, <code class="docutils literal notranslate"><span class="pre">test</span></code> 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.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>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.</p> +</div> +</div> +<div class="section" id="pg0704"> +<span id="license"></span><span id="index-4"></span><h3>LICENSE<a class="headerlink" href="#pg0704" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0704</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>The <code class="docutils literal notranslate"><span class="pre">LICENSE</span></code> variable must explicitly list licenses for all files +installed by the package. If some of the applicable licenses are +conditional to USE flags, appropriate USE conditionals need to +be expressed in the variable.</p> +<p>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.</p> +<p>The licenses for files that are not installed but that are used at build +time are not listed explicitly.</p> +<p><em>Rationale</em>: 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.</p> +<p>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).</p> +<p>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).</p> +<p>The ebuild format does not provide a separate variable to list licenses +needed only at build time. So far it has not been considered important +enough to have one, as the relevant files exist only temporarily +on the user’s system and do not affect the runtime use of packages.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>Please remember to include the licenses of support files provided +by the ebuild, e.g. init.d scripts (usually GPL-2).</p> +</div> +</div> +</div> +<span id="document-use-flags"></span><div class="section" id="use-flags"> +<h2>USE flags<a class="headerlink" href="#use-flags" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0801"> +<span id="versioned-use-flags"></span><span id="index-0"></span><h3>Versioned USE flags<a class="headerlink" href="#pg0801" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0801</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#Versioned_USE_flags">https://wiki.gentoo.org/index.php?title=Project:Quality_Assurance/Policies&oldid=109991#Versioned_USE_flags</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>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. <code class="docutils literal notranslate"><span class="pre">qt4</span></code>, <code class="docutils literal notranslate"><span class="pre">qt5</span></code>). +The hierarchical form used e.g. by GTK+ (<code class="docutils literal notranslate"><span class="pre">gtk</span></code> meaning 2-or-3, +then optionally <code class="docutils literal notranslate"><span class="pre">gtk2</span></code> or <code class="docutils literal notranslate"><span class="pre">gtk3</span></code> to switch between both) +is discouraged.</p> +<p>Any future set of USE flags introduced in this way needs to be discussed +with the QA team before introduction.</p> +<div class="admonition note"> +<p class="admonition-title">Note</p> +<p>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.</p> +</div> +</div> +<div class="section" id="pg0802"> +<span id="use-gui-flag"></span><span id="index-1"></span><h3>USE=gui flag<a class="headerlink" href="#pg0802" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0802</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722">https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>no</p> +</dd> +</dl> +<p>Whenever a package offers an optional GUI support, the <code class="docutils literal notranslate"><span class="pre">gui</span></code> flag must +be used to control that support rather than historically used <code class="docutils literal notranslate"><span class="pre">X</span></code> +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).</p> +<p><em>Rationale</em>: the historical use of toolkit flags to control building +GUIs made it very hard for users to express the simple wish of ‘I want +<em>any</em> 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.</p> +</div> +<div class="section" id="pg0803"> +<span id="underscores-in-use-flag-names"></span><span id="index-2"></span><h3>Underscores in USE flag names<a class="headerlink" href="#pg0803" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0803</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>Council</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt">https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>by pkgcheck</p> +</dd> +</dl> +<p>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.</p> +<p>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.</p> +<p><em>Rationale</em>: 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.</p> +<p>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.</p> +</div> +</div> +<span id="document-user-group"></span><div class="section" id="users-and-groups"> +<h2>Users and groups<a class="headerlink" href="#users-and-groups" title="Permalink to this headline">¶</a></h2> +<span class="target" id="index-0"></span><div class="section" id="pg0901"> +<span id="user-and-group-account-policy"></span><span id="index-1"></span><h3>User and group account policy<a class="headerlink" href="#pg0901" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0901</p> +</dd> +<dt class="field-even">Source</dt> +<dd class="field-even"><p>QA</p> +</dd> +<dt class="field-odd">Reference</dt> +<dd class="field-odd"><p><a class="reference external" href="https://bugs.gentoo.org/702460">https://bugs.gentoo.org/702460</a></p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><p>by repoman and pkgcheck (as deprecated eclass)</p> +</dd> +</dl> +<p>All new user/group accounts must be created via <a class="reference external" href="https://www.gentoo.org/glep/glep-0081.html">GLEP 81</a> packages. +The existing packages should be migrated on the next version bump or +major update.</p> +<p>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.</p> +<p>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.</p> +<p>The range 101..499 is provided for regular use by packages. +The assignments from this range follow the following rules:</p> +<ol class="arabic simple"> +<li><p>A developer can select an arbitrary free UID/GID from this range. +If in doubt, it is recommended to select successive numbers from 499 +downwards.</p></li> +<li><p>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.</p></li> +<li><p>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.</p></li> +</ol> +<p>Further UID/GID ranges will be open in the future as the need arises.</p> +<p><em>Rationale</em>: 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.</p> +<p>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.</p> +</div> +</div> +</div> +</div> +<div class="section" id="indices-and-tables"> +<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1> +<ul class="simple"> +<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li> +<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li> +</ul> +</div> + + + + + + + + + + </div> + + + <div class="col-md-3 hidden-sm hidden-xs" role="main"> +<div class="" role="navigation" aria-label="main navigation"> + <div class=""> + + <nav class="bs-docs-sidebar" data-spy="affix" data-offset-top="140" data-offset-bottom="400"> + <p class="hidden"><span class="hidden-text">Contents:</span></p> +<ul class='nav'> +<li class="toctree-l1"><a class="reference internal" href="#document-preface">Preface</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="#authors">Authors</a></li> +<li class="toctree-l2"><a class="reference internal" href="#license">License</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-motivation">Motivation and history</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#historical-state-of-policy-documentation">Historical state of policy documentation</a></li> +<li class="toctree-l2"><a class="reference internal" href="#purpose-of-the-policy-guide">Purpose of the Policy Guide</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-basics">Basic information</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#goals-of-policy-making">Goals of policy making</a></li> +<li class="toctree-l2"><a class="reference internal" href="#policy-compliance-checking">Policy compliance checking</a></li> +<li class="toctree-l2"><a class="reference internal" href="#policy-enforcement">Policy enforcement</a></li> +<li class="toctree-l2"><a class="reference internal" href="#policy-making-changes-and-appeals">Policy making, changes and appeals</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-other-docs">Other policy documents</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#gentoo-specific-documentation">Gentoo-specific documentation</a><ul class='nav'> +<li class="toctree-l3"><a class="reference internal" href="#package-manager-specification">Package Manager Specification</a></li> +<li class="toctree-l3"><a class="reference internal" href="#gleps">GLEPs</a></li> +<li class="toctree-l3"><a class="reference internal" href="#developer-manual">Developer Manual</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="#external-standards">External standards</a><ul class='nav'> +<li class="toctree-l3"><a class="reference internal" href="#posix">POSIX</a></li> +<li class="toctree-l3"><a class="reference internal" href="#fhs">FHS</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-dependencies">Dependencies</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0001">Optional runtime dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0002">=-dependencies with no revision</a></li> +<li class="toctree-l2"><a class="reference internal" href="#slot-and-subslot-dependencies">Slot and subslot dependencies</a><ul class='nav'> +<li class="toctree-l3"><a class="reference internal" href="#pg0011">on (sub-)slotted packages</a></li> +<li class="toctree-l3"><a class="reference internal" href="#pg0012">special case: Qt packages</a></li> +<li class="toctree-l3"><a class="reference internal" href="#proactive-use-of-slot-operators">proactive use of slot operators</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="#pg0003">Revision bumps on runtime dependency changes</a></li> +<li class="toctree-l2"><a class="reference internal" href="#use-dependencies">USE dependencies</a><ul class='nav'> +<li class="toctree-l3"><a class="reference internal" href="#pg0021">on packages without the flag</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-ebuild-format">Ebuild file format</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0101">Coding style</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0102">Code must be contained within ebuild and eclasses</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0103">HOMEPAGE must not contain variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0104">SRC_URI must not refer to HOMEPAGE</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0105">KEYWORDS must be defined on a single line</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-filesystem">File system layout</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0201">Installation paths</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0202">Support for separate /usr</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0203">Strict multilib layout</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0204">Static libraries and libtool files</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0205">Game install locations and ownership</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0206">Absolute symbolic link targets</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-installed-files">Installed files</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0301">Installation of small files</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0302">Installation of static libraries</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0303">Installation of libtool (.la) files</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-keywords">Keywording and stabilization</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0401">Rekeywording on dropped keywords</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0402">Stabilizing new versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0403">Removing stable keywords</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-languages">Language-specific policies</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#python">Python</a><ul class='nav'> +<li class="toctree-l3"><a class="reference internal" href="#pg0501">Eclass usage</a></li> +<li class="toctree-l3"><a class="reference internal" href="#pg0502">Python 2 deprecation</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-maintainer">Package Maintainers</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0601">Adding new maintainers</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0602">New packages without a maintainer</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0603">Removing package maintainers</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-other-metadata">Other metadata variables</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0701">Dynamic slots (multislot flag)</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0702">HOMEPAGE value must be meaningful</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0703">RESTRICT=test for USE=-test</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0704">LICENSE</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-use-flags">USE flags</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0801">Versioned USE flags</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0802">USE=gui flag</a></li> +<li class="toctree-l2"><a class="reference internal" href="#pg0803">Underscores in USE flag names</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="#document-user-group">Users and groups</a><ul class='nav'> +<li class="toctree-l2"><a class="reference internal" href="#pg0901">User and group account policy</a></li> +</ul> +</li> +</ul> + + + </nav> + </div> +</div> + </div> + + </div> + <div class="clearer"></div> + </div> + <footer> + <div class="container"> + <div class="row"> + <div class="col-xs-12 col-md-offset-2 col-md-7"> + <h3 class="footerhead">None</h3> + <div class="row"> + <div class="col-xs-12 col-md-4"> + <span class="kk-group-header">Powered by</span><br><span><a href="http://sphinx-doc.org/">Sphinx 2.4.3</a> & <a href="https://github.com/mmagorsc/tyrian_sphinx_theme">Tyrian Theme 0.0.7</a></span> + </div> + <div class="col-xs-12 col-md-4"> + </div> + <div class="col-xs-12 col-md-4"> + </div> + </div> + </div> + <div class="col-xs-12 col-md-3"> + <h3 class="footerhead">Questions or comments?</h3> + Please feel free to <a href="https://www.gentoo.org/inside-gentoo/contact/">contact us</a>. + </div> + </div> + <div class="row"> + <div class="col-xs-2 col-sm-3 col-md-2"> + <ul class="footerlinks three-icons"> + <li><a href="https://twitter.com/gentoo" title="@Gentoo on Twitter"><span class="fa fa-twitter fa-fw"></span></a></li> + <li><a href="https://plus.google.com/+Gentoo" title="+Gentoo on Google+"><span class="fa fa-google-plus fa-fw"></span></a></li> + <li><a href="https://www.facebook.com/gentoo.org" title="Gentoo on Facebook"><span class="fa fa-facebook fa-fw"></span></a></li> + </ul> + </div> + <div class="col-xs-10 col-sm-9 col-md-10"> + <strong>© 2001–2020 Gentoo Foundation, Inc.</strong><br> + <small> + Gentoo is a trademark of the Gentoo Foundation, Inc. + The contents of this document, unless otherwise expressly stated, are licensed under the + <a href="https://creativecommons.org/licenses/by-sa/4.0/" rel="license">CC-BY-SA-4.0</a> license. + The <a href="https://www.gentoo.org/inside-gentoo/foundation/name-logo-guidelines.html">Gentoo Name and Logo Usage Guidelines</a> apply. + </small> + </div> + </div> + </div> + </footer> + + <script src="https://assets.gentoo.org/tyrian/bootstrap.min.js"></script> + + <div id="custom_toc"> + <span style="border-bottom: 1px solid #e1e1e1;font-weight: bold;">Contents</span> + [<a class="" id="show_contents" role="button" data-toggle="collapse" href="#collapseExample" aria-expanded="false" aria-controls="collapseExample">show</a>] + <div class="collapse" id="collapseExample" style="margin-top:10px;"> + <p class="caption"><span class="caption-text">Contents:</span></p> +<ul> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-preface">Preface</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#introduction">Introduction</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#authors">Authors</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#license">License</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-motivation">Motivation and history</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#historical-state-of-policy-documentation">Historical state of policy documentation</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#purpose-of-the-policy-guide">Purpose of the Policy Guide</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-basics">Basic information</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#goals-of-policy-making">Goals of policy making</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#policy-compliance-checking">Policy compliance checking</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#policy-enforcement">Policy enforcement</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#policy-making-changes-and-appeals">Policy making, changes and appeals</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-other-docs">Other policy documents</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#gentoo-specific-documentation">Gentoo-specific documentation</a><ul> +<li class="toctree-l3"><a class="reference internal" href="index.html#package-manager-specification">Package Manager Specification</a></li> +<li class="toctree-l3"><a class="reference internal" href="index.html#gleps">GLEPs</a></li> +<li class="toctree-l3"><a class="reference internal" href="index.html#developer-manual">Developer Manual</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="index.html#external-standards">External standards</a><ul> +<li class="toctree-l3"><a class="reference internal" href="index.html#posix">POSIX</a></li> +<li class="toctree-l3"><a class="reference internal" href="index.html#fhs">FHS</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-dependencies">Dependencies</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0001">Optional runtime dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0002">=-dependencies with no revision</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#slot-and-subslot-dependencies">Slot and subslot dependencies</a><ul> +<li class="toctree-l3"><a class="reference internal" href="index.html#pg0011">on (sub-)slotted packages</a></li> +<li class="toctree-l3"><a class="reference internal" href="index.html#pg0012">special case: Qt packages</a></li> +<li class="toctree-l3"><a class="reference internal" href="index.html#proactive-use-of-slot-operators">proactive use of slot operators</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0003">Revision bumps on runtime dependency changes</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#use-dependencies">USE dependencies</a><ul> +<li class="toctree-l3"><a class="reference internal" href="index.html#pg0021">on packages without the flag</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-ebuild-format">Ebuild file format</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0101">Coding style</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0102">Code must be contained within ebuild and eclasses</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0103">HOMEPAGE must not contain variables</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0104">SRC_URI must not refer to HOMEPAGE</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0105">KEYWORDS must be defined on a single line</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-filesystem">File system layout</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0201">Installation paths</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0202">Support for separate /usr</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0203">Strict multilib layout</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0204">Static libraries and libtool files</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0205">Game install locations and ownership</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0206">Absolute symbolic link targets</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-installed-files">Installed files</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0301">Installation of small files</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0302">Installation of static libraries</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0303">Installation of libtool (.la) files</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-keywords">Keywording and stabilization</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0401">Rekeywording on dropped keywords</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0402">Stabilizing new versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0403">Removing stable keywords</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-languages">Language-specific policies</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#python">Python</a><ul> +<li class="toctree-l3"><a class="reference internal" href="index.html#pg0501">Eclass usage</a></li> +<li class="toctree-l3"><a class="reference internal" href="index.html#pg0502">Python 2 deprecation</a></li> +</ul> +</li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-maintainer">Package Maintainers</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0601">Adding new maintainers</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0602">New packages without a maintainer</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0603">Removing package maintainers</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-other-metadata">Other metadata variables</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0701">Dynamic slots (multislot flag)</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0702">HOMEPAGE value must be meaningful</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0703">RESTRICT=test for USE=-test</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0704">LICENSE</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-use-flags">USE flags</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0801">Versioned USE flags</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0802">USE=gui flag</a></li> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0803">Underscores in USE flag names</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="index.html#document-user-group">Users and groups</a><ul> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0901">User and group account policy</a></li> +</ul> +</li> +</ul> + + </div> + + </div> + + <script type="text/javascript"> + $("#custom_toc").prependTo(".toctree-wrapper"); + $("#custom_toc").css("display", "inline-block"); + + $('#collapseExample').on('show.bs.collapse', function () { + $("#show_contents").html("hide"); + }) + + $('#collapseExample').on('hide.bs.collapse', function () { + $("#show_contents").html("show"); + }) + + $("#collapseExample").collapse('show'); + $("#show_contents").html("hide"); + + </script> + + + <script type="text/javascript"> + $('body').scrollspy({ + target: '.bs-docs-sidebar', + offset: 40 + }); + </script> + + + <script type="text/javascript"> + $('#indices-and-tables').hide() + </script> + + + + + + + + </body> +</html> + diff --git a/std-policy-index.html b/std-policy-index.html new file mode 100644 index 0000000..7aace05 --- /dev/null +++ b/std-policy-index.html @@ -0,0 +1,444 @@ + +<!doctype html> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>Policy Index — Gentoo Policy Guide documentation</title> + <link rel="stylesheet" href="_static/tyrian-sphinx-theme.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + <link rel="icon" href="https://www.gentoo.org/favicon.ico" type="image/x-icon"> + <link href="https://assets.gentoo.org/tyrian/bootstrap.min.css" rel="stylesheet" media="screen"> + <link href="https://assets.gentoo.org/tyrian/tyrian.min.css" rel="stylesheet" media="screen"> + <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> + <script src="_static/jquery.js"></script> + <script src="_static/underscore.js"></script> + <script src="_static/doctools.js"></script> + <script src="_static/language_data.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + + + + </head><body> + <header> + <div class="site-title"> + <div class="container"> + <div class="row"> + <div class="site-title-buttons"> + <div class="btn-group btn-group-sm"> + <a href="https://get.gentoo.org/" role="button" class="btn get-gentoo"><span class="fa fa-fw fa-download"></span> <strong>Get Gentoo!</strong></a> + <div class="btn-group btn-group-sm"> + <a class="btn gentoo-org-sites dropdown-toggle" data-toggle="dropdown" data-target="#" href="#"> + <span class="fa fa-fw fa-map-o"></span> <span class="hidden-xs">gentoo.org sites</span> <span class="caret"></span> + </a> + <ul class="dropdown-menu dropdown-menu-right"> + <li><a href="https://www.gentoo.org/" title="Main Gentoo website"><span class="fa fa-home fa-fw"></span> gentoo.org</a></li> + <li><a href="https://wiki.gentoo.org/" title="Find and contribute documentation"><span class="fa fa-file-text-o fa-fw"></span> Wiki</a></li> + <li><a href="https://bugs.gentoo.org/" title="Report issues and find common issues"><span class="fa fa-bug fa-fw"></span> Bugs</a></li> + <li><a href="https://forums.gentoo.org/" title="Discuss with the community"><span class="fa fa-comments-o fa-fw"></span> Forums</a></li> + <li><a href="https://packages.gentoo.org/" title="Find software for your Gentoo"><span class="fa fa-hdd-o fa-fw"></span> Packages</a></li> + <li class="divider"></li> + <li><a href="https://planet.gentoo.org/" title="Find out what's going on in the developer community"><span class="fa fa-rss fa-fw"></span> Planet</a></li> + <li><a href="https://archives.gentoo.org/" title="Read up on past discussions"><span class="fa fa-archive fa-fw"></span> Archives</a></li> + <li><a href="https://sources.gentoo.org/" title="Browse our source code"><span class="fa fa-code fa-fw"></span> Sources</a></li> + <li class="divider"></li> + <li><a href="https://infra-status.gentoo.org/" title="Get updates on the services provided by Gentoo"><span class="fa fa-server fa-fw"></span> Infra Status</a></li> + </ul> + </div> + </div> + </div> + <div class="logo"> + <a href="index.html" title="Back to the homepage" class="site-logo"></a> + <span class="site-label"> Policy Guide </span> + </div> + </div> + </div> + </div> + <nav class="tyrian-navbar" role="navigation"> + <div class="container"> + <div class="row"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + </div> + <div class="collapse navbar-collapse navbar-main-collapse"> + <ul class="nav navbar-nav"> + <li> + <a href="index.html">Home</a></li> + <li class=""><a href="https://gitweb.gentoo.org/proj/policy-guide.git/">Source</a></li> + <li> + <a href="search.html">Search</a></li> + + + <li> + + <a href="genindex.html">General Index</a> + + </li> + + <li class="active"> + + <a href="std-policy-index.html">Policy Index</a> + + </li> + + + + + + </ul> + + <form action="search.html" class="navbar-form navbar-right" method="get" onsubmit="if (this.quicksearch.value == '') + { alert('Please enter one or more search terms first.'); + return false; } return true;"> + + <div class="input-group" style="margin-top:2px;"> + <span class="input-group-addon" style="background:#61597b;color:#FFF;border:0px;" id="basic-addon1"><i class="fa fa-search" aria-hidden="true"></i></span> + <input class="form-control" style="height:30px;border:0px;background:#61597b;color:#FFF;padding-left:0px;box-shadow: none;" type="text" id="quicksearch_top" name="q" title="Quick Search" placeholder="Quick Search" value=""> + </div> + <button class="btn btn-default hidden" type="submit" value="Search" id="find_top">Search</button> + </form> + + </div> + </div> + </div> + </nav> + </header> + + + <div class="container"> + <div class="row"> + + + + <div class="col-md-9 col-sm-12 col-xs-12" role="main"> + + + + + + + + <h1>Policy Index</h1> + + <div class="modindex-jumpbox"> + <a href="#cap-Dependencies"><strong>Dependencies</strong></a> | + <a href="#cap-Ebuild file format"><strong>Ebuild file format</strong></a> | + <a href="#cap-File system layout"><strong>File system layout</strong></a> | + <a href="#cap-Installed files"><strong>Installed files</strong></a> | + <a href="#cap-Keywording and stabilization"><strong>Keywording and stabilization</strong></a> | + <a href="#cap-Language-specific policies"><strong>Language-specific policies</strong></a> | + <a href="#cap-Package Maintainers"><strong>Package Maintainers</strong></a> | + <a href="#cap-Other metadata variables"><strong>Other metadata variables</strong></a> | + <a href="#cap-USE flags"><strong>USE flags</strong></a> | + <a href="#cap-Users and groups"><strong>Users and groups</strong></a> + </div> + + <table class="indextable modindextable"> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Dependencies"><td></td><td> + <strong>Dependencies</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="dependencies.html#pg0001"><code class="xref">PG0001</code></a> <em>(Optional runtime dependencies)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="dependencies.html#pg0002"><code class="xref">PG0002</code></a> <em>(=-dependencies with no revision)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="dependencies.html#pg0003"><code class="xref">PG0003</code></a> <em>(Revision bumps on runtime dependency changes)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="dependencies.html#pg0011"><code class="xref">PG0011</code></a> <em>(Slot and subslot dependencies: on (sub-)slotted packages)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="dependencies.html#pg0012"><code class="xref">PG0012</code></a> <em>(Slot and subslot dependencies: special case: Qt packages)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="dependencies.html#pg0021"><code class="xref">PG0021</code></a> <em>(USE dependencies: on packages without the flag)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Ebuild file format"><td></td><td> + <strong>Ebuild file format</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="ebuild-format.html#pg0101"><code class="xref">PG0101</code></a> <em>(Coding style)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="ebuild-format.html#pg0102"><code class="xref">PG0102</code></a> <em>(Code must be contained within ebuild and eclasses)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="ebuild-format.html#pg0103"><code class="xref">PG0103</code></a> <em>(HOMEPAGE must not contain variables)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="ebuild-format.html#pg0104"><code class="xref">PG0104</code></a> <em>(SRC_URI must not refer to HOMEPAGE)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="ebuild-format.html#pg0105"><code class="xref">PG0105</code></a> <em>(KEYWORDS must be defined on a single line)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-File system layout"><td></td><td> + <strong>File system layout</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="filesystem.html#pg0201"><code class="xref">PG0201</code></a> <em>(Installation paths)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="filesystem.html#pg0202"><code class="xref">PG0202</code></a> <em>(Support for separate /usr)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="filesystem.html#pg0203"><code class="xref">PG0203</code></a> <em>(Strict multilib layout)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="filesystem.html#pg0204"><code class="xref">PG0204</code></a> <em>(Static libraries and libtool files)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="filesystem.html#pg0205"><code class="xref">PG0205</code></a> <em>(Game install locations and ownership)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="filesystem.html#pg0206"><code class="xref">PG0206</code></a> <em>(Absolute symbolic link targets)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Installed files"><td></td><td> + <strong>Installed files</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="installed-files.html#pg0301"><code class="xref">PG0301</code></a> <em>(Installation of small files)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="installed-files.html#pg0302"><code class="xref">PG0302</code></a> <em>(Installation of static libraries)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="installed-files.html#pg0303"><code class="xref">PG0303</code></a> <em>(Installation of libtool (.la) files)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Keywording and stabilization"><td></td><td> + <strong>Keywording and stabilization</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="keywords.html#pg0401"><code class="xref">PG0401</code></a> <em>(Rekeywording on dropped keywords)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="keywords.html#pg0402"><code class="xref">PG0402</code></a> <em>(Stabilizing new versions)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="keywords.html#pg0403"><code class="xref">PG0403</code></a> <em>(Removing stable keywords)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Language-specific policies"><td></td><td> + <strong>Language-specific policies</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="languages.html#pg0501"><code class="xref">PG0501</code></a> <em>(Python: Eclass usage)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="languages.html#pg0502"><code class="xref">PG0502</code></a> <em>(Python: Python 2 deprecation)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Package Maintainers"><td></td><td> + <strong>Package Maintainers</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="maintainer.html#pg0601"><code class="xref">PG0601</code></a> <em>(Adding new maintainers)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="maintainer.html#pg0602"><code class="xref">PG0602</code></a> <em>(New packages without a maintainer)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="maintainer.html#pg0603"><code class="xref">PG0603</code></a> <em>(Removing package maintainers)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Other metadata variables"><td></td><td> + <strong>Other metadata variables</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="other-metadata.html#pg0701"><code class="xref">PG0701</code></a> <em>(Dynamic slots (multislot flag))</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="other-metadata.html#pg0702"><code class="xref">PG0702</code></a> <em>(HOMEPAGE value must be meaningful)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="other-metadata.html#pg0703"><code class="xref">PG0703</code></a> <em>(RESTRICT=test for USE=-test)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="other-metadata.html#pg0704"><code class="xref">PG0704</code></a> <em>(LICENSE)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-USE flags"><td></td><td> + <strong>USE flags</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="use-flags.html#pg0801"><code class="xref">PG0801</code></a> <em>(Versioned USE flags)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="use-flags.html#pg0802"><code class="xref">PG0802</code></a> <em>(USE=gui flag)</em></td><td> + <em></em></td></tr> + <tr> + <td></td> + <td> + <a href="use-flags.html#pg0803"><code class="xref">PG0803</code></a> <em>(Underscores in USE flag names)</em></td><td> + <em></em></td></tr> + <tr class="pcap"><td></td><td> </td><td></td></tr> + <tr class="cap" id="cap-Users and groups"><td></td><td> + <strong>Users and groups</strong></td><td></td></tr> + <tr> + <td></td> + <td> + <a href="user-group.html#pg0901"><code class="xref">PG0901</code></a> <em>(User and group account policy)</em></td><td> + <em></em></td></tr> + </table> + + + + + + + + + + </div> + + + <div class="col-md-3 hidden-sm hidden-xs" role="main"> +<div class="" role="navigation" aria-label="main navigation"> + <div class=""> + </div> +</div> + </div> + + </div> + <div class="clearer"></div> + </div> + <footer> + <div class="container"> + <div class="row"> + <div class="col-xs-12 col-md-offset-2 col-md-7"> + <h3 class="footerhead">Gentoo Policy Guide </h3> + <div class="row"> + <div class="col-xs-12 col-md-4"> + <span class="kk-group-header">Powered by</span><br><span><a href="http://sphinx-doc.org/">Sphinx 2.4.3</a> & <a href="https://github.com/mmagorsc/tyrian_sphinx_theme">Tyrian Theme 0.0.7</a></span> + </div> + <div class="col-xs-12 col-md-4"> + </div> + <div class="col-xs-12 col-md-4"> + </div> + </div> + </div> + <div class="col-xs-12 col-md-3"> + <h3 class="footerhead">Questions or comments?</h3> + Please feel free to <a href="https://www.gentoo.org/inside-gentoo/contact/">contact us</a>. + </div> + </div> + <div class="row"> + <div class="col-xs-2 col-sm-3 col-md-2"> + <ul class="footerlinks three-icons"> + <li><a href="https://twitter.com/gentoo" title="@Gentoo on Twitter"><span class="fa fa-twitter fa-fw"></span></a></li> + <li><a href="https://plus.google.com/+Gentoo" title="+Gentoo on Google+"><span class="fa fa-google-plus fa-fw"></span></a></li> + <li><a href="https://www.facebook.com/gentoo.org" title="Gentoo on Facebook"><span class="fa fa-facebook fa-fw"></span></a></li> + </ul> + </div> + <div class="col-xs-10 col-sm-9 col-md-10"> + <strong>© 2001–2020 Gentoo Foundation, Inc.</strong><br> + <small> + Gentoo is a trademark of the Gentoo Foundation, Inc. + The contents of this document, unless otherwise expressly stated, are licensed under the + <a href="https://creativecommons.org/licenses/by-sa/4.0/" rel="license">CC-BY-SA-4.0</a> license. + The <a href="https://www.gentoo.org/inside-gentoo/foundation/name-logo-guidelines.html">Gentoo Name and Logo Usage Guidelines</a> apply. + </small> + </div> + </div> + </div> + </footer> + + <script src="https://assets.gentoo.org/tyrian/bootstrap.min.js"></script> + + + <script type="text/javascript"> + $('body').scrollspy({ + target: '.bs-docs-sidebar', + offset: 40 + }); + </script> + + + <script type="text/javascript"> + $('#indices-and-tables').hide() + </script> + + + + + + + + </body> +</html> + |