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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.1 - (show annotations) (download) (as text)
Tue Oct 21 23:30:47 2008 UTC (10 years, 5 months ago) by cardoe
Branch: MAIN
File MIME type: text/html
add Robin's tree signing gleps. They still need lots of editing love (some won't glep-ify) but at least they're here and have glep #s reserved

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

  ViewVC Help
Powered by ViewVC 1.1.20