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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.1 Revision 1.8
1GLEP: 60 1GLEP: 60
2Title: Manifest2 filetypes 2Title: Manifest2 filetypes
3Version: $Revision: 1.1 $ 3Version: $Revision: 1.8 $
4Last-Modified: $Date: 2008/10/21 23:30:47 $ 4Last-Modified: $Date: 2010/01/31 07:56:58 $
5Author: Robin Hugh Johnson <robbat2@gentoo.org> 5Author: Robin Hugh Johnson <robbat2@gentoo.org>
6Status: Draft 6Status: Draft
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Requires: 44 9Requires: 44
10Created: November 2007 10Created: November 2007
11Updated: June 2008, July 2008 11Updated: June 2008, July 2008, October 2008, January 2010
12Updates: 44 12Updates: 44
13Post-History: December 2009, January 2010
13 14
14Abstract 15Abstract
15======== 16========
16Clarification of the Manifest2 [GLEP44] specification, including new types to 17Clarification of the Manifest2 [#GLEP44] specification, including new types to
17help in the tree-signing specification. 18help in the tree-signing specification.
18 19
19Motivation 20Motivation
20========== 21==========
21[GLEP44] was not entirely clear on the usage of filetype specifiers. 22[#GLEP44] was not entirely clear on the usage of filetype specifiers.
22This document serves to provide some of the internal logic used by 23This document serves to provide some of the internal logic used by
23Portage at the point of writing, as well as adding new types to cover 24Portage at the point of writing, as well as adding new types to cover
24the rest of the tree, for the purposes of tree-signing coverage. 25the rest of the tree, for the purposes of tree-signing coverage.
26
27This GLEP is not mandatory for the tree-signing specification, but
28instead aims to clarify the usage of the Manifest2 filetype specifiers,
29and note which types signify files that are allowed to be missing from
30the tree (e.g. a user excluding a package or category).
25 31
26Specification 32Specification
27============= 33=============
28General 34General
29------- 35-------
32unless stated otherwise in the following sections. The Manifest file 38unless stated otherwise in the following sections. The Manifest file
33must not contain an entry for itself. 39must not contain an entry for itself.
34 40
35Excluded files 41Excluded files
36-------------- 42--------------
37When generating or validating a Manifest, or commiting to a version 43When generating or validating a Manifest, or committing to a version
38control system, the package manager should endeavour to ignore files 44control system, the package manager should endeavour to ignore files
39created by a version control system, backup files from text editors. A 45created by a version control system, backup files from text editors. A
40non-exhaustive list is suggested here: CVS/, .svn/, .bzr/, .git/, .hg/, 46non-exhaustive list is suggested here: ``CVS/``, ``.svn/``, ``.bzr/``,
41.#*, *.rej, *.orig, *.bak, *~. 47``.git/``, ``.hg/``, ``.#*``, ``*.rej``, ``*.orig``, ``*.bak``, ``*~``.
42 48
43Additionally, for a transitional Manifest1->Manifest2 system, old-style 49Additionally, for a transitional Manifest1->Manifest2 system, old-style
44digest files located in a 'files/' directory, may be excluded from 50digest files located in a 'files/' directory, may be excluded from
45Manifest2 generation, or included with a type of MISC. 51Manifest2 generation, or included with a type of MISC.
46 52
91 97
92 98
93New filetypes: 99New filetypes:
94-------------- 100--------------
95_INFO (new, abstract) 101_INFO (new, abstract)
96~~~~~~~~~~~~~~~~~~~~~~~~~ 102~~~~~~~~~~~~~~~~~~~~~
97- This is the functionality of the old AUX, but does not include the 103- This is the functionality of the old AUX, but does not include the
98 implicit 'files/' prefix in the path, and is verified relative to the 104 implicit 'files/' prefix in the path, and is verified relative to the
99 working directory instead of $FILESDIR. 105 working directory instead of $FILESDIR.
100- The modification or absence of a file listed as a _INFO-derived type 106- The modification or absence of a file listed as a _INFO-derived type
101 is not an error unless the package manager is attempting to be strict. 107 is not an error unless the package manager is attempting to be strict.
102 108
103_CRIT (new, abstract) 109_CRIT (new, abstract)
104~~~~~~~~~~~~~~~~~~~~~~~~~ 110~~~~~~~~~~~~~~~~~~~~~
105- _CRIT is based off the _INFO type. 111- _CRIT is based off the _INFO type.
106- The modification or absence of a file listed as a _CRIT-derived type 112- The modification or absence of a file listed as a _CRIT-derived type
107 must be treated as an error. 113 MUST be treated as an error.
108 114
109EBUILD 115EBUILD
110~~~~~~ 116~~~~~~
111- Now derived from _CRIT. 117- Now derived from _CRIT.
112- Otherwise unchanged. 118- Otherwise unchanged.
124MANIFEST (new) 130MANIFEST (new)
125~~~~~~~~~~~~~~ 131~~~~~~~~~~~~~~
126- The MANIFEST type is explicitly to cover all nested Manifest files. 132- The MANIFEST type is explicitly to cover all nested Manifest files.
127- During validation, this serves as an indicator that the package 133- During validation, this serves as an indicator that the package
128 manager may need to check subtree Manifest file. 134 manager may need to check subtree Manifest file.
129- A missing MANIFEST file may be treated as a minor (eg excluding an 135- A missing MANIFEST file may be treated as a minor (e.g. excluding an
130 entire category) or critical validation failure. 136 entire category) or critical validation failure.
131- The failure should be considered as critical only if files that would 137- The failure should be considered as critical only if files that would
132 be directly covered by this Manifest are missing. Deletion of a 138 be directly covered by this Manifest are missing. Deletion of a
133 category-level Manifest while preserving the packages is forbidden. 139 category-level Manifest while preserving the packages is forbidden.
134 Deletion of an entire category is not. 140 Deletion of an entire category is not.
135 141
136ECLASS (new) 142ECLASS (new)
137~~~~~~~~~~~~ 143~~~~~~~~~~~~
138- uses _CRIT. 144- uses _CRIT.
139- This type shall be used for all eclasses only. 145- This type shall be used for all eclasses only.
140- TODO: What about patches etc under eclasses/? Probably EXEC?
141 146
142DATA (new) 147DATA (new)
143~~~~~~~~~~ 148~~~~~~~~~~
144- uses _CRIT. 149- uses _CRIT.
145- The DATA type shall be used for all files that directly affect the 150- The DATA type shall be used for all files that directly affect the
147 152
148EXEC (new) 153EXEC (new)
149~~~~~~~~~~ 154~~~~~~~~~~
150- uses _CRIT. 155- uses _CRIT.
151- If the file gets sourced, executed, or causes a change (patches) in 156- If the file gets sourced, executed, or causes a change (patches) in
152 how something is sourced or execututed, it belongs in the EXEC 157 how something is sourced or executed, it belongs in the EXEC
153 filetype. 158 filetype.
154- This filetype should be used for the scripts directories of a 159- This filetype should be used for the scripts directories of a
155 repository for important files. 160 repository for important files.
161- This filetype is not limited to being used in the files/
162 subdirectory.
156 163
157UNKNOWN (new) 164OTHER (new)
158~~~~~~~~~~~~~ 165~~~~~~~~~~~
159- uses _CRIT. 166- uses _CRIT.
160- All other files that are not covered by another type should be 167- All other files that are not covered by another type should be
161 considered as 'UNKNOWN'. 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'.
162 173
163On Bloat 174On Bloat
164-------- 175--------
165If repeated use of a common path prefix is considered a bloat problem, a 176If repeated use of a common path prefix is considered a bloat problem, a
166Manifest file should be added inside the common directory, however this 177Manifest file should be added inside the common directory, however this
167should not be done blindly, as bloat by inodes is more significant for 178should not be done blindly, as bloat by inodes is more significant for
168the majority of use cases. 179the majority of use cases. See also [#GLEP58] on size reductions of
180Manifests.
169 181
170Chosing a filetype 182Chosing a filetype
171------------------ 183------------------
1721. matches Manifest 1841. matches ``Manifest``
173 => MANIFEST, stop. 185 => MANIFEST, stop.
1742. matches *.ebuild 1862. matches ``*.ebuild``
175 => EBUILD, stop. 187 => EBUILD, stop.
1763. matches *.eclass 1883. matches ``*.eclass``
177 => ECLASS, stop. 189 => ECLASS, stop.
1784. listed in SRC_URI 1904. listed in SRC_URI
179 => DIST, stop. 191 => DIST, stop.
1805. matches files/* 1925. matches ``files/*``
181 => AUX, continue [see note]. 193 => AUX, continue [see note].
1826. matches {*.sh,*.bashrc,*.patch,...} 1946. matches any of ``*.sh``, ``*.bashrc``, ``*.patch``, ...
183 => EXEC, stop. 195 => EXEC, stop.
1847. matches {metadata/cache/*,profiles/,package.*,use.mask*,...} 1967. matches any of ``metadata/cache/*``, ``profiles/``, ``package.*``, ``use.mask*``, ...
185 => DATA, stop. 197 => DATA, stop.
1868. matches {ChangeLog,metadata.xml,*.desc,...} 1988. matches any of ``ChangeLog``, ``metadata.xml``, ``*.desc``, ...
187 => MISC, stop. 199 => MISC, stop.
1889. not matched by any other rule 2009. not matched by any other rule
189 => UNKNOWN, stop. 201 => OTHER, stop.
190 202
191The logic behind 5, 6, 7 is ensuring that every item that by it's 203The logic behind 5, 6, 7 is ensuring that every item that by it's
192presence or absense may be dangerous should always be treated strictly. 204presence or absence may be dangerous should always be treated strictly.
193(Consider epatch given a directory of patches ${FILESDIR}/${PV}/, where 205(Consider epatch given a directory of patches ``${FILESDIR}/${PV}/``,
194it blindly includes them, or alternatively, the package.mask file or a 206where it blindly includes them, or alternatively, the package.mask file
195profile being altered/missing). 207or a profile being altered/missing).
208
209The above lists of file patterns are not intended to be exhaustive,
210but merely demonstrative.
196 211
197Note: The AUX entries should only be generated if we are generating a 212Note: The AUX entries should only be generated if we are generating a
198compatible Manifest that supports older versions of Portage. They should 213compatible Manifest that supports older versions of Portage. They should
199be generated along with the new type. 214be generated along with the new type.
200 215
202======================= 217=======================
203For generation of existing package Manifests, the AUX entries must 218For generation of existing package Manifests, the AUX entries must
204continue to be present for the standard Portage deprecation cycle. 219continue to be present for the standard Portage deprecation cycle.
205The new entries may be included already in all Manifest files, as they 220The new entries may be included already in all Manifest files, as they
206will be ignored by older Portage versions. Over time, ECLASS, DATA, 221will be ignored by older Portage versions. Over time, ECLASS, DATA,
207EXEC, UNKNOWN may replace the existing AUX type. 222EXEC, OTHER may replace the existing AUX type.
208 223
209The adoption of this proposal does also affect [GLEPxx+1] as part of 224The adoption of this proposal does also affect [#GLEP58] as part of
210this GLEP series, however this GLEP was an offset of the research in 225this GLEP series, however this GLEP was an offset of the research in
211that GLEP. 226that GLEP.
212 227
213Thanks to 228Thanks to
214========= 229=========
220.. [#GLEP44] Mauch, M. (2005) GLEP44 - Manifest2 format. 235.. [#GLEP44] Mauch, M. (2005) GLEP44 - Manifest2 format.
221 http://www.gentoo.org/proj/en/glep/glep-0044.html 236 http://www.gentoo.org/proj/en/glep/glep-0044.html
222 237
223Copyright 238Copyright
224========= 239=========
225Copyright (c) 2007 by Robin Hugh Johnson. This material may be 240Copyright (c) 2007-2010 by Robin Hugh Johnson. This material may be
226distributed only subject to the terms and conditions set forth in the 241distributed only subject to the terms and conditions set forth in the
227Open Publication License, v1.0. 242Open Publication License, v1.0.
228 243
229vim: tw=72 ts=2 expandtab: 244vim: tw=72 ts=2 expandtab:

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.8

  ViewVC Help
Powered by ViewVC 1.1.20