diff options
Diffstat (limited to 'ebuild-format.html')
| -rw-r--r-- | ebuild-format.html | 123 |
1 files changed, 87 insertions, 36 deletions
diff --git a/ebuild-format.html b/ebuild-format.html index 3a89fb2..74402f5 100644 --- a/ebuild-format.html +++ b/ebuild-format.html @@ -15,10 +15,10 @@ <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 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> + <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" /> <link rel="next" title="File system layout" href="filesystem.html" /> @@ -76,8 +76,25 @@ <li class=""><a href="_sources/ebuild-format.rst.txt">Source</a></li> <li> <a href="search.html">Search</a></li> + + + <li> + + <a href="genindex.html">General Index</a> + + </li> + <li> - <a href="genindex.html">Index</a></li> + + <a href="std-policy-index.html">Policy Index</a> + + </li> + + + + + + @@ -115,14 +132,17 @@ <div class="section" id="ebuild-file-format"> <h1>Ebuild file format<a class="headerlink" href="#ebuild-file-format" title="Permalink to this headline">¶</a></h1> -<div class="section" id="coding-style"> -<span id="index-0"></span><h2>Coding style<a class="headerlink" href="#coding-style" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0101"> +<span id="coding-style"></span><span id="index-0"></span><h2>Coding style<a class="headerlink" href="#pg0101" 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> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0101</p> </dd> -<dt class="field-even">Reported</dt> -<dd class="field-even"><p>partially via repoman and pkgcheck</p> +<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, @@ -139,17 +159,20 @@ or <code class="docutils literal notranslate"><span class="pre">test</span></cod Consistency avoids unnecessary changes when other developers edit the ebuild.</p> </div> -<div class="section" id="code-must-be-contained-within-ebuild-and-eclasses"> -<span id="index-1"></span><h2>Code must be contained within ebuild and eclasses<a class="headerlink" href="#code-must-be-contained-within-ebuild-and-eclasses" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0102"> +<span id="code-must-be-contained-within-ebuild-and-eclasses"></span><span id="index-1"></span><h2>Code must be contained within ebuild and eclasses<a class="headerlink" href="#pg0102" 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> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0102</p> </dd> -<dt class="field-even">Reference</dt> -<dd class="field-even"><p><a class="reference external" href="https://bugs.gentoo.org/612630">https://bugs.gentoo.org/612630</a></p> +<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> +<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 @@ -163,14 +186,17 @@ 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="homepage-must-not-contain-variables"> -<span id="index-2"></span><h2>HOMEPAGE must not contain variables<a class="headerlink" href="#homepage-must-not-contain-variables" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0103"> +<span id="homepage-must-not-contain-variables"></span><span id="index-2"></span><h2>HOMEPAGE must not contain variables<a class="headerlink" href="#pg0103" 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> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0103</p> </dd> -<dt class="field-even">Reported</dt> -<dd class="field-even"><p>by pkgcheck, highlighted as error by gentoo-syntax</p> +<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, @@ -182,14 +208,17 @@ 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="src-uri-must-not-refer-to-homepage"> -<span id="index-3"></span><h2>SRC_URI must not refer to HOMEPAGE<a class="headerlink" href="#src-uri-must-not-refer-to-homepage" title="Permalink to this headline">¶</a></h2> +<div class="section" id="pg0104"> +<span id="src-uri-must-not-refer-to-homepage"></span><span id="index-3"></span><h2>SRC_URI must not refer to HOMEPAGE<a class="headerlink" href="#pg0104" 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> +<dt class="field-odd">PG</dt> +<dd class="field-odd"><p>0104</p> </dd> -<dt class="field-even">Reported</dt> -<dd class="field-even"><p>by pkgcheck</p> +<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>. @@ -202,6 +231,27 @@ 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><h2>KEYWORDS must be defined on a single line<a class="headerlink" href="#pg0105" title="Permalink to this headline">¶</a></h2> +<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> @@ -252,10 +302,11 @@ index.</p> <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 current"><a class="current reference internal" href="#">Ebuild file format</a><ul class='nav'> -<li class="toctree-l2"><a class="reference internal" href="#coding-style">Coding style</a></li> -<li class="toctree-l2"><a class="reference internal" href="#code-must-be-contained-within-ebuild-and-eclasses">Code must be contained within ebuild and eclasses</a></li> -<li class="toctree-l2"><a class="reference internal" href="#homepage-must-not-contain-variables">HOMEPAGE must not contain variables</a></li> -<li class="toctree-l2"><a class="reference internal" href="#src-uri-must-not-refer-to-homepage">SRC_URI must not refer to HOMEPAGE</a></li> +<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="filesystem.html">File system layout</a></li> @@ -284,7 +335,7 @@ index.</p> <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.3.1</a> & <a href="https://github.com/mmagorsc/tyrian_sphinx_theme">Tyrian Theme 0.0.2</a></span> + <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> |