diff options
Diffstat (limited to 'dependencies.html')
| -rw-r--r-- | dependencies.html | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/dependencies.html b/dependencies.html new file mode 100644 index 0000000..40201d3 --- /dev/null +++ b/dependencies.html @@ -0,0 +1,264 @@ + +<!DOCTYPE html> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta charset="utf-8" /> + <title>Dependencies — Gentoo Policy Guide documentation</title> + <link rel="stylesheet" href="_static/alabaster.css" type="text/css" /> + <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> + <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> + <script type="text/javascript" src="_static/jquery.js"></script> + <script type="text/javascript" src="_static/underscore.js"></script> + <script type="text/javascript" src="_static/doctools.js"></script> + <script type="text/javascript" src="_static/language_data.js"></script> + <link rel="index" title="Index" href="genindex.html" /> + <link rel="search" title="Search" href="search.html" /> + <link rel="next" title="Ebuild file format" href="ebuild-format.html" /> + <link rel="prev" title="Other policy documents" href="other-docs.html" /> + + <link rel="stylesheet" href="_static/custom.css" type="text/css" /> + + + <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> + + </head><body> + + + <div class="document"> + <div class="documentwrapper"> + <div class="bodywrapper"> + + + <div class="body" role="main"> + + <div class="section" id="dependencies"> +<h1>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h1> +<span class="target" id="index-0"></span><div class="section" id="optional-runtime-dependencies"> +<span id="index-1"></span><h2>Optional runtime dependencies<a class="headerlink" href="#optional-runtime-dependencies" title="Permalink to this headline">¶</a></h2> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>QA</p> +</dd> +<dt class="field-even">Reference</dt> +<dd class="field-even"><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-odd">Reported</dt> +<dd class="field-odd"><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. The two possible options include +using <code class="docutils literal notranslate"><span class="pre">elog</span></code> messages and <code class="docutils literal notranslate"><span class="pre">readme.gentoo-r1</span></code> eclass.</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="slot-and-subslot-dependencies"> +<span id="index-2"></span><h2>Slot and subslot dependencies<a class="headerlink" href="#slot-and-subslot-dependencies" title="Permalink to this headline">¶</a></h2> +<div class="section" id="on-sub-slotted-packages"> +<h3>on (sub-)slotted packages<a class="headerlink" href="#on-sub-slotted-packages" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>QA</p> +</dd> +<dt class="field-even">Reference</dt> +<dd class="field-even"><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-odd">Reported</dt> +<dd class="field-odd"><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="special-case-qt-packages"> +<span id="index-3"></span><h3>special case: Qt packages<a class="headerlink" href="#special-case-qt-packages" title="Permalink to this headline">¶</a></h3> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>Qt project</p> +</dd> +<dt class="field-even">Reference</dt> +<dd class="field-even"><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-odd">Reported</dt> +<dd class="field-odd"><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"> +<h3>proactive use of slot operators<a class="headerlink" href="#proactive-use-of-slot-operators" title="Permalink to this headline">¶</a></h3> +<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="revision-bumps-on-runtime-dependency-changes"> +<span id="index-4"></span><h2>Revision bumps on runtime dependency changes<a class="headerlink" href="#revision-bumps-on-runtime-dependency-changes" title="Permalink to this headline">¶</a></h2> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>Council</p> +</dd> +<dt class="field-even">Reference</dt> +<dd class="field-even"><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-odd">Reported</dt> +<dd class="field-odd"><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> + + + </div> + + </div> + </div> + <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> + <div class="sphinxsidebarwrapper"> +<h1 class="logo"><a href="index.html">Gentoo Policy Guide</a></h1> + + + + + + + + +<h3>Navigation</h3> +<p class="caption"><span class="caption-text">Contents:</span></p> +<ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="preface.html">Preface</a></li> +<li class="toctree-l1"><a class="reference internal" href="motivation.html">Motivation and history</a></li> +<li class="toctree-l1"><a class="reference internal" href="basics.html">Basic information</a></li> +<li class="toctree-l1"><a class="reference internal" href="other-docs.html">Other policy documents</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Dependencies</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#optional-runtime-dependencies">Optional runtime dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#slot-and-subslot-dependencies">Slot and subslot dependencies</a></li> +<li class="toctree-l2"><a class="reference internal" href="#revision-bumps-on-runtime-dependency-changes">Revision bumps on runtime dependency changes</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="ebuild-format.html">Ebuild file format</a></li> +<li class="toctree-l1"><a class="reference internal" href="filesystem.html">File system layout</a></li> +<li class="toctree-l1"><a class="reference internal" href="installed-files.html">Installed files</a></li> +<li class="toctree-l1"><a class="reference internal" href="keywords.html">Keywording and stabilization</a></li> +<li class="toctree-l1"><a class="reference internal" href="languages.html">Language-specific policies</a></li> +<li class="toctree-l1"><a class="reference internal" href="other-metadata.html">Other metadata variables</a></li> +<li class="toctree-l1"><a class="reference internal" href="use-flags.html">USE flags</a></li> +<li class="toctree-l1"><a class="reference internal" href="user-group.html">Users and groups</a></li> +</ul> + +<div class="relations"> +<h3>Related Topics</h3> +<ul> + <li><a href="index.html">Documentation overview</a><ul> + <li>Previous: <a href="other-docs.html" title="previous chapter">Other policy documents</a></li> + <li>Next: <a href="ebuild-format.html" title="next chapter">Ebuild file format</a></li> + </ul></li> +</ul> +</div> +<div id="searchbox" style="display: none" role="search"> + <h3 id="searchlabel">Quick search</h3> + <div class="searchformwrapper"> + <form class="search" action="search.html" method="get"> + <input type="text" name="q" aria-labelledby="searchlabel" /> + <input type="submit" value="Go" /> + </form> + </div> +</div> +<script type="text/javascript">$('#searchbox').show(0);</script> + + + + + + + + + </div> + </div> + <div class="clearer"></div> + </div> + <div class="footer"> + ©2020, Gentoo Authors. + + | + Powered by <a href="http://sphinx-doc.org/">Sphinx 2.3.1</a> + & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a> + + | + <a href="_sources/dependencies.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file |