/[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.7 - (hide annotations) (download)
Wed Jan 13 03:26:53 2010 UTC (4 years, 3 months ago) by robbat2
Branch: MAIN
Changes since 1.6: +7 -7 lines
File MIME type: text/plain
Fix spelling in treesigning gleps.

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

  ViewVC Help
Powered by ViewVC 1.1.20