/[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.4 - (hide annotations) (download)
Wed Jan 13 00:35:49 2010 UTC (4 years, 7 months ago) by robbat2
Branch: MAIN
Changes since 1.3: +7 -7 lines
File MIME type: text/plain
Name the default type "OTHER" instead of UNKNOWN for the Manifest2 types, per discussion with ulm.

1 cardoe 1.1 GLEP: 60
2     Title: Manifest2 filetypes
3 robbat2 1.4 Version: $Revision: 1.3 $
4     Last-Modified: $Date: 2008/10/28 07:46:51 $
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.3 Updated: June 2008, July 2008, October 2008
12 cardoe 1.1 Updates: 44
13 robbat2 1.3 Post-History:
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     When generating or validating a Manifest, or commiting to a version
39     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     must be treated as an error.
109    
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     - A missing MANIFEST file may be treated as a minor (eg excluding an
131     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     - TODO: What about patches etc under eclasses/? Probably EXEC?
142    
143     DATA (new)
144     ~~~~~~~~~~
145     - uses _CRIT.
146     - The DATA type shall be used for all files that directly affect the
147     package manager, such as metadata/cache/* and profiles/.
148    
149     EXEC (new)
150     ~~~~~~~~~~
151     - uses _CRIT.
152     - If the file gets sourced, executed, or causes a change (patches) in
153     how something is sourced or execututed, it belongs in the EXEC
154     filetype.
155     - This filetype should be used for the scripts directories of a
156     repository for important files.
157    
158 robbat2 1.4 OTHER (new)
159     ~~~~~~~~~~~
160 cardoe 1.1 - uses _CRIT.
161     - All other files that are not covered by another type should be
162 robbat2 1.4 considered as 'OTHER'.
163 cardoe 1.1
164     On Bloat
165     --------
166     If repeated use of a common path prefix is considered a bloat problem, a
167     Manifest file should be added inside the common directory, however this
168     should not be done blindly, as bloat by inodes is more significant for
169     the majority of use cases.
170    
171     Chosing a filetype
172     ------------------
173     1. matches Manifest
174     => MANIFEST, stop.
175 robbat2 1.3 2. matches ``*.ebuild``
176 cardoe 1.1 => EBUILD, stop.
177 robbat2 1.3 3. matches ``*.eclass``
178 cardoe 1.1 => ECLASS, stop.
179     4. listed in SRC_URI
180     => DIST, stop.
181 robbat2 1.3 5. matches ``files/*``
182 cardoe 1.1 => AUX, continue [see note].
183 robbat2 1.3 6. matches any of ``*.sh``, ``*.bashrc``, ``*.patch``, ...
184 cardoe 1.1 => EXEC, stop.
185 robbat2 1.3 7. matches any of ``metadata/cache/*``, ``profiles/``, ``package.*``, ``use.mask*``, ...
186 cardoe 1.1 => DATA, stop.
187 robbat2 1.3 8. matches any of ``ChangeLog``, ``metadata.xml``, ``*.desc``, ...
188 cardoe 1.1 => MISC, stop.
189     9. not matched by any other rule
190 robbat2 1.4 => OTHER, stop.
191 cardoe 1.1
192     The logic behind 5, 6, 7 is ensuring that every item that by it's
193     presence or absense may be dangerous should always be treated strictly.
194 robbat2 1.3 (Consider epatch given a directory of patches ``${FILESDIR}/${PV}/``,
195     where it blindly includes them, or alternatively, the package.mask file
196     or a profile being altered/missing).
197 cardoe 1.1
198     Note: The AUX entries should only be generated if we are generating a
199     compatible Manifest that supports older versions of Portage. They should
200     be generated along with the new type.
201    
202     Backwards Compatibility
203     =======================
204     For generation of existing package Manifests, the AUX entries must
205     continue to be present for the standard Portage deprecation cycle.
206     The new entries may be included already in all Manifest files, as they
207     will be ignored by older Portage versions. Over time, ECLASS, DATA,
208 robbat2 1.4 EXEC, OTHER may replace the existing AUX type.
209 cardoe 1.1
210 robbat2 1.3 The adoption of this proposal does also affect [#GLEP58] as part of
211 cardoe 1.1 this GLEP series, however this GLEP was an offset of the research in
212     that GLEP.
213    
214     Thanks to
215     =========
216     I'd like to thank the following people for input on this GLEP.
217     - Marius Mauch (genone) & Zac Medico (zmedico): Portage Manifest2
218    
219     References
220     ==========
221     .. [#GLEP44] Mauch, M. (2005) GLEP44 - Manifest2 format.
222     http://www.gentoo.org/proj/en/glep/glep-0044.html
223    
224     Copyright
225     =========
226     Copyright (c) 2007 by Robin Hugh Johnson. This material may be
227     distributed only subject to the terms and conditions set forth in the
228     Open Publication License, v1.0.
229    
230     vim: tw=72 ts=2 expandtab:

  ViewVC Help
Powered by ViewVC 1.1.20