/[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.9 - (hide annotations) (download)
Sun Jan 31 09:55:43 2010 UTC (4 years, 6 months ago) by robbat2
Branch: MAIN
Changes since 1.8: +4 -3 lines
File MIME type: text/plain
Note that GLEP59-61 are independantly useful, even without GLEP58.

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

  ViewVC Help
Powered by ViewVC 1.1.20