diff options
Diffstat (limited to 'combined.html')
| -rw-r--r-- | combined.html | 354 |
1 files changed, 188 insertions, 166 deletions
diff --git a/combined.html b/combined.html index 478b358..ce8ced8 100644 --- a/combined.html +++ b/combined.html @@ -5,7 +5,8 @@ <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> - <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="viewport" content="width=device-width, initial-scale=1"><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" /> + <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" /> @@ -14,11 +15,13 @@ <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"> + <link rel="stylesheet" type="text/css" href="_static/pygments.css" /> + <link rel="stylesheet" type="text/css" href="_static/tyrian-sphinx-theme.css" /> <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> + <script data-url_root="./" id="documentation_options" 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> @@ -107,7 +110,7 @@ - <div class="section" id="gentoo-policy-guide"> + <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. @@ -117,9 +120,9 @@ 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"> +<span id="document-preface"></span><section id="preface"> <h2>Preface<a class="headerlink" href="#preface" title="Permalink to this headline">¶</a></h2> -<div class="section" id="introduction"> +<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. @@ -128,24 +131,24 @@ 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"> +</section> +<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"> +</section> +<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"> +</section> +</section> +<span id="document-motivation"></span><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"> +<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> @@ -171,8 +174,8 @@ and which are obsolete or non-binding tips.</p> 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"> +</section> +<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 @@ -187,11 +190,11 @@ 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"> +</section> +</section> +<span id="document-basics"></span><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"> +<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"> @@ -209,8 +212,8 @@ 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"> +</section> +<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> @@ -232,8 +235,8 @@ All non-trivial violations are reported to the <a class="reference external" hre 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"> +</section> +<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 @@ -245,8 +248,8 @@ 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"> +</section> +<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 @@ -257,13 +260,13 @@ 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"> +</section> +</section> +<span id="document-other-docs"></span><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"> +<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"> +<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 @@ -272,8 +275,8 @@ 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"> +</section> +<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 @@ -281,8 +284,8 @@ 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"> +</section> +<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. @@ -290,28 +293,28 @@ 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"> +</section> +</section> +<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"> +<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"> +</section> +<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"> +</section> +</section> +</section> +<span id="document-dependencies"></span><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 class="target" id="index-0"></span><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> @@ -333,8 +336,8 @@ 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> +<code class="docutils literal notranslate"><span class="pre">optfeature</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> @@ -344,8 +347,8 @@ This is especially important for packages that take long time to build.</p> 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"> +</section> +<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> @@ -364,11 +367,11 @@ revision is requested, <code class="docutils literal notranslate"><span class="p 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="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.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> +<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.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.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.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 @@ -376,10 +379,10 @@ 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"> +</section> +<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"> +<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> @@ -415,8 +418,8 @@ means ‘verified that any slot is acceptable’.</p> 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"> +</section> +<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> @@ -437,8 +440,8 @@ 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"> +</section> +<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 @@ -450,9 +453,9 @@ 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"> +</section> +</section> +<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> @@ -494,10 +497,10 @@ 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"> +</section> +<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"> +<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> @@ -535,12 +538,12 @@ 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-deprecation"></span><div class="section" id="deprecations"> +</section> +</section> +</section> +<span id="document-deprecation"></span><section id="deprecations"> <h2>Deprecations<a class="headerlink" href="#deprecations" title="Permalink to this headline">¶</a></h2> -<div class="section" id="pg1001"> +<section id="pg1001"> <span id="deprecated-eapis"></span><span id="index-0"></span><h3>Deprecated EAPIs<a class="headerlink" href="#pg1001" title="Permalink to this headline">¶</a></h3> <dl class="field-list simple"> <dt class="field-odd">PG</dt> @@ -561,8 +564,8 @@ should be migrated to newer EAPIs on version bumps, or proactively when no version bumps are expected.</p> <p>The current list of deprecated EAPIs is stored as <code class="docutils literal notranslate"><span class="pre">eapis-deprecated</span></code> in <code class="docutils literal notranslate"><span class="pre">metadata/layout.conf</span></code>.</p> -</div> -<div class="section" id="pg1003"> +</section> +<section id="pg1003"> <span id="deprecated-eclasses"></span><span id="index-1"></span><h3>Deprecated eclasses<a class="headerlink" href="#pg1003" title="Permalink to this headline">¶</a></h3> <dl class="field-list simple"> <dt class="field-odd">PG</dt> @@ -571,11 +574,8 @@ in <code class="docutils literal notranslate"><span class="pre">metadata/layout. <dt class="field-even">Source</dt> <dd class="field-even"><p>individual eclass maintainers</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/qa-policy.conf">https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/qa-policy.conf</a></p> -</dd> -<dt class="field-even">Reported</dt> -<dd class="field-even"><p>by pkgcheck and repoman</p> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>by pkgcheck and repoman</p> </dd> </dl> <p>Deprecated eclasses should not be used in new ebuilds. Existing @@ -583,11 +583,11 @@ packages should be updated not to use these eclasses on version bumps, or proactively when no version bumps are expected.</p> <p>Deprecations are indicated using the <code class="docutils literal notranslate"><span class="pre">@DEPRECATED</span></code> eclassdoc tag inside the eclass files.</p> -</div> -</div> -<span id="document-ebuild-format"></span><div class="section" id="ebuild-file-format"> +</section> +</section> +<span id="document-ebuild-format"></span><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"> +<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> @@ -613,8 +613,8 @@ or <code class="docutils literal notranslate"><span class="pre">test</span></cod <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"> +</section> +<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> @@ -640,8 +640,8 @@ converted into eclasses.</p> 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"> +</section> +<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> @@ -662,8 +662,8 @@ 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"> +</section> +<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> @@ -685,8 +685,8 @@ 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"> +</section> +<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> @@ -706,11 +706,11 @@ wrapping, appending, etc.).</p> 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"> +</section> +</section> +<span id="document-filesystem"></span><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"> +<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> @@ -778,8 +778,8 @@ exceptions are:</p> <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"> +</section> +<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> @@ -803,8 +803,8 @@ 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"> +</section> +<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> @@ -830,8 +830,8 @@ 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"> +</section> +<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> @@ -856,8 +856,8 @@ 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"> +</section> +<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> @@ -895,8 +895,8 @@ 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"> +</section> +<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> @@ -925,11 +925,11 @@ when symlinks are supposed to always reference the running host system.</p> <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"> +</section> +</section> +<span id="document-installed-files"></span><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"> +<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> @@ -963,8 +963,8 @@ 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"> +</section> +<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> @@ -987,8 +987,8 @@ 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"> +</section> +<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> @@ -1021,11 +1021,31 @@ 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"> +</section> +<section id="pg0304"> +<span id="virtuals"></span><span id="index-3"></span><h3>Virtuals<a class="headerlink" href="#pg0304" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0304</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 in the <code class="docutils literal notranslate"><span class="pre">virtual</span></code> category must not install any files.</p> +<p><em>Rationale</em>: The <code class="docutils literal notranslate"><span class="pre">virtual</span></code> category is reserved for packages with +an empty installation image. Package managers rely on this for some +optimizations. Also QA tools make certain assumptions about virtuals, +e.g., that they must not assign the <code class="docutils literal notranslate"><span class="pre">LICENSE</span></code> variable (which would +be impossible if they installed any files).</p> +</section> +</section> +<span id="document-keywords"></span><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"> +<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> @@ -1046,8 +1066,8 @@ retested. This rule can be exempted if the package is known not to work 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"> +</section> +<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> @@ -1076,8 +1096,8 @@ 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"> +</section> +<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> @@ -1100,13 +1120,13 @@ 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"> +</section> +</section> +<span id="document-languages"></span><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"> +<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 class="target" id="index-1"></span><span class="target" id="index-2"></span><span class="target" id="index-3"></span><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> @@ -1138,8 +1158,8 @@ 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"> +</section> +<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> @@ -1172,12 +1192,12 @@ exponentially.</p> 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"> +</section> +</section> +</section> +<span id="document-maintainer"></span><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"> +<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> @@ -1205,8 +1225,8 @@ 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"> +</section> +<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> @@ -1227,8 +1247,8 @@ 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 class="target" id="index-2"></span></section> +<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> @@ -1258,11 +1278,11 @@ 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"> +</section> +</section> +<span id="document-other-metadata"></span><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 class="target" id="index-0"></span><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> @@ -1299,8 +1319,8 @@ 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"> +</section> +<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> @@ -1330,8 +1350,8 @@ 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"> +</section> +<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> @@ -1364,8 +1384,8 @@ restriction since they handle missing test prerequisites gracefully 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"> +</section> +<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> @@ -1413,11 +1433,11 @@ on the user’s system and do not affect the runtime use of packages.</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"> +</section> +</section> +<span id="document-use-flags"></span><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"> +<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> @@ -1447,8 +1467,8 @@ with the QA team before introduction.</p> of the QA policy on gtk/gtk2/gtk3 flags. The latter policy has been removed since.</p> </div> -</div> -<div class="section" id="pg0802"> +</section> +<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> @@ -1476,8 +1496,8 @@ 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"> +</section> +<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> @@ -1509,11 +1529,11 @@ unnecessary mismatches between global flags and local flags.</p> 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"> +</section> +</section> +<span id="document-user-group"></span><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 class="target" id="index-0"></span><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> @@ -1562,17 +1582,17 @@ and using it.</p> 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> +</section> +</section> </div> -</div> -</div> -</div> -<div class="section" id="indices-and-tables"> +</section> +<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> +</section> @@ -1590,7 +1610,7 @@ been reserved for true system users and groups.</p> <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> + <p class="hidden" role="heading"><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> @@ -1666,6 +1686,7 @@ been reserved for true system users and groups.</p> <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> +<li class="toctree-l2"><a class="reference internal" href="#pg0304">Virtuals</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="#document-keywords">Keywording and stabilization</a><ul class='nav'> @@ -1723,7 +1744,7 @@ been reserved for true system users and groups.</p> <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 3.3.0</a> & <a href="https://github.com/mmagorsc/tyrian_sphinx_theme">Tyrian Theme 0.0.7</a></span> + <span class="kk-group-header">Powered by</span><br><span><a href="http://sphinx-doc.org/">Sphinx 4.1.2</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> @@ -1763,7 +1784,7 @@ been reserved for true system users and groups.</p> <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> + <p class="caption" role="heading"><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> @@ -1839,6 +1860,7 @@ been reserved for true system users and groups.</p> <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> +<li class="toctree-l2"><a class="reference internal" href="index.html#pg0304">Virtuals</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="index.html#document-keywords">Keywording and stabilization</a><ul> |