diff options
Diffstat (limited to 'use-flags.html')
| -rw-r--r-- | use-flags.html | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/use-flags.html b/use-flags.html new file mode 100644 index 0000000..7480e5b --- /dev/null +++ b/use-flags.html @@ -0,0 +1,209 @@ + +<!DOCTYPE html> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta charset="utf-8" /> + <title>USE flags — 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="Users and groups" href="user-group.html" /> + <link rel="prev" title="Other metadata variables" href="other-metadata.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="use-flags"> +<h1>USE flags<a class="headerlink" href="#use-flags" title="Permalink to this headline">¶</a></h1> +<div class="section" id="versioned-use-flags"> +<span id="index-0"></span><h2>Versioned USE flags<a class="headerlink" href="#versioned-use-flags" 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=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-odd">Reported</dt> +<dd class="field-odd"><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="use-gui-flag"> +<span id="index-1"></span><h2>USE=gui flag<a class="headerlink" href="#use-gui-flag" 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://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722">https://archives.gentoo.org/gentoo-dev/message/cf3f5a59ac918335766632bd02438722</a></p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><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="underscores-in-use-flag-names"> +<span id="index-2"></span><h2>Underscores in USE flag names<a class="headerlink" href="#underscores-in-use-flag-names" 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/20191013-summary.txt">https://projects.gentoo.org/council/meeting-logs/20191013-summary.txt</a></p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><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> + + + </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"><a class="reference internal" href="dependencies.html">Dependencies</a></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 current"><a class="current reference internal" href="#">USE flags</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#versioned-use-flags">Versioned USE flags</a></li> +<li class="toctree-l2"><a class="reference internal" href="#use-gui-flag">USE=gui flag</a></li> +<li class="toctree-l2"><a class="reference internal" href="#underscores-in-use-flag-names">Underscores in USE flag names</a></li> +</ul> +</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-metadata.html" title="previous chapter">Other metadata variables</a></li> + <li>Next: <a href="user-group.html" title="next chapter">Users and groups</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/use-flags.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file |