en/glep/glep-0060.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
  <title>GLEP 60 -- Manifest2 filetypes</title>
  <link rel="stylesheet" href="tools/glep.css" type="text/css" /></head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
       width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
 border="0" width="150" height="35" /></a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0060.txt">GLEP Source</a></b>]
</td></tr></table>
<table class="rfc2822 docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">60</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Manifest2 filetypes</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.3</td>
</tr>
<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0060.txt?cvsroot=gentoo">2008/10/28 07:46:51</a></td>
</tr>
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Robin Hugh Johnson &lt;robbat2&#32;&#97;t&#32;gentoo.org&gt;</td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
</tr>
<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="glep-0002.html">text/x-rst</a></td>
</tr>
<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><a class="reference external" href="http://www.gentoo.org/proj/en/glepglep-0044.html">44</a></td>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">November 2007</td>
</tr>
<tr class="field"><th class="field-name">Updated:</th><td class="field-body">June 2008, July 2008, October 2008</td>
</tr>
<tr class="field"><th class="field-name">Updates:</th><td class="field-body">44</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#abstract" id="id4">Abstract</a></li>
<li><a class="reference internal" href="#motivation" id="id5">Motivation</a></li>
<li><a class="reference internal" href="#specification" id="id6">Specification</a><ul>
<li><a class="reference internal" href="#general" id="id7">General</a></li>
<li><a class="reference internal" href="#excluded-files" id="id8">Excluded files</a></li>
<li><a class="reference internal" href="#existing-filetypes" id="id9">Existing filetypes:</a><ul>
<li><a class="reference internal" href="#aux" id="id10">AUX</a></li>
<li><a class="reference internal" href="#ebuild" id="id11">EBUILD</a></li>
<li><a class="reference internal" href="#dist" id="id12">DIST</a></li>
<li><a class="reference internal" href="#misc" id="id13">MISC</a></li>
</ul>
</li>
<li><a class="reference internal" href="#new-filetypes" id="id14">New filetypes:</a><ul>
<li><a class="reference internal" href="#info-new-abstract" id="id15">_INFO (new, abstract)</a></li>
<li><a class="reference internal" href="#crit-new-abstract" id="id16">_CRIT (new, abstract)</a></li>
<li><a class="reference internal" href="#id1" id="id17">EBUILD</a></li>
<li><a class="reference internal" href="#id2" id="id18">DIST</a></li>
<li><a class="reference internal" href="#id3" id="id19">MISC</a></li>
<li><a class="reference internal" href="#manifest-new" id="id20">MANIFEST (new)</a></li>
<li><a class="reference internal" href="#eclass-new" id="id21">ECLASS (new)</a></li>
<li><a class="reference internal" href="#data-new" id="id22">DATA (new)</a></li>
<li><a class="reference internal" href="#exec-new" id="id23">EXEC (new)</a></li>
<li><a class="reference internal" href="#other-new" id="id24">OTHER (new)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#on-bloat" id="id25">On Bloat</a></li>
<li><a class="reference internal" href="#chosing-a-filetype" id="id26">Chosing a filetype</a></li>
</ul>
</li>
<li><a class="reference internal" href="#backwards-compatibility" id="id27">Backwards Compatibility</a></li>
<li><a class="reference internal" href="#thanks-to" id="id28">Thanks to</a></li>
<li><a class="reference internal" href="#references" id="id29">References</a></li>
<li><a class="reference internal" href="#copyright" id="id30">Copyright</a></li>
</ul>
</div>
<div class="section" id="abstract">
<h1><a class="toc-backref" href="#id4">Abstract</a></h1>
<p>Clarification of the Manifest2 [#GLEP44] specification, including new types to
help in the tree-signing specification.</p>
</div>
<div class="section" id="motivation">
<h1><a class="toc-backref" href="#id5">Motivation</a></h1>
<p>[#GLEP44] was not entirely clear on the usage of filetype specifiers.
This document serves to provide some of the internal logic used by
Portage at the point of writing, as well as adding new types to cover
the rest of the tree, for the purposes of tree-signing coverage.</p>
</div>
<div class="section" id="specification">
<h1><a class="toc-backref" href="#id6">Specification</a></h1>
<div class="section" id="general">
<h2><a class="toc-backref" href="#id7">General</a></h2>
<p>For any given directory with a Manifest file, every file located in that
directory, or a sub-directory must be listed in that Manifest file,
unless stated otherwise in the following sections. The Manifest file
must not contain an entry for itself.</p>
</div>
<div class="section" id="excluded-files">
<h2><a class="toc-backref" href="#id8">Excluded files</a></h2>
<p>When generating or validating a Manifest, or commiting to a version
control system, the package manager should endeavour to ignore files
created by a version control system, backup files from text editors. A
non-exhaustive list is suggested here: <tt class="docutils literal"><span class="pre">CVS/</span></tt>, <tt class="docutils literal"><span class="pre">.svn/</span></tt>, <tt class="docutils literal"><span class="pre">.bzr/</span></tt>,
<tt class="docutils literal"><span class="pre">.git/</span></tt>, <tt class="docutils literal"><span class="pre">.hg/</span></tt>, <tt class="docutils literal"><span class="pre">.#*</span></tt>, <tt class="docutils literal"><span class="pre">*.rej</span></tt>, <tt class="docutils literal"><span class="pre">*.orig</span></tt>, <tt class="docutils literal"><span class="pre">*.bak</span></tt>, <tt class="docutils literal"><span class="pre">*~</span></tt>.</p>
<p>Additionally, for a transitional Manifest1-&gt;Manifest2 system, old-style
digest files located in a 'files/' directory, may be excluded from
Manifest2 generation, or included with a type of MISC.</p>
<p>Under strict security conditions, the exclusion list may be ignored
during validation if the existence of a file would be considered a
security risk.</p>
</div>
<div class="section" id="existing-filetypes">
<h2><a class="toc-backref" href="#id9">Existing filetypes:</a></h2>
<div class="section" id="aux">
<h3><a class="toc-backref" href="#id10">AUX</a></h3>
<ul class="simple">
<li>The AUX type is used for all items under the 'files' subdirectory.</li>
<li>They should be verified relative to $FILESDIR.</li>
<li>The string 'files/' is left out of the Manifest line.</li>
<li>The absence of a file mentioned by AUX must be treated as an error.</li>
<li>The AUX type is intended to denote potentially executable content
(either directly or indirectly), that must be treated an error if
modified or absent.</li>
</ul>
</div>
<div class="section" id="ebuild">
<h3><a class="toc-backref" href="#id11">EBUILD</a></h3>
<ul class="simple">
<li>The EBUILD type is used solely for files ending in .ebuild, or other
suffixes as defined by the EAPI.</li>
<li>The files are located in the same directory as the Manifest file.</li>
<li>The modification or absence of a file mentioned by EBUILD must be
treated as an error.</li>
</ul>
</div>
<div class="section" id="dist">
<h3><a class="toc-backref" href="#id12">DIST</a></h3>
<ul class="simple">
<li>The DIST type is used for distfiles</li>
<li>They may be found directly via the $DISTDIR setting of the package
manager.</li>
<li>During simple verification of a Manifest, a missing DIST file should
not be consider as a validation error (it is however a failure to
fetch or unpack).</li>
</ul>
</div>
<div class="section" id="misc">
<h3><a class="toc-backref" href="#id13">MISC</a></h3>
<ul class="simple">
<li>The MISC type covers all remaining files in a directory.</li>
<li>MISC is intended to mark all content that was not used in
some way that directly affected execution of the package manager.</li>
<li>This includes metadata.xml and ChangeLog entries, and any other purely
informational content.</li>
<li>MISC entries where the file is missing may optionally be ignored as by
non-strict package managers.</li>
<li>It should be possible to install a package while all MISC entries have
been deleted from the tree.</li>
</ul>
</div>
</div>
<div class="section" id="new-filetypes">
<h2><a class="toc-backref" href="#id14">New filetypes:</a></h2>
<div class="section" id="info-new-abstract">
<h3><a class="toc-backref" href="#id15">_INFO (new, abstract)</a></h3>
<ul class="simple">
<li>This is the functionality of the old AUX, but does not include the
implicit 'files/' prefix in the path, and is verified relative to the
working directory instead of $FILESDIR.</li>
<li>The modification or absence of a file listed as a _INFO-derived type
is not an error unless the package manager is attempting to be strict.</li>
</ul>
</div>
<div class="section" id="crit-new-abstract">
<h3><a class="toc-backref" href="#id16">_CRIT (new, abstract)</a></h3>
<ul class="simple">
<li>_CRIT is based off the _INFO type.</li>
<li>The modification or absence of a file listed as a _CRIT-derived type
must be treated as an error.</li>
</ul>
</div>
<div class="section" id="id1">
<h3><a class="toc-backref" href="#id17">EBUILD</a></h3>
<ul class="simple">
<li>Now derived from _CRIT.</li>
<li>Otherwise unchanged.</li>
</ul>
</div>
<div class="section" id="id2">
<h3><a class="toc-backref" href="#id18">DIST</a></h3>
<ul class="simple">
<li>Now derived from _CRIT.</li>
<li>Otherwise unchanged.</li>
</ul>
</div>
<div class="section" id="id3">
<h3><a class="toc-backref" href="#id19">MISC</a></h3>
<ul class="simple">
<li>Now derived from _INFO.</li>
<li>Otherwise unchanged.</li>
</ul>
</div>
<div class="section" id="manifest-new">
<h3><a class="toc-backref" href="#id20">MANIFEST (new)</a></h3>
<ul class="simple">
<li>The MANIFEST type is explicitly to cover all nested Manifest files.</li>
<li>During validation, this serves as an indicator that the package
manager may need to check subtree Manifest file.</li>
<li>A missing MANIFEST file may be treated as a minor (eg excluding an
entire category) or critical validation failure.</li>
<li>The failure should be considered as critical only if files that would
be directly covered by this Manifest are missing. Deletion of a
category-level Manifest while preserving the packages is forbidden.
Deletion of an entire category is not.</li>
</ul>
</div>
<div class="section" id="eclass-new">
<h3><a class="toc-backref" href="#id21">ECLASS (new)</a></h3>
<ul class="simple">
<li>uses _CRIT.</li>
<li>This type shall be used for all eclasses only.</li>
<li>TODO: What about patches etc under eclasses/? Probably EXEC?</li>
</ul>
</div>
<div class="section" id="data-new">
<h3><a class="toc-backref" href="#id22">DATA (new)</a></h3>
<ul class="simple">
<li>uses _CRIT.</li>
<li>The DATA type shall be used for all files that directly affect the
package manager, such as metadata/cache/* and profiles/.</li>
</ul>
</div>
<div class="section" id="exec-new">
<h3><a class="toc-backref" href="#id23">EXEC (new)</a></h3>
<ul class="simple">
<li>uses _CRIT.</li>
<li>If the file gets sourced, executed, or causes a change (patches) in
how something is sourced or execututed, it belongs in the EXEC
filetype.</li>
<li>This filetype should be used for the scripts directories of a
repository for important files.</li>
</ul>
</div>
<div class="section" id="other-new">
<h3><a class="toc-backref" href="#id24">OTHER (new)</a></h3>
<ul class="simple">
<li>uses _CRIT.</li>
<li>All other files that are not covered by another type should be
considered as 'OTHER'.</li>
</ul>
</div>
</div>
<div class="section" id="on-bloat">
<h2><a class="toc-backref" href="#id25">On Bloat</a></h2>
<p>If repeated use of a common path prefix is considered a bloat problem, a
Manifest file should be added inside the common directory, however this
should not be done blindly, as bloat by inodes is more significant for
the majority of use cases.</p>
</div>
<div class="section" id="chosing-a-filetype">
<h2><a class="toc-backref" href="#id26">Chosing a filetype</a></h2>
<ol class="arabic">
<li><dl class="first docutils">
<dt>matches Manifest</dt>
<dd><p class="first last">=&gt; MANIFEST, stop.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>matches <tt class="docutils literal"><span class="pre">*.ebuild</span></tt></dt>
<dd><p class="first last">=&gt; EBUILD, stop.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>matches <tt class="docutils literal"><span class="pre">*.eclass</span></tt></dt>
<dd><p class="first last">=&gt; ECLASS, stop.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>listed in SRC_URI</dt>
<dd><p class="first last">=&gt; DIST, stop.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>matches <tt class="docutils literal"><span class="pre">files/*</span></tt></dt>
<dd><p class="first last">=&gt; AUX, continue [see note].</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>matches any of <tt class="docutils literal"><span class="pre">*.sh</span></tt>, <tt class="docutils literal"><span class="pre">*.bashrc</span></tt>, <tt class="docutils literal"><span class="pre">*.patch</span></tt>, ...</dt>
<dd><p class="first last">=&gt; EXEC, stop.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>matches any of <tt class="docutils literal"><span class="pre">metadata/cache/*</span></tt>, <tt class="docutils literal"><span class="pre">profiles/</span></tt>, <tt class="docutils literal"><span class="pre">package.*</span></tt>, <tt class="docutils literal"><span class="pre">use.mask*</span></tt>, ...</dt>
<dd><p class="first last">=&gt; DATA, stop.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>matches any of <tt class="docutils literal"><span class="pre">ChangeLog</span></tt>, <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>, <tt class="docutils literal"><span class="pre">*.desc</span></tt>, ...</dt>
<dd><p class="first last">=&gt; MISC, stop.</p>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt>not matched by any other rule</dt>
<dd><p class="first last">=&gt; OTHER, stop.</p>
</dd>
</dl>
</li>
</ol>
<p>The logic behind 5, 6, 7 is ensuring that every item that by it's
presence or absense may be dangerous should always be treated strictly.
(Consider epatch given a directory of patches <tt class="docutils literal"><span class="pre">${FILESDIR}/${PV}/</span></tt>,
where it blindly includes them, or alternatively, the package.mask file
or a profile being altered/missing).</p>
<p>Note: The AUX entries should only be generated if we are generating a
compatible Manifest that supports older versions of Portage. They should
be generated along with the new type.</p>
</div>
</div>
<div class="section" id="backwards-compatibility">
<h1><a class="toc-backref" href="#id27">Backwards Compatibility</a></h1>
<p>For generation of existing package Manifests, the AUX entries must
continue to be present for the standard Portage deprecation cycle.
The new entries may be included already in all Manifest files, as they
will be ignored by older Portage versions. Over time, ECLASS, DATA,
EXEC, OTHER may replace the existing AUX type.</p>
<p>The adoption of this proposal does also affect [#GLEP58] as part of
this GLEP series, however this GLEP was an offset of the research in
that GLEP.</p>
</div>
<div class="section" id="thanks-to">
<h1><a class="toc-backref" href="#id28">Thanks to</a></h1>
<p>I'd like to thank the following people for input on this GLEP.
- Marius Mauch (genone) &amp; Zac Medico (zmedico): Portage Manifest2</p>
</div>
<div class="section" id="references">
<h1><a class="toc-backref" href="#id29">References</a></h1>
<table class="docutils footnote" frame="void" id="glep44" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td>Mauch, M. (2005) GLEP44 - Manifest2 format.
<a class="reference external" href="http://www.gentoo.org/proj/en/glep/glep-0044.html">http://www.gentoo.org/proj/en/glep/glep-0044.html</a></td></tr>
</tbody>
</table>
</div>
<div class="section" id="copyright">
<h1><a class="toc-backref" href="#id30">Copyright</a></h1>
<p>Copyright (c) 2007 by Robin Hugh Johnson. This material may be
distributed only subject to the terms and conditions set forth in the
Open Publication License, v1.0.</p>
<p>vim: tw=72 ts=2 expandtab:</p>
</div>

</div>
<div class="footer">
<hr class="footer" />
<a class="reference external" href="glep-0060.txt">View document source</a>.
Generated on: 2008-10-28 07:47 UTC.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.

</div>
</body>
</html>
1	cardoe	1.1	<?xml version="1.0" encoding="utf-8" ?>
2			<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3			<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
5			<head>
6			<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7			<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
8			<title>GLEP 60 -- Manifest2 filetypes</title>
9			<link rel="stylesheet" href="tools/glep.css" type="text/css" /></head>
10			<body bgcolor="white">
11			<table class="navigation" cellpadding="0" cellspacing="0"
12			width="100%" border="0">
13			<tr><td class="navicon" width="150" height="35">
14			<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
15			<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
16			border="0" width="150" height="35" /></a></td>
17			<td class="textlinks" align="left">
18			[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
19			[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
20			[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0060.txt">GLEP Source</a></b>]
21			</td></tr></table>
22			<table class="rfc2822 docutils field-list" frame="void" rules="none">
23			<col class="field-name" />
24			<col class="field-body" />
25			<tbody valign="top">
26			<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">60</td>
27			</tr>
28			<tr class="field"><th class="field-name">Title:</th><td class="field-body">Manifest2 filetypes</td>
29			</tr>
30	robbat2	1.3	<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.3</td>
31	cardoe	1.1	</tr>
32	robbat2	1.3	<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/glep/glep-0060.txt?cvsroot=gentoo">2008/10/28 07:46:51</a></td>
33	cardoe	1.1	</tr>
34			<tr class="field"><th class="field-name">Author:</th><td class="field-body">Robin Hugh Johnson <robbat2 at gentoo.org></td>
35			</tr>
36			<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
37			</tr>
38			<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
39			</tr>
40			<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="glep-0002.html">text/x-rst</a></td>
41			</tr>
42			<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><a class="reference external" href="http://www.gentoo.org/proj/en/glepglep-0044.html">44</a></td>
43			</tr>
44			<tr class="field"><th class="field-name">Created:</th><td class="field-body">November 2007</td>
45			</tr>
46	robbat2	1.3	<tr class="field"><th class="field-name">Updated:</th><td class="field-body">June 2008, July 2008, October 2008</td>
47	cardoe	1.1	</tr>
48			<tr class="field"><th class="field-name">Updates:</th><td class="field-body">44</td>
49			</tr>
50	robbat2	1.3	<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
51			</tr>
52	cardoe	1.1	</tbody>
53			</table>
54			<hr />
55			<div class="contents topic" id="contents">
56			<p class="topic-title first">Contents</p>
57			<ul class="simple">
58	robbat2	1.3	<li><a class="reference internal" href="#abstract" id="id4">Abstract</a></li>
59			<li><a class="reference internal" href="#motivation" id="id5">Motivation</a></li>
60			<li><a class="reference internal" href="#specification" id="id6">Specification</a><ul>
61			<li><a class="reference internal" href="#general" id="id7">General</a></li>
62			<li><a class="reference internal" href="#excluded-files" id="id8">Excluded files</a></li>
63			<li><a class="reference internal" href="#existing-filetypes" id="id9">Existing filetypes:</a><ul>
64			<li><a class="reference internal" href="#aux" id="id10">AUX</a></li>
65			<li><a class="reference internal" href="#ebuild" id="id11">EBUILD</a></li>
66			<li><a class="reference internal" href="#dist" id="id12">DIST</a></li>
67			<li><a class="reference internal" href="#misc" id="id13">MISC</a></li>
68			</ul>
69			</li>
70			<li><a class="reference internal" href="#new-filetypes" id="id14">New filetypes:</a><ul>
71			<li><a class="reference internal" href="#info-new-abstract" id="id15">_INFO (new, abstract)</a></li>
72			<li><a class="reference internal" href="#crit-new-abstract" id="id16">_CRIT (new, abstract)</a></li>
73			<li><a class="reference internal" href="#id1" id="id17">EBUILD</a></li>
74			<li><a class="reference internal" href="#id2" id="id18">DIST</a></li>
75			<li><a class="reference internal" href="#id3" id="id19">MISC</a></li>
76			<li><a class="reference internal" href="#manifest-new" id="id20">MANIFEST (new)</a></li>
77			<li><a class="reference internal" href="#eclass-new" id="id21">ECLASS (new)</a></li>
78			<li><a class="reference internal" href="#data-new" id="id22">DATA (new)</a></li>
79			<li><a class="reference internal" href="#exec-new" id="id23">EXEC (new)</a></li>
80	robbat2	1.4	<li><a class="reference internal" href="#other-new" id="id24">OTHER (new)</a></li>
81	robbat2	1.3	</ul>
82			</li>
83			<li><a class="reference internal" href="#on-bloat" id="id25">On Bloat</a></li>
84			<li><a class="reference internal" href="#chosing-a-filetype" id="id26">Chosing a filetype</a></li>
85			</ul>
86			</li>
87			<li><a class="reference internal" href="#backwards-compatibility" id="id27">Backwards Compatibility</a></li>
88			<li><a class="reference internal" href="#thanks-to" id="id28">Thanks to</a></li>
89			<li><a class="reference internal" href="#references" id="id29">References</a></li>
90			<li><a class="reference internal" href="#copyright" id="id30">Copyright</a></li>
91	cardoe	1.1	</ul>
92			</div>
93			<div class="section" id="abstract">
94	robbat2	1.3	<h1><a class="toc-backref" href="#id4">Abstract</a></h1>
95			<p>Clarification of the Manifest2 [#GLEP44] specification, including new types to
96	cardoe	1.1	help in the tree-signing specification.</p>
97			</div>
98			<div class="section" id="motivation">
99	robbat2	1.3	<h1><a class="toc-backref" href="#id5">Motivation</a></h1>
100			<p>[#GLEP44] was not entirely clear on the usage of filetype specifiers.
101	cardoe	1.1	This document serves to provide some of the internal logic used by
102			Portage at the point of writing, as well as adding new types to cover
103			the rest of the tree, for the purposes of tree-signing coverage.</p>
104			</div>
105			<div class="section" id="specification">
106	robbat2	1.3	<h1><a class="toc-backref" href="#id6">Specification</a></h1>
107	cardoe	1.1	<div class="section" id="general">
108	robbat2	1.3	<h2><a class="toc-backref" href="#id7">General</a></h2>
109	cardoe	1.1	<p>For any given directory with a Manifest file, every file located in that
110			directory, or a sub-directory must be listed in that Manifest file,
111			unless stated otherwise in the following sections. The Manifest file
112			must not contain an entry for itself.</p>
113			</div>
114			<div class="section" id="excluded-files">
115	robbat2	1.3	<h2><a class="toc-backref" href="#id8">Excluded files</a></h2>
116	cardoe	1.1	<p>When generating or validating a Manifest, or commiting to a version
117			control system, the package manager should endeavour to ignore files
118			created by a version control system, backup files from text editors. A
119	robbat2	1.3	non-exhaustive list is suggested here: <tt class="docutils literal"><span class="pre">CVS/</span></tt>, <tt class="docutils literal"><span class="pre">.svn/</span></tt>, <tt class="docutils literal"><span class="pre">.bzr/</span></tt>,
120			<tt class="docutils literal"><span class="pre">.git/</span></tt>, <tt class="docutils literal"><span class="pre">.hg/</span></tt>, <tt class="docutils literal"><span class="pre">.#</span></tt>, <tt class="docutils literal"><span class="pre">.rej</span></tt>, <tt class="docutils literal"><span class="pre">.orig</span></tt>, <tt class="docutils literal"><span class="pre">.bak</span></tt>, <tt class="docutils literal"><span class="pre">*~</span></tt>.</p>
121	cardoe	1.1	<p>Additionally, for a transitional Manifest1->Manifest2 system, old-style
122			digest files located in a 'files/' directory, may be excluded from
123			Manifest2 generation, or included with a type of MISC.</p>
124			<p>Under strict security conditions, the exclusion list may be ignored
125			during validation if the existence of a file would be considered a
126			security risk.</p>
127			</div>
128			<div class="section" id="existing-filetypes">
129	robbat2	1.3	<h2><a class="toc-backref" href="#id9">Existing filetypes:</a></h2>
130	cardoe	1.1	<div class="section" id="aux">
131	robbat2	1.3	<h3><a class="toc-backref" href="#id10">AUX</a></h3>
132	cardoe	1.1	<ul class="simple">
133			<li>The AUX type is used for all items under the 'files' subdirectory.</li>
134			<li>They should be verified relative to $FILESDIR.</li>
135			<li>The string 'files/' is left out of the Manifest line.</li>
136			<li>The absence of a file mentioned by AUX must be treated as an error.</li>
137			<li>The AUX type is intended to denote potentially executable content
138			(either directly or indirectly), that must be treated an error if
139			modified or absent.</li>
140			</ul>
141			</div>
142			<div class="section" id="ebuild">
143	robbat2	1.3	<h3><a class="toc-backref" href="#id11">EBUILD</a></h3>
144	cardoe	1.1	<ul class="simple">
145			<li>The EBUILD type is used solely for files ending in .ebuild, or other
146			suffixes as defined by the EAPI.</li>
147			<li>The files are located in the same directory as the Manifest file.</li>
148			<li>The modification or absence of a file mentioned by EBUILD must be
149			treated as an error.</li>
150			</ul>
151			</div>
152			<div class="section" id="dist">
153	robbat2	1.3	<h3><a class="toc-backref" href="#id12">DIST</a></h3>
154	cardoe	1.1	<ul class="simple">
155			<li>The DIST type is used for distfiles</li>
156			<li>They may be found directly via the $DISTDIR setting of the package
157			manager.</li>
158			<li>During simple verification of a Manifest, a missing DIST file should
159			not be consider as a validation error (it is however a failure to
160			fetch or unpack).</li>
161			</ul>
162			</div>
163			<div class="section" id="misc">
164	robbat2	1.3	<h3><a class="toc-backref" href="#id13">MISC</a></h3>
165	cardoe	1.1	<ul class="simple">
166			<li>The MISC type covers all remaining files in a directory.</li>
167			<li>MISC is intended to mark all content that was not used in
168			some way that directly affected execution of the package manager.</li>
169			<li>This includes metadata.xml and ChangeLog entries, and any other purely
170			informational content.</li>
171			<li>MISC entries where the file is missing may optionally be ignored as by
172			non-strict package managers.</li>
173			<li>It should be possible to install a package while all MISC entries have
174			been deleted from the tree.</li>
175			</ul>
176			</div>
177			</div>
178			<div class="section" id="new-filetypes">
179	robbat2	1.3	<h2><a class="toc-backref" href="#id14">New filetypes:</a></h2>
180	cardoe	1.1	<div class="section" id="info-new-abstract">
181	robbat2	1.3	<h3><a class="toc-backref" href="#id15">_INFO (new, abstract)</a></h3>
182	cardoe	1.1	<ul class="simple">
183			<li>This is the functionality of the old AUX, but does not include the
184			implicit 'files/' prefix in the path, and is verified relative to the
185			working directory instead of $FILESDIR.</li>
186			<li>The modification or absence of a file listed as a _INFO-derived type
187			is not an error unless the package manager is attempting to be strict.</li>
188			</ul>
189			</div>
190			<div class="section" id="crit-new-abstract">
191	robbat2	1.3	<h3><a class="toc-backref" href="#id16">_CRIT (new, abstract)</a></h3>
192	cardoe	1.1	<ul class="simple">
193			<li>_CRIT is based off the _INFO type.</li>
194			<li>The modification or absence of a file listed as a _CRIT-derived type
195			must be treated as an error.</li>
196			</ul>
197			</div>
198	robbat2	1.3	<div class="section" id="id1">
199			<h3><a class="toc-backref" href="#id17">EBUILD</a></h3>
200	cardoe	1.1	<ul class="simple">
201			<li>Now derived from _CRIT.</li>
202			<li>Otherwise unchanged.</li>
203			</ul>
204			</div>
205	robbat2	1.3	<div class="section" id="id2">
206			<h3><a class="toc-backref" href="#id18">DIST</a></h3>
207	cardoe	1.1	<ul class="simple">
208			<li>Now derived from _CRIT.</li>
209			<li>Otherwise unchanged.</li>
210			</ul>
211			</div>
212	robbat2	1.3	<div class="section" id="id3">
213			<h3><a class="toc-backref" href="#id19">MISC</a></h3>
214	cardoe	1.1	<ul class="simple">
215			<li>Now derived from _INFO.</li>
216			<li>Otherwise unchanged.</li>
217			</ul>
218			</div>
219			<div class="section" id="manifest-new">
220	robbat2	1.3	<h3><a class="toc-backref" href="#id20">MANIFEST (new)</a></h3>
221	cardoe	1.1	<ul class="simple">
222			<li>The MANIFEST type is explicitly to cover all nested Manifest files.</li>
223			<li>During validation, this serves as an indicator that the package
224			manager may need to check subtree Manifest file.</li>
225			<li>A missing MANIFEST file may be treated as a minor (eg excluding an
226			entire category) or critical validation failure.</li>
227			<li>The failure should be considered as critical only if files that would
228			be directly covered by this Manifest are missing. Deletion of a
229			category-level Manifest while preserving the packages is forbidden.
230			Deletion of an entire category is not.</li>
231			</ul>
232			</div>
233			<div class="section" id="eclass-new">
234	robbat2	1.3	<h3><a class="toc-backref" href="#id21">ECLASS (new)</a></h3>
235	cardoe	1.1	<ul class="simple">
236			<li>uses _CRIT.</li>
237			<li>This type shall be used for all eclasses only.</li>
238			<li>TODO: What about patches etc under eclasses/? Probably EXEC?</li>
239			</ul>
240			</div>
241			<div class="section" id="data-new">
242	robbat2	1.3	<h3><a class="toc-backref" href="#id22">DATA (new)</a></h3>
243	cardoe	1.1	<ul class="simple">
244			<li>uses _CRIT.</li>
245			<li>The DATA type shall be used for all files that directly affect the
246			package manager, such as metadata/cache/* and profiles/.</li>
247			</ul>
248			</div>
249			<div class="section" id="exec-new">
250	robbat2	1.3	<h3><a class="toc-backref" href="#id23">EXEC (new)</a></h3>
251	cardoe	1.1	<ul class="simple">
252			<li>uses _CRIT.</li>
253			<li>If the file gets sourced, executed, or causes a change (patches) in
254			how something is sourced or execututed, it belongs in the EXEC
255			filetype.</li>
256			<li>This filetype should be used for the scripts directories of a
257			repository for important files.</li>
258			</ul>
259			</div>
260	robbat2	1.4	<div class="section" id="other-new">
261			<h3><a class="toc-backref" href="#id24">OTHER (new)</a></h3>
262	cardoe	1.1	<ul class="simple">
263			<li>uses _CRIT.</li>
264			<li>All other files that are not covered by another type should be
265	robbat2	1.4	considered as 'OTHER'.</li>
266	cardoe	1.1	</ul>
267			</div>
268			</div>
269			<div class="section" id="on-bloat">
270	robbat2	1.3	<h2><a class="toc-backref" href="#id25">On Bloat</a></h2>
271	cardoe	1.1	<p>If repeated use of a common path prefix is considered a bloat problem, a
272			Manifest file should be added inside the common directory, however this
273			should not be done blindly, as bloat by inodes is more significant for
274			the majority of use cases.</p>
275			</div>
276			<div class="section" id="chosing-a-filetype">
277	robbat2	1.3	<h2><a class="toc-backref" href="#id26">Chosing a filetype</a></h2>
278	cardoe	1.1	<ol class="arabic">
279			<li><dl class="first docutils">
280			<dt>matches Manifest</dt>
281			<dd><p class="first last">=> MANIFEST, stop.</p>
282			</dd>
283			</dl>
284			</li>
285			<li><dl class="first docutils">
286	robbat2	1.3	<dt>matches <tt class="docutils literal"><span class="pre">*.ebuild</span></tt></dt>
287			<dd><p class="first last">=> EBUILD, stop.</p>
288	cardoe	1.1	</dd>
289			</dl>
290			</li>
291			<li><dl class="first docutils">
292	robbat2	1.3	<dt>matches <tt class="docutils literal"><span class="pre">*.eclass</span></tt></dt>
293			<dd><p class="first last">=> ECLASS, stop.</p>
294	cardoe	1.1	</dd>
295			</dl>
296			</li>
297			<li><dl class="first docutils">
298			<dt>listed in SRC_URI</dt>
299			<dd><p class="first last">=> DIST, stop.</p>
300			</dd>
301			</dl>
302			</li>
303			<li><dl class="first docutils">
304	robbat2	1.3	<dt>matches <tt class="docutils literal"><span class="pre">files/*</span></tt></dt>
305	cardoe	1.1	<dd><p class="first last">=> AUX, continue [see note].</p>
306			</dd>
307			</dl>
308			</li>
309			<li><dl class="first docutils">
310	robbat2	1.3	<dt>matches any of <tt class="docutils literal"><span class="pre">.sh</span></tt>, <tt class="docutils literal"><span class="pre">.bashrc</span></tt>, <tt class="docutils literal"><span class="pre">*.patch</span></tt>, ...</dt>
311	cardoe	1.1	<dd><p class="first last">=> EXEC, stop.</p>
312			</dd>
313			</dl>
314			</li>
315			<li><dl class="first docutils">
316	robbat2	1.3	<dt>matches any of <tt class="docutils literal"><span class="pre">metadata/cache/</span></tt>, <tt class="docutils literal"><span class="pre">profiles/</span></tt>, <tt class="docutils literal"><span class="pre">package.</span></tt>, <tt class="docutils literal"><span class="pre">use.mask*</span></tt>, ...</dt>
317	cardoe	1.1	<dd><p class="first last">=> DATA, stop.</p>
318			</dd>
319			</dl>
320			</li>
321			<li><dl class="first docutils">
322	robbat2	1.3	<dt>matches any of <tt class="docutils literal"><span class="pre">ChangeLog</span></tt>, <tt class="docutils literal"><span class="pre">metadata.xml</span></tt>, <tt class="docutils literal"><span class="pre">*.desc</span></tt>, ...</dt>
323	cardoe	1.1	<dd><p class="first last">=> MISC, stop.</p>
324			</dd>
325			</dl>
326			</li>
327			<li><dl class="first docutils">
328			<dt>not matched by any other rule</dt>
329	robbat2	1.4	<dd><p class="first last">=> OTHER, stop.</p>
330	cardoe	1.1	</dd>
331			</dl>
332			</li>
333			</ol>
334			<p>The logic behind 5, 6, 7 is ensuring that every item that by it's
335			presence or absense may be dangerous should always be treated strictly.
336	robbat2	1.3	(Consider epatch given a directory of patches <tt class="docutils literal"><span class="pre">${FILESDIR}/${PV}/</span></tt>,
337			where it blindly includes them, or alternatively, the package.mask file
338			or a profile being altered/missing).</p>
339	cardoe	1.1	<p>Note: The AUX entries should only be generated if we are generating a
340			compatible Manifest that supports older versions of Portage. They should
341			be generated along with the new type.</p>
342			</div>
343			</div>
344			<div class="section" id="backwards-compatibility">
345	robbat2	1.3	<h1><a class="toc-backref" href="#id27">Backwards Compatibility</a></h1>
346	cardoe	1.1	<p>For generation of existing package Manifests, the AUX entries must
347			continue to be present for the standard Portage deprecation cycle.
348			The new entries may be included already in all Manifest files, as they
349			will be ignored by older Portage versions. Over time, ECLASS, DATA,
350	robbat2	1.4	EXEC, OTHER may replace the existing AUX type.</p>
351	robbat2	1.3	<p>The adoption of this proposal does also affect [#GLEP58] as part of
352	cardoe	1.1	this GLEP series, however this GLEP was an offset of the research in
353			that GLEP.</p>
354			</div>
355			<div class="section" id="thanks-to">
356	robbat2	1.3	<h1><a class="toc-backref" href="#id28">Thanks to</a></h1>
357	cardoe	1.1	<p>I'd like to thank the following people for input on this GLEP.
358			- Marius Mauch (genone) & Zac Medico (zmedico): Portage Manifest2</p>
359			</div>
360			<div class="section" id="references">
361	robbat2	1.3	<h1><a class="toc-backref" href="#id29">References</a></h1>
362	cardoe	1.1	<table class="docutils footnote" frame="void" id="glep44" rules="none">
363			<colgroup><col class="label" /><col /></colgroup>
364			<tbody valign="top">
365			<tr><td class="label">[1]</td><td>Mauch, M. (2005) GLEP44 - Manifest2 format.
366			<a class="reference external" href="http://www.gentoo.org/proj/en/glep/glep-0044.html">http://www.gentoo.org/proj/en/glep/glep-0044.html</a></td></tr>
367			</tbody>
368			</table>
369			</div>
370			<div class="section" id="copyright">
371	robbat2	1.3	<h1><a class="toc-backref" href="#id30">Copyright</a></h1>
372	cardoe	1.1	<p>Copyright (c) 2007 by Robin Hugh Johnson. This material may be
373			distributed only subject to the terms and conditions set forth in the
374			Open Publication License, v1.0.</p>
375			<p>vim: tw=72 ts=2 expandtab:</p>
376			</div>
377
378			</div>
379			<div class="footer">
380			<hr class="footer" />
381			<a class="reference external" href="glep-0060.txt">View document source</a>.
382	robbat2	1.3	Generated on: 2008-10-28 07:47 UTC.
383	cardoe	1.1	Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
384
385			</div>
386			</body>
387			</html>