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.6: 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.7</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">2010/01/13 03:26:53</a></td> |
33 |
</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 |
<tr class="field"><th class="field-name">Updated:</th><td class="field-body">June 2008, July 2008, October 2008, January 2010</td> |
47 |
</tr> |
48 |
<tr class="field"><th class="field-name">Updates:</th><td class="field-body">44</td> |
49 |
</tr> |
50 |
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">December 2009</td> |
51 |
</tr> |
52 |
</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 |
<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="#other-new" id="id24">OTHER (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 |
</ul> |
92 |
</div> |
93 |
<div class="section" id="abstract"> |
94 |
<h1><a class="toc-backref" href="#id4">Abstract</a></h1> |
95 |
<p>Clarification of the Manifest2 [#GLEP44] specification, including new types to |
96 |
help in the tree-signing specification.</p> |
97 |
</div> |
98 |
<div class="section" id="motivation"> |
99 |
<h1><a class="toc-backref" href="#id5">Motivation</a></h1> |
100 |
<p>[#GLEP44] was not entirely clear on the usage of filetype specifiers. |
101 |
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 |
<h1><a class="toc-backref" href="#id6">Specification</a></h1> |
107 |
<div class="section" id="general"> |
108 |
<h2><a class="toc-backref" href="#id7">General</a></h2> |
109 |
<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 |
<h2><a class="toc-backref" href="#id8">Excluded files</a></h2> |
116 |
<p>When generating or validating a Manifest, or committing 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 |
non-exhaustive list is suggested here: <tt class="docutils literal">CVS/</tt>, <tt class="docutils literal">.svn/</tt>, <tt class="docutils literal">.bzr/</tt>, |
120 |
<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> |
121 |
<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 |
<h2><a class="toc-backref" href="#id9">Existing filetypes:</a></h2> |
130 |
<div class="section" id="aux"> |
131 |
<h3><a class="toc-backref" href="#id10">AUX</a></h3> |
132 |
<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 |
<h3><a class="toc-backref" href="#id11">EBUILD</a></h3> |
144 |
<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 |
<h3><a class="toc-backref" href="#id12">DIST</a></h3> |
154 |
<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 |
<h3><a class="toc-backref" href="#id13">MISC</a></h3> |
165 |
<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 |
<h2><a class="toc-backref" href="#id14">New filetypes:</a></h2> |
180 |
<div class="section" id="info-new-abstract"> |
181 |
<h3><a class="toc-backref" href="#id15">_INFO (new, abstract)</a></h3> |
182 |
<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 |
<h3><a class="toc-backref" href="#id16">_CRIT (new, abstract)</a></h3> |
192 |
<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 |
<div class="section" id="id1"> |
199 |
<h3><a class="toc-backref" href="#id17">EBUILD</a></h3> |
200 |
<ul class="simple"> |
201 |
<li>Now derived from _CRIT.</li> |
202 |
<li>Otherwise unchanged.</li> |
203 |
</ul> |
204 |
</div> |
205 |
<div class="section" id="id2"> |
206 |
<h3><a class="toc-backref" href="#id18">DIST</a></h3> |
207 |
<ul class="simple"> |
208 |
<li>Now derived from _CRIT.</li> |
209 |
<li>Otherwise unchanged.</li> |
210 |
</ul> |
211 |
</div> |
212 |
<div class="section" id="id3"> |
213 |
<h3><a class="toc-backref" href="#id19">MISC</a></h3> |
214 |
<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 |
<h3><a class="toc-backref" href="#id20">MANIFEST (new)</a></h3> |
221 |
<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 (e.g. 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 |
<h3><a class="toc-backref" href="#id21">ECLASS (new)</a></h3> |
235 |
<ul class="simple"> |
236 |
<li>uses _CRIT.</li> |
237 |
<li>This type shall be used for all eclasses only.</li> |
238 |
</ul> |
239 |
</div> |
240 |
<div class="section" id="data-new"> |
241 |
<h3><a class="toc-backref" href="#id22">DATA (new)</a></h3> |
242 |
<ul class="simple"> |
243 |
<li>uses _CRIT.</li> |
244 |
<li>The DATA type shall be used for all files that directly affect the |
245 |
package manager, such as metadata/cache/* and profiles/.</li> |
246 |
</ul> |
247 |
</div> |
248 |
<div class="section" id="exec-new"> |
249 |
<h3><a class="toc-backref" href="#id23">EXEC (new)</a></h3> |
250 |
<ul class="simple"> |
251 |
<li>uses _CRIT.</li> |
252 |
<li>If the file gets sourced, executed, or causes a change (patches) in |
253 |
how something is sourced or executed, it belongs in the EXEC |
254 |
filetype.</li> |
255 |
<li>This filetype should be used for the scripts directories of a |
256 |
repository for important files.</li> |
257 |
<li>This filetype is not limited to being used in the files/ |
258 |
subdirectory.</li> |
259 |
</ul> |
260 |
</div> |
261 |
<div class="section" id="other-new"> |
262 |
<h3><a class="toc-backref" href="#id24">OTHER (new)</a></h3> |
263 |
<ul class="simple"> |
264 |
<li>uses _CRIT.</li> |
265 |
<li>All other files that are not covered by another type should be |
266 |
considered as 'OTHER'.</li> |
267 |
<li>Any further new filetypes should be introduced to subtract files |
268 |
from the 'OTHER' set.</li> |
269 |
<li>If a package manager runs into a unknown Manifest2 type, it should |
270 |
be treated as 'OTHER'.</li> |
271 |
</ul> |
272 |
</div> |
273 |
</div> |
274 |
<div class="section" id="on-bloat"> |
275 |
<h2><a class="toc-backref" href="#id25">On Bloat</a></h2> |
276 |
<p>If repeated use of a common path prefix is considered a bloat problem, a |
277 |
Manifest file should be added inside the common directory, however this |
278 |
should not be done blindly, as bloat by inodes is more significant for |
279 |
the majority of use cases. See also [#GLEP58] on size reductions of |
280 |
Manifests.</p> |
281 |
</div> |
282 |
<div class="section" id="chosing-a-filetype"> |
283 |
<h2><a class="toc-backref" href="#id26">Chosing a filetype</a></h2> |
284 |
<ol class="arabic"> |
285 |
<li><dl class="first docutils"> |
286 |
<dt>matches <tt class="docutils literal">Manifest</tt></dt> |
287 |
<dd><p class="first last">=> MANIFEST, stop.</p> |
288 |
</dd> |
289 |
</dl> |
290 |
</li> |
291 |
<li><dl class="first docutils"> |
292 |
<dt>matches <tt class="docutils literal">*.ebuild</tt></dt> |
293 |
<dd><p class="first last">=> EBUILD, stop.</p> |
294 |
</dd> |
295 |
</dl> |
296 |
</li> |
297 |
<li><dl class="first docutils"> |
298 |
<dt>matches <tt class="docutils literal">*.eclass</tt></dt> |
299 |
<dd><p class="first last">=> ECLASS, stop.</p> |
300 |
</dd> |
301 |
</dl> |
302 |
</li> |
303 |
<li><dl class="first docutils"> |
304 |
<dt>listed in SRC_URI</dt> |
305 |
<dd><p class="first last">=> DIST, stop.</p> |
306 |
</dd> |
307 |
</dl> |
308 |
</li> |
309 |
<li><dl class="first docutils"> |
310 |
<dt>matches <tt class="docutils literal">files/*</tt></dt> |
311 |
<dd><p class="first last">=> AUX, continue [see note].</p> |
312 |
</dd> |
313 |
</dl> |
314 |
</li> |
315 |
<li><dl class="first docutils"> |
316 |
<dt>matches any of <tt class="docutils literal">*.sh</tt>, <tt class="docutils literal">*.bashrc</tt>, <tt class="docutils literal">*.patch</tt>, ...</dt> |
317 |
<dd><p class="first last">=> EXEC, stop.</p> |
318 |
</dd> |
319 |
</dl> |
320 |
</li> |
321 |
<li><dl class="first docutils"> |
322 |
<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> |
323 |
<dd><p class="first last">=> DATA, stop.</p> |
324 |
</dd> |
325 |
</dl> |
326 |
</li> |
327 |
<li><dl class="first docutils"> |
328 |
<dt>matches any of <tt class="docutils literal">ChangeLog</tt>, <tt class="docutils literal">metadata.xml</tt>, <tt class="docutils literal">*.desc</tt>, ...</dt> |
329 |
<dd><p class="first last">=> MISC, stop.</p> |
330 |
</dd> |
331 |
</dl> |
332 |
</li> |
333 |
<li><dl class="first docutils"> |
334 |
<dt>not matched by any other rule</dt> |
335 |
<dd><p class="first last">=> OTHER, stop.</p> |
336 |
</dd> |
337 |
</dl> |
338 |
</li> |
339 |
</ol> |
340 |
<p>The logic behind 5, 6, 7 is ensuring that every item that by it's |
341 |
presence or absence may be dangerous should always be treated strictly. |
342 |
(Consider epatch given a directory of patches <tt class="docutils literal"><span class="pre">${FILESDIR}/${PV}/</span></tt>, |
343 |
where it blindly includes them, or alternatively, the package.mask file |
344 |
or a profile being altered/missing).</p> |
345 |
<p>The above lists of file patterns are not intended to be exhaustive, |
346 |
but merely demonstrative.</p> |
347 |
<p>Note: The AUX entries should only be generated if we are generating a |
348 |
compatible Manifest that supports older versions of Portage. They should |
349 |
be generated along with the new type.</p> |
350 |
</div> |
351 |
</div> |
352 |
<div class="section" id="backwards-compatibility"> |
353 |
<h1><a class="toc-backref" href="#id27">Backwards Compatibility</a></h1> |
354 |
<p>For generation of existing package Manifests, the AUX entries must |
355 |
continue to be present for the standard Portage deprecation cycle. |
356 |
The new entries may be included already in all Manifest files, as they |
357 |
will be ignored by older Portage versions. Over time, ECLASS, DATA, |
358 |
EXEC, OTHER may replace the existing AUX type.</p> |
359 |
<p>The adoption of this proposal does also affect [#GLEP58] as part of |
360 |
this GLEP series, however this GLEP was an offset of the research in |
361 |
that GLEP.</p> |
362 |
</div> |
363 |
<div class="section" id="thanks-to"> |
364 |
<h1><a class="toc-backref" href="#id28">Thanks to</a></h1> |
365 |
<p>I'd like to thank the following people for input on this GLEP. |
366 |
- Marius Mauch (genone) & Zac Medico (zmedico): Portage Manifest2</p> |
367 |
</div> |
368 |
<div class="section" id="references"> |
369 |
<h1><a class="toc-backref" href="#id29">References</a></h1> |
370 |
<table class="docutils footnote" frame="void" id="glep44" rules="none"> |
371 |
<colgroup><col class="label" /><col /></colgroup> |
372 |
<tbody valign="top"> |
373 |
<tr><td class="label">[1]</td><td>Mauch, M. (2005) GLEP44 - Manifest2 format. |
374 |
<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> |
375 |
</tbody> |
376 |
</table> |
377 |
</div> |
378 |
<div class="section" id="copyright"> |
379 |
<h1><a class="toc-backref" href="#id30">Copyright</a></h1> |
380 |
<p>Copyright (c) 2007-2010 by Robin Hugh Johnson. This material may be |
381 |
distributed only subject to the terms and conditions set forth in the |
382 |
Open Publication License, v1.0.</p> |
383 |
<p>vim: tw=72 ts=2 expandtab:</p> |
384 |
</div> |
385 |
|
386 |
</div> |
387 |
<div class="footer"> |
388 |
<hr class="footer" /> |
389 |
<a class="reference external" href="glep-0060.txt">View document source</a>. |
390 |
Generated on: 2010-01-13 03:27 UTC. |
391 |
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. |
392 |
|
393 |
</div> |
394 |
</body> |
395 |
</html> |