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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.8 - (show annotations) (download)
Sun Jan 31 07:56:58 2010 UTC (4 years, 10 months ago) by robbat2
Branch: MAIN
Changes since 1.7: +8 -3 lines
File MIME type: text/plain
Revise GLEP60 per Calchan questions: It is not required for tree-signing, but is merely nice to have.

1 GLEP: 60
2 Title: Manifest2 filetypes
3 Version: $Revision: 1.7 $
4 Last-Modified: $Date: 2010/01/13 03:26:53 $
5 Author: Robin Hugh Johnson <robbat2@gentoo.org>
6 Status: Draft
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Requires: 44
10 Created: November 2007
11 Updated: June 2008, July 2008, October 2008, January 2010
12 Updates: 44
13 Post-History: December 2009, January 2010
14
15 Abstract
16 ========
17 Clarification of the Manifest2 [#GLEP44] specification, including new types to
18 help in the tree-signing specification.
19
20 Motivation
21 ==========
22 [#GLEP44] was not entirely clear on the usage of filetype specifiers.
23 This document serves to provide some of the internal logic used by
24 Portage at the point of writing, as well as adding new types to cover
25 the rest of the tree, for the purposes of tree-signing coverage.
26
27 This GLEP is not mandatory for the tree-signing specification, but
28 instead aims to clarify the usage of the Manifest2 filetype specifiers,
29 and note which types signify files that are allowed to be missing from
30 the tree (e.g. a user excluding a package or category).
31
32 Specification
33 =============
34 General
35 -------
36 For any given directory with a Manifest file, every file located in that
37 directory, or a sub-directory must be listed in that Manifest file,
38 unless stated otherwise in the following sections. The Manifest file
39 must not contain an entry for itself.
40
41 Excluded files
42 --------------
43 When generating or validating a Manifest, or committing to a version
44 control system, the package manager should endeavour to ignore files
45 created by a version control system, backup files from text editors. A
46 non-exhaustive list is suggested here: ``CVS/``, ``.svn/``, ``.bzr/``,
47 ``.git/``, ``.hg/``, ``.#*``, ``*.rej``, ``*.orig``, ``*.bak``, ``*~``.
48
49 Additionally, for a transitional Manifest1->Manifest2 system, old-style
50 digest files located in a 'files/' directory, may be excluded from
51 Manifest2 generation, or included with a type of MISC.
52
53 Under strict security conditions, the exclusion list may be ignored
54 during validation if the existence of a file would be considered a
55 security risk.
56
57 Existing filetypes:
58 -------------------
59 AUX
60 ~~~
61 - The AUX type is used for all items under the 'files' subdirectory.
62 - They should be verified relative to $FILESDIR.
63 - The string 'files/' is left out of the Manifest line.
64 - The absence of a file mentioned by AUX must be treated as an error.
65 - The AUX type is intended to denote potentially executable content
66 (either directly or indirectly), that must be treated an error if
67 modified or absent.
68
69 EBUILD
70 ~~~~~~
71 - The EBUILD type is used solely for files ending in .ebuild, or other
72 suffixes as defined by the EAPI.
73 - The files are located in the same directory as the Manifest file.
74 - The modification or absence of a file mentioned by EBUILD must be
75 treated as an error.
76
77 DIST
78 ~~~~
79 - The DIST type is used for distfiles
80 - They may be found directly via the $DISTDIR setting of the package
81 manager.
82 - During simple verification of a Manifest, a missing DIST file should
83 not be consider as a validation error (it is however a failure to
84 fetch or unpack).
85
86 MISC
87 ~~~~
88 - The MISC type covers all remaining files in a directory.
89 - MISC is intended to mark all content that was not used in
90 some way that directly affected execution of the package manager.
91 - This includes metadata.xml and ChangeLog entries, and any other purely
92 informational content.
93 - MISC entries where the file is missing may optionally be ignored as by
94 non-strict package managers.
95 - It should be possible to install a package while all MISC entries have
96 been deleted from the tree.
97
98
99 New filetypes:
100 --------------
101 _INFO (new, abstract)
102 ~~~~~~~~~~~~~~~~~~~~~
103 - This is the functionality of the old AUX, but does not include the
104 implicit 'files/' prefix in the path, and is verified relative to the
105 working directory instead of $FILESDIR.
106 - The modification or absence of a file listed as a _INFO-derived type
107 is not an error unless the package manager is attempting to be strict.
108
109 _CRIT (new, abstract)
110 ~~~~~~~~~~~~~~~~~~~~~
111 - _CRIT is based off the _INFO type.
112 - The modification or absence of a file listed as a _CRIT-derived type
113 MUST be treated as an error.
114
115 EBUILD
116 ~~~~~~
117 - Now derived from _CRIT.
118 - Otherwise unchanged.
119
120 DIST
121 ~~~~
122 - Now derived from _CRIT.
123 - Otherwise unchanged.
124
125 MISC
126 ~~~~
127 - Now derived from _INFO.
128 - Otherwise unchanged.
129
130 MANIFEST (new)
131 ~~~~~~~~~~~~~~
132 - The MANIFEST type is explicitly to cover all nested Manifest files.
133 - During validation, this serves as an indicator that the package
134 manager may need to check subtree Manifest file.
135 - A missing MANIFEST file may be treated as a minor (e.g. excluding an
136 entire category) or critical validation failure.
137 - The failure should be considered as critical only if files that would
138 be directly covered by this Manifest are missing. Deletion of a
139 category-level Manifest while preserving the packages is forbidden.
140 Deletion of an entire category is not.
141
142 ECLASS (new)
143 ~~~~~~~~~~~~
144 - uses _CRIT.
145 - This type shall be used for all eclasses only.
146
147 DATA (new)
148 ~~~~~~~~~~
149 - uses _CRIT.
150 - The DATA type shall be used for all files that directly affect the
151 package manager, such as metadata/cache/* and profiles/.
152
153 EXEC (new)
154 ~~~~~~~~~~
155 - uses _CRIT.
156 - If the file gets sourced, executed, or causes a change (patches) in
157 how something is sourced or executed, it belongs in the EXEC
158 filetype.
159 - This filetype should be used for the scripts directories of a
160 repository for important files.
161 - This filetype is not limited to being used in the files/
162 subdirectory.
163
164 OTHER (new)
165 ~~~~~~~~~~~
166 - uses _CRIT.
167 - All other files that are not covered by another type should be
168 considered as 'OTHER'.
169 - Any further new filetypes should be introduced to subtract files
170 from the 'OTHER' set.
171 - If a package manager runs into a unknown Manifest2 type, it should
172 be treated as 'OTHER'.
173
174 On Bloat
175 --------
176 If repeated use of a common path prefix is considered a bloat problem, a
177 Manifest file should be added inside the common directory, however this
178 should not be done blindly, as bloat by inodes is more significant for
179 the majority of use cases. See also [#GLEP58] on size reductions of
180 Manifests.
181
182 Chosing a filetype
183 ------------------
184 1. matches ``Manifest``
185 => MANIFEST, stop.
186 2. matches ``*.ebuild``
187 => EBUILD, stop.
188 3. matches ``*.eclass``
189 => ECLASS, stop.
190 4. listed in SRC_URI
191 => DIST, stop.
192 5. matches ``files/*``
193 => AUX, continue [see note].
194 6. matches any of ``*.sh``, ``*.bashrc``, ``*.patch``, ...
195 => EXEC, stop.
196 7. matches any of ``metadata/cache/*``, ``profiles/``, ``package.*``, ``use.mask*``, ...
197 => DATA, stop.
198 8. matches any of ``ChangeLog``, ``metadata.xml``, ``*.desc``, ...
199 => MISC, stop.
200 9. not matched by any other rule
201 => OTHER, stop.
202
203 The logic behind 5, 6, 7 is ensuring that every item that by it's
204 presence or absence may be dangerous should always be treated strictly.
205 (Consider epatch given a directory of patches ``${FILESDIR}/${PV}/``,
206 where it blindly includes them, or alternatively, the package.mask file
207 or a profile being altered/missing).
208
209 The above lists of file patterns are not intended to be exhaustive,
210 but merely demonstrative.
211
212 Note: The AUX entries should only be generated if we are generating a
213 compatible Manifest that supports older versions of Portage. They should
214 be generated along with the new type.
215
216 Backwards Compatibility
217 =======================
218 For generation of existing package Manifests, the AUX entries must
219 continue to be present for the standard Portage deprecation cycle.
220 The new entries may be included already in all Manifest files, as they
221 will be ignored by older Portage versions. Over time, ECLASS, DATA,
222 EXEC, OTHER may replace the existing AUX type.
223
224 The adoption of this proposal does also affect [#GLEP58] as part of
225 this GLEP series, however this GLEP was an offset of the research in
226 that GLEP.
227
228 Thanks to
229 =========
230 I'd like to thank the following people for input on this GLEP.
231 - Marius Mauch (genone) & Zac Medico (zmedico): Portage Manifest2
232
233 References
234 ==========
235 .. [#GLEP44] Mauch, M. (2005) GLEP44 - Manifest2 format.
236 http://www.gentoo.org/proj/en/glep/glep-0044.html
237
238 Copyright
239 =========
240 Copyright (c) 2007-2010 by Robin Hugh Johnson. This material may be
241 distributed only subject to the terms and conditions set forth in the
242 Open Publication License, v1.0.
243
244 vim: tw=72 ts=2 expandtab:

  ViewVC Help
Powered by ViewVC 1.1.20