/[gentoo]/xml/htdocs/proj/en/glep/glep-0060.html
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0060.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.7 - (hide annotations) (download) (as text)
Sun Jan 31 07:57:09 2010 UTC (4 years, 7 months ago) by robbat2
Branch: MAIN
Changes since 1.6: +8 -4 lines
File MIME type: text/html
Revise GLEP60 per Calchan questions: It is not required for tree-signing, but is merely nice to have.

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 robbat2 1.5 <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
8 cardoe 1.1 <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.7 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.8</td>
31 cardoe 1.1 </tr>
32 robbat2 1.7 <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">2010/01/31 07:56:58</a></td>
33 cardoe 1.1 </tr>
34     <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>
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.5 <tr class="field"><th class="field-name">Updated:</th><td class="field-body">June 2008, July 2008, October 2008, January 2010</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.7 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">December 2009, January 2010</td>
51 robbat2 1.3 </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 robbat2 1.7 <p>This GLEP is not mandatory for the tree-signing specification, but
105     instead aims to clarify the usage of the Manifest2 filetype specifiers,
106     and note which types signify files that are allowed to be missing from
107     the tree (e.g. a user excluding a package or category).</p>
108 cardoe 1.1 </div>
109     <div class="section" id="specification">
110 robbat2 1.3 <h1><a class="toc-backref" href="#id6">Specification</a></h1>
111 cardoe 1.1 <div class="section" id="general">
112 robbat2 1.3 <h2><a class="toc-backref" href="#id7">General</a></h2>
113 cardoe 1.1 <p>For any given directory with a Manifest file, every file located in that
114     directory, or a sub-directory must be listed in that Manifest file,
115     unless stated otherwise in the following sections. The Manifest file
116     must not contain an entry for itself.</p>
117     </div>
118     <div class="section" id="excluded-files">
119 robbat2 1.3 <h2><a class="toc-backref" href="#id8">Excluded files</a></h2>
120 robbat2 1.6 <p>When generating or validating a Manifest, or committing to a version
121 cardoe 1.1 control system, the package manager should endeavour to ignore files
122     created by a version control system, backup files from text editors. A
123 robbat2 1.5 non-exhaustive list is suggested here: <tt class="docutils literal">CVS/</tt>, <tt class="docutils literal">.svn/</tt>, <tt class="docutils literal">.bzr/</tt>,
124     <tt class="docutils literal">.git/</tt>, <tt class="docutils literal">.hg/</tt>, <tt class="docutils literal">.#*</tt>, <tt class="docutils literal">*.rej</tt>, <tt class="docutils literal">*.orig</tt>, <tt class="docutils literal">*.bak</tt>, <tt class="docutils literal">*~</tt>.</p>
125 cardoe 1.1 <p>Additionally, for a transitional Manifest1-&gt;Manifest2 system, old-style
126     digest files located in a 'files/' directory, may be excluded from
127     Manifest2 generation, or included with a type of MISC.</p>
128     <p>Under strict security conditions, the exclusion list may be ignored
129     during validation if the existence of a file would be considered a
130     security risk.</p>
131     </div>
132     <div class="section" id="existing-filetypes">
133 robbat2 1.3 <h2><a class="toc-backref" href="#id9">Existing filetypes:</a></h2>
134 cardoe 1.1 <div class="section" id="aux">
135 robbat2 1.3 <h3><a class="toc-backref" href="#id10">AUX</a></h3>
136 cardoe 1.1 <ul class="simple">
137     <li>The AUX type is used for all items under the 'files' subdirectory.</li>
138     <li>They should be verified relative to $FILESDIR.</li>
139     <li>The string 'files/' is left out of the Manifest line.</li>
140     <li>The absence of a file mentioned by AUX must be treated as an error.</li>
141     <li>The AUX type is intended to denote potentially executable content
142     (either directly or indirectly), that must be treated an error if
143     modified or absent.</li>
144     </ul>
145     </div>
146     <div class="section" id="ebuild">
147 robbat2 1.3 <h3><a class="toc-backref" href="#id11">EBUILD</a></h3>
148 cardoe 1.1 <ul class="simple">
149     <li>The EBUILD type is used solely for files ending in .ebuild, or other
150     suffixes as defined by the EAPI.</li>
151     <li>The files are located in the same directory as the Manifest file.</li>
152     <li>The modification or absence of a file mentioned by EBUILD must be
153     treated as an error.</li>
154     </ul>
155     </div>
156     <div class="section" id="dist">
157 robbat2 1.3 <h3><a class="toc-backref" href="#id12">DIST</a></h3>
158 cardoe 1.1 <ul class="simple">
159     <li>The DIST type is used for distfiles</li>
160     <li>They may be found directly via the $DISTDIR setting of the package
161     manager.</li>
162     <li>During simple verification of a Manifest, a missing DIST file should
163     not be consider as a validation error (it is however a failure to
164     fetch or unpack).</li>
165     </ul>
166     </div>
167     <div class="section" id="misc">
168 robbat2 1.3 <h3><a class="toc-backref" href="#id13">MISC</a></h3>
169 cardoe 1.1 <ul class="simple">
170     <li>The MISC type covers all remaining files in a directory.</li>
171     <li>MISC is intended to mark all content that was not used in
172     some way that directly affected execution of the package manager.</li>
173     <li>This includes metadata.xml and ChangeLog entries, and any other purely
174     informational content.</li>
175     <li>MISC entries where the file is missing may optionally be ignored as by
176     non-strict package managers.</li>
177     <li>It should be possible to install a package while all MISC entries have
178     been deleted from the tree.</li>
179     </ul>
180     </div>
181     </div>
182     <div class="section" id="new-filetypes">
183 robbat2 1.3 <h2><a class="toc-backref" href="#id14">New filetypes:</a></h2>
184 cardoe 1.1 <div class="section" id="info-new-abstract">
185 robbat2 1.3 <h3><a class="toc-backref" href="#id15">_INFO (new, abstract)</a></h3>
186 cardoe 1.1 <ul class="simple">
187     <li>This is the functionality of the old AUX, but does not include the
188     implicit 'files/' prefix in the path, and is verified relative to the
189     working directory instead of $FILESDIR.</li>
190     <li>The modification or absence of a file listed as a _INFO-derived type
191     is not an error unless the package manager is attempting to be strict.</li>
192     </ul>
193     </div>
194     <div class="section" id="crit-new-abstract">
195 robbat2 1.3 <h3><a class="toc-backref" href="#id16">_CRIT (new, abstract)</a></h3>
196 cardoe 1.1 <ul class="simple">
197     <li>_CRIT is based off the _INFO type.</li>
198     <li>The modification or absence of a file listed as a _CRIT-derived type
199 robbat2 1.5 MUST be treated as an error.</li>
200 cardoe 1.1 </ul>
201     </div>
202 robbat2 1.3 <div class="section" id="id1">
203     <h3><a class="toc-backref" href="#id17">EBUILD</a></h3>
204 cardoe 1.1 <ul class="simple">
205     <li>Now derived from _CRIT.</li>
206     <li>Otherwise unchanged.</li>
207     </ul>
208     </div>
209 robbat2 1.3 <div class="section" id="id2">
210     <h3><a class="toc-backref" href="#id18">DIST</a></h3>
211 cardoe 1.1 <ul class="simple">
212     <li>Now derived from _CRIT.</li>
213     <li>Otherwise unchanged.</li>
214     </ul>
215     </div>
216 robbat2 1.3 <div class="section" id="id3">
217     <h3><a class="toc-backref" href="#id19">MISC</a></h3>
218 cardoe 1.1 <ul class="simple">
219     <li>Now derived from _INFO.</li>
220     <li>Otherwise unchanged.</li>
221     </ul>
222     </div>
223     <div class="section" id="manifest-new">
224 robbat2 1.3 <h3><a class="toc-backref" href="#id20">MANIFEST (new)</a></h3>
225 cardoe 1.1 <ul class="simple">
226     <li>The MANIFEST type is explicitly to cover all nested Manifest files.</li>
227     <li>During validation, this serves as an indicator that the package
228     manager may need to check subtree Manifest file.</li>
229 robbat2 1.6 <li>A missing MANIFEST file may be treated as a minor (e.g. excluding an
230 cardoe 1.1 entire category) or critical validation failure.</li>
231     <li>The failure should be considered as critical only if files that would
232     be directly covered by this Manifest are missing. Deletion of a
233     category-level Manifest while preserving the packages is forbidden.
234     Deletion of an entire category is not.</li>
235     </ul>
236     </div>
237     <div class="section" id="eclass-new">
238 robbat2 1.3 <h3><a class="toc-backref" href="#id21">ECLASS (new)</a></h3>
239 cardoe 1.1 <ul class="simple">
240     <li>uses _CRIT.</li>
241     <li>This type shall be used for all eclasses only.</li>
242     </ul>
243     </div>
244     <div class="section" id="data-new">
245 robbat2 1.3 <h3><a class="toc-backref" href="#id22">DATA (new)</a></h3>
246 cardoe 1.1 <ul class="simple">
247     <li>uses _CRIT.</li>
248     <li>The DATA type shall be used for all files that directly affect the
249     package manager, such as metadata/cache/* and profiles/.</li>
250     </ul>
251     </div>
252     <div class="section" id="exec-new">
253 robbat2 1.3 <h3><a class="toc-backref" href="#id23">EXEC (new)</a></h3>
254 cardoe 1.1 <ul class="simple">
255     <li>uses _CRIT.</li>
256     <li>If the file gets sourced, executed, or causes a change (patches) in
257 robbat2 1.6 how something is sourced or executed, it belongs in the EXEC
258 cardoe 1.1 filetype.</li>
259     <li>This filetype should be used for the scripts directories of a
260     repository for important files.</li>
261 robbat2 1.5 <li>This filetype is not limited to being used in the files/
262     subdirectory.</li>
263 cardoe 1.1 </ul>
264     </div>
265 robbat2 1.4 <div class="section" id="other-new">
266     <h3><a class="toc-backref" href="#id24">OTHER (new)</a></h3>
267 cardoe 1.1 <ul class="simple">
268     <li>uses _CRIT.</li>
269     <li>All other files that are not covered by another type should be
270 robbat2 1.4 considered as 'OTHER'.</li>
271 robbat2 1.5 <li>Any further new filetypes should be introduced to subtract files
272     from the 'OTHER' set.</li>
273     <li>If a package manager runs into a unknown Manifest2 type, it should
274     be treated as 'OTHER'.</li>
275 cardoe 1.1 </ul>
276     </div>
277     </div>
278     <div class="section" id="on-bloat">
279 robbat2 1.3 <h2><a class="toc-backref" href="#id25">On Bloat</a></h2>
280 cardoe 1.1 <p>If repeated use of a common path prefix is considered a bloat problem, a
281     Manifest file should be added inside the common directory, however this
282     should not be done blindly, as bloat by inodes is more significant for
283 robbat2 1.5 the majority of use cases. See also [#GLEP58] on size reductions of
284     Manifests.</p>
285 cardoe 1.1 </div>
286     <div class="section" id="chosing-a-filetype">
287 robbat2 1.3 <h2><a class="toc-backref" href="#id26">Chosing a filetype</a></h2>
288 cardoe 1.1 <ol class="arabic">
289     <li><dl class="first docutils">
290 robbat2 1.5 <dt>matches <tt class="docutils literal">Manifest</tt></dt>
291 cardoe 1.1 <dd><p class="first last">=&gt; MANIFEST, stop.</p>
292     </dd>
293     </dl>
294     </li>
295     <li><dl class="first docutils">
296 robbat2 1.5 <dt>matches <tt class="docutils literal">*.ebuild</tt></dt>
297 robbat2 1.3 <dd><p class="first last">=&gt; EBUILD, stop.</p>
298 cardoe 1.1 </dd>
299     </dl>
300     </li>
301     <li><dl class="first docutils">
302 robbat2 1.5 <dt>matches <tt class="docutils literal">*.eclass</tt></dt>
303 robbat2 1.3 <dd><p class="first last">=&gt; ECLASS, stop.</p>
304 cardoe 1.1 </dd>
305     </dl>
306     </li>
307     <li><dl class="first docutils">
308     <dt>listed in SRC_URI</dt>
309     <dd><p class="first last">=&gt; DIST, stop.</p>
310     </dd>
311     </dl>
312     </li>
313     <li><dl class="first docutils">
314 robbat2 1.5 <dt>matches <tt class="docutils literal">files/*</tt></dt>
315 cardoe 1.1 <dd><p class="first last">=&gt; AUX, continue [see note].</p>
316     </dd>
317     </dl>
318     </li>
319     <li><dl class="first docutils">
320 robbat2 1.5 <dt>matches any of <tt class="docutils literal">*.sh</tt>, <tt class="docutils literal">*.bashrc</tt>, <tt class="docutils literal">*.patch</tt>, ...</dt>
321 cardoe 1.1 <dd><p class="first last">=&gt; EXEC, stop.</p>
322     </dd>
323     </dl>
324     </li>
325     <li><dl class="first docutils">
326 robbat2 1.5 <dt>matches any of <tt class="docutils literal">metadata/cache/*</tt>, <tt class="docutils literal">profiles/</tt>, <tt class="docutils literal">package.*</tt>, <tt class="docutils literal">use.mask*</tt>, ...</dt>
327 cardoe 1.1 <dd><p class="first last">=&gt; DATA, stop.</p>
328     </dd>
329     </dl>
330     </li>
331     <li><dl class="first docutils">
332 robbat2 1.5 <dt>matches any of <tt class="docutils literal">ChangeLog</tt>, <tt class="docutils literal">metadata.xml</tt>, <tt class="docutils literal">*.desc</tt>, ...</dt>
333 cardoe 1.1 <dd><p class="first last">=&gt; MISC, stop.</p>
334     </dd>
335     </dl>
336     </li>
337     <li><dl class="first docutils">
338     <dt>not matched by any other rule</dt>
339 robbat2 1.4 <dd><p class="first last">=&gt; OTHER, stop.</p>
340 cardoe 1.1 </dd>
341     </dl>
342     </li>
343     </ol>
344     <p>The logic behind 5, 6, 7 is ensuring that every item that by it's
345 robbat2 1.6 presence or absence may be dangerous should always be treated strictly.
346 robbat2 1.3 (Consider epatch given a directory of patches <tt class="docutils literal"><span class="pre">${FILESDIR}/${PV}/</span></tt>,
347     where it blindly includes them, or alternatively, the package.mask file
348     or a profile being altered/missing).</p>
349 robbat2 1.5 <p>The above lists of file patterns are not intended to be exhaustive,
350     but merely demonstrative.</p>
351 cardoe 1.1 <p>Note: The AUX entries should only be generated if we are generating a
352     compatible Manifest that supports older versions of Portage. They should
353     be generated along with the new type.</p>
354     </div>
355     </div>
356     <div class="section" id="backwards-compatibility">
357 robbat2 1.3 <h1><a class="toc-backref" href="#id27">Backwards Compatibility</a></h1>
358 cardoe 1.1 <p>For generation of existing package Manifests, the AUX entries must
359     continue to be present for the standard Portage deprecation cycle.
360     The new entries may be included already in all Manifest files, as they
361     will be ignored by older Portage versions. Over time, ECLASS, DATA,
362 robbat2 1.4 EXEC, OTHER may replace the existing AUX type.</p>
363 robbat2 1.3 <p>The adoption of this proposal does also affect [#GLEP58] as part of
364 cardoe 1.1 this GLEP series, however this GLEP was an offset of the research in
365     that GLEP.</p>
366     </div>
367     <div class="section" id="thanks-to">
368 robbat2 1.3 <h1><a class="toc-backref" href="#id28">Thanks to</a></h1>
369 cardoe 1.1 <p>I'd like to thank the following people for input on this GLEP.
370     - Marius Mauch (genone) &amp; Zac Medico (zmedico): Portage Manifest2</p>
371     </div>
372     <div class="section" id="references">
373 robbat2 1.3 <h1><a class="toc-backref" href="#id29">References</a></h1>
374 cardoe 1.1 <table class="docutils footnote" frame="void" id="glep44" rules="none">
375     <colgroup><col class="label" /><col /></colgroup>
376     <tbody valign="top">
377     <tr><td class="label">[1]</td><td>Mauch, M. (2005) GLEP44 - Manifest2 format.
378     <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>
379     </tbody>
380     </table>
381     </div>
382     <div class="section" id="copyright">
383 robbat2 1.3 <h1><a class="toc-backref" href="#id30">Copyright</a></h1>
384 robbat2 1.6 <p>Copyright (c) 2007-2010 by Robin Hugh Johnson. This material may be
385 cardoe 1.1 distributed only subject to the terms and conditions set forth in the
386     Open Publication License, v1.0.</p>
387     <p>vim: tw=72 ts=2 expandtab:</p>
388     </div>
389    
390     </div>
391     <div class="footer">
392     <hr class="footer" />
393     <a class="reference external" href="glep-0060.txt">View document source</a>.
394 robbat2 1.7 Generated on: 2010-01-31 07:57 UTC.
395 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.
396    
397     </div>
398     </body>
399     </html>

  ViewVC Help
Powered by ViewVC 1.1.20