/[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.3 - (hide annotations) (download) (as text)
Tue Oct 28 07:47:52 2008 UTC (6 years ago) by robbat2
Branch: MAIN
Changes since 1.2: +85 -103 lines
File MIME type: text/html
Regen 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 &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.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     <li><a class="reference internal" href="#unknown-new" id="id24">UNKNOWN (new)</a></li>
81     </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-&gt;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     <div class="section" id="unknown-new">
261 robbat2 1.3 <h3><a class="toc-backref" href="#id24">UNKNOWN (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     considered as 'UNKNOWN'.</li>
266     </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">=&gt; 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">=&gt; 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">=&gt; 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">=&gt; 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">=&gt; 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">=&gt; 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">=&gt; 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">=&gt; 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     <dd><p class="first last">=&gt; UNKNOWN, stop.</p>
330     </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     EXEC, UNKNOWN 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) &amp; 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>

  ViewVC Help
Powered by ViewVC 1.1.20