diff options
Diffstat (limited to 'filesystem.html')
-rw-r--r-- | filesystem.html | 298 |
1 files changed, 298 insertions, 0 deletions
diff --git a/filesystem.html b/filesystem.html new file mode 100644 index 0000000..f5e33f8 --- /dev/null +++ b/filesystem.html @@ -0,0 +1,298 @@ + +<!DOCTYPE html> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta charset="utf-8" /> + <title>File system layout — 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="Installed files" href="installed-files.html" /> + <link rel="prev" title="Ebuild file format" href="ebuild-format.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="file-system-layout"> +<h1>File system layout<a class="headerlink" href="#file-system-layout" title="Permalink to this headline">¶</a></h1> +<div class="section" id="installation-paths"> +<span id="index-0"></span><h2>Installation paths<a class="headerlink" href="#installation-paths" 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://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths">https://gitweb.gentoo.org/repo/gentoo.git/tree/metadata/install-qa-check.d/08gentoo-paths</a></p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>via install-qa-check.d</p> +</dd> +</dl> +<p>Gentoo packages may only install into one of the following top-level +directories:</p> +<table class="hlist"><tr><td><ul class="simple"> +<li><p>/bin</p></li> +<li><p>/boot</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/dev</p></li> +<li><p>/etc</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/lib*</p></li> +<li><p>/opt</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/sbin</p></li> +<li><p>/srv</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr</p></li> +<li><p>/var</p></li> +</ul> +</td></tr></table> +<p>Furthermore, only the following subdirectories of /usr are permitted:</p> +<table class="hlist"><tr><td><ul class="simple"> +<li><p>/usr/bin</p></li> +<li><p>/usr/include</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr/lib*</p></li> +<li><p>/usr/libexec</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr/sbin</p></li> +<li><p>/usr/share</p></li> +</ul> +</td><td><ul class="simple"> +<li><p>/usr/src</p></li> +<li><p>/usr/<triplet></p></li> +</ul> +</td></tr></table> +<p>Furthermore, within /usr/share/doc hierarchy only a subdirectory named +after full package name and version with revision (PF) is permitted.</p> +<p>In the aforementioned lists, ‘lib*’ indicates lib and its appropriate +suffixed variants for the architecture in question. ‘<triplet>’ +indicates either CHOST or CTARGET value, as used by toolchain packages.</p> +<p>Additional exceptions can be granted by the QA team. Currently those +exceptions are:</p> +<ul class="simple"> +<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="support-for-separate-usr"> +<span id="index-1"></span><h2>Support for separate /usr<a class="headerlink" href="#support-for-separate-usr" 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://projects.gentoo.org/council/meeting-logs/20130813-summary.txt">https://projects.gentoo.org/council/meeting-logs/20130813-summary.txt</a> +<a class="reference external" href="https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt">https://projects.gentoo.org/council/meeting-logs/20130924-summary.txt</a></p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>no</p> +</dd> +</dl> +<p>Developers are not required to support using separate /usr filesystem +without an initramfs.</p> +<p><em>Rationale</em>: upstream software (as of 2013) is already making support +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="strict-multilib-layout"> +<span id="index-2"></span><h2>Strict multilib layout<a class="headerlink" href="#strict-multilib-layout" 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://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict">https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80multilib-strict</a></p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>via install-qa-check.d, fatal</p> +</dd> +</dl> +<p>Libraries must be installed into an appropriate /lib* or /usr/lib* +directory corresponding to their ABI. For example, 64-bit libraries +on amd64 must be installed into lib64 and not lib.</p> +<p>Libraries installed as a part of larger software package can be +installed along with it into a subdirectory of lib.</p> +<p><em>Rationale</em>: historically, Gentoo has been symlinking /lib to /lib64 +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="static-libraries-and-libtool-files"> +<span id="index-3"></span><h2>Static libraries and libtool files<a class="headerlink" href="#static-libraries-and-libtool-files" 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://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries">https://gitweb.gentoo.org/proj/portage.git/tree/bin/install-qa-check.d/80libraries</a></p> +</dd> +<dt class="field-odd">Reported</dt> +<dd class="field-odd"><p>via install-qa-check.d, fatal</p> +</dd> +</dl> +<p>Static libraries and libtool files (.la) must be installed into /usr +hierarchy and never to root filesystem (/lib*). If an additional shared +version of the library is installed to /lib*, a .so linker script must +be installed into /usr/lib* in order to ensure correct linking.</p> +<p><em>Rationale</em>: historically, the purpose of root filesystem was to hold +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="game-install-locations-and-ownership"> +<span id="index-4"></span><h2>Game install locations and ownership<a class="headerlink" href="#game-install-locations-and-ownership" title="Permalink to this headline">¶</a></h2> +<dl class="field-list simple"> +<dt class="field-odd">Source</dt> +<dd class="field-odd"><p>Council, clarified by QA</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/20151213-summary.txt">https://projects.gentoo.org/council/meeting-logs/20151213-summary.txt</a> +<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>via install-qa-check.d</p> +</dd> +</dl> +<p>The historical game install locations (/usr/games and /etc/games) must +not be used anymore. Instead, games should follow normal guidelines +for install locations. As an exception, /usr/share/games can be used +if this location is used upstream, and /var/games can be used for shared +game files (e.g. high scores, game state files).</p> +<p>The historical games group must no longer be used. Games must work +for users that are not in this group. The aforementioned install +locations must therefore be owned by root and be world-readable.</p> +<p>If games need privileged access to shared files, the group gamestat +can be used for this purpose. The game executables should be owned +by that group and made setgid. The shared files must be installed +into /var/games hierarchy, and writable to gamestat group.</p> +<p><em>Rationale</em>: there is no technical reason to isolate games from other +applications on the system, or to restrict access to them. The boundary +between game and non-game packages is very blurry on modern systems, +especially due to web browsers.</p> +<p>The historical use of games group on Gentoo to control access is +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> + + + </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 current"><a class="current reference internal" href="#">File system layout</a><ul> +<li class="toctree-l2"><a class="reference internal" href="#installation-paths">Installation paths</a></li> +<li class="toctree-l2"><a class="reference internal" href="#support-for-separate-usr">Support for separate /usr</a></li> +<li class="toctree-l2"><a class="reference internal" href="#strict-multilib-layout">Strict multilib layout</a></li> +<li class="toctree-l2"><a class="reference internal" href="#static-libraries-and-libtool-files">Static libraries and libtool files</a></li> +<li class="toctree-l2"><a class="reference internal" href="#game-install-locations-and-ownership">Game install locations and ownership</a></li> +</ul> +</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="ebuild-format.html" title="previous chapter">Ebuild file format</a></li> + <li>Next: <a href="installed-files.html" title="next chapter">Installed files</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/filesystem.rst.txt" + rel="nofollow">Page source</a> + </div> + + + + + </body> +</html>
\ No newline at end of file |