diff options
Diffstat (limited to 'ebuild-format.html')
| -rw-r--r-- | ebuild-format.html | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/ebuild-format.html b/ebuild-format.html new file mode 100644 index 0000000..8ecd823 --- /dev/null +++ b/ebuild-format.html @@ -0,0 +1,213 @@ + +<!DOCTYPE html> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta charset="utf-8" /> + <title>Ebuild file format — 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="File system layout" href="filesystem.html" /> + <link rel="prev" title="Dependencies" href="dependencies.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="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> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>QA</p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><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="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> +<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://bugs.gentoo.org/612630">https://bugs.gentoo.org/612630</a></p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><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="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> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>QA</p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><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="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> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>QA</p> +</dd> +<dt class="field-even">Reported</dt> +<dd class="field-even"><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> + + + </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 current"><a class="current reference internal" href="#">Ebuild file format</a><ul> +<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> +</ul> +</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="dependencies.html" title="previous chapter">Dependencies</a></li> + <li>Next: <a href="filesystem.html" title="next chapter">File system layout</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/ebuild-format.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file |