| 1 | GLEP: 60 |
1 | GLEP: 60 |
| 2 | Title: Manifest2 filetypes |
2 | Title: Manifest2 filetypes |
| 3 | Version: $Revision: 1.2 $ |
3 | Version: $Revision: 1.6 $ |
| 4 | Last-Modified: $Date: 2008/10/22 17:59:43 $ |
4 | Last-Modified: $Date: 2010/01/13 00:54:50 $ |
| 5 | Author: Robin Hugh Johnson <robbat2@gentoo.org> |
5 | Author: Robin Hugh Johnson <robbat2@gentoo.org> |
| 6 | Status: Draft |
6 | Status: Draft |
| 7 | Type: Standards Track |
7 | Type: Standards Track |
| 8 | Content-Type: text/x-rst |
8 | Content-Type: text/x-rst |
| 9 | Requires: 44 |
9 | Requires: 44 |
| 10 | Created: November 2007 |
10 | Created: November 2007 |
| 11 | Updated: June 2008, July 2008 |
11 | Updated: June 2008, July 2008, October 2008, January 2010 |
| 12 | Updates: 44 |
12 | Updates: 44 |
|
|
13 | Post-History: December 2009 |
| 13 | |
14 | |
| 14 | Abstract |
15 | Abstract |
| 15 | ======== |
16 | ======== |
| 16 | Clarification of the Manifest2 [GLEP44] specification, including new types to |
17 | Clarification of the Manifest2 [#GLEP44] specification, including new types to |
| 17 | help in the tree-signing specification. |
18 | help in the tree-signing specification. |
| 18 | |
19 | |
| 19 | Motivation |
20 | Motivation |
| 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. |
| 22 | This document serves to provide some of the internal logic used by |
23 | This document serves to provide some of the internal logic used by |
| 23 | Portage at the point of writing, as well as adding new types to cover |
24 | Portage at the point of writing, as well as adding new types to cover |
| 24 | the rest of the tree, for the purposes of tree-signing coverage. |
25 | the rest of the tree, for the purposes of tree-signing coverage. |
| 25 | |
26 | |
| 26 | Specification |
27 | Specification |
| … | |
… | |
| 35 | Excluded files |
36 | Excluded files |
| 36 | -------------- |
37 | -------------- |
| 37 | When generating or validating a Manifest, or commiting to a version |
38 | When generating or validating a Manifest, or commiting to a version |
| 38 | control system, the package manager should endeavour to ignore files |
39 | control system, the package manager should endeavour to ignore files |
| 39 | created by a version control system, backup files from text editors. A |
40 | created by a version control system, backup files from text editors. A |
| 40 | non-exhaustive list is suggested here: CVS/, .svn/, .bzr/, .git/, .hg/, |
41 | non-exhaustive list is suggested here: ``CVS/``, ``.svn/``, ``.bzr/``, |
| 41 | .#*, *.rej, *.orig, *.bak, *~. |
42 | ``.git/``, ``.hg/``, ``.#*``, ``*.rej``, ``*.orig``, ``*.bak``, ``*~``. |
| 42 | |
43 | |
| 43 | Additionally, for a transitional Manifest1->Manifest2 system, old-style |
44 | Additionally, for a transitional Manifest1->Manifest2 system, old-style |
| 44 | digest files located in a 'files/' directory, may be excluded from |
45 | digest files located in a 'files/' directory, may be excluded from |
| 45 | Manifest2 generation, or included with a type of MISC. |
46 | Manifest2 generation, or included with a type of MISC. |
| 46 | |
47 | |
| … | |
… | |
| 102 | |
103 | |
| 103 | _CRIT (new, abstract) |
104 | _CRIT (new, abstract) |
| 104 | ~~~~~~~~~~~~~~~~~~~~~ |
105 | ~~~~~~~~~~~~~~~~~~~~~ |
| 105 | - _CRIT is based off the _INFO type. |
106 | - _CRIT is based off the _INFO type. |
| 106 | - The modification or absence of a file listed as a _CRIT-derived type |
107 | - The modification or absence of a file listed as a _CRIT-derived type |
| 107 | must be treated as an error. |
108 | MUST be treated as an error. |
| 108 | |
109 | |
| 109 | EBUILD |
110 | EBUILD |
| 110 | ~~~~~~ |
111 | ~~~~~~ |
| 111 | - Now derived from _CRIT. |
112 | - Now derived from _CRIT. |
| 112 | - Otherwise unchanged. |
113 | - Otherwise unchanged. |
| … | |
… | |
| 135 | |
136 | |
| 136 | ECLASS (new) |
137 | ECLASS (new) |
| 137 | ~~~~~~~~~~~~ |
138 | ~~~~~~~~~~~~ |
| 138 | - uses _CRIT. |
139 | - uses _CRIT. |
| 139 | - This type shall be used for all eclasses only. |
140 | - This type shall be used for all eclasses only. |
| 140 | - TODO: What about patches etc under eclasses/? Probably EXEC? |
|
|
| 141 | |
141 | |
| 142 | DATA (new) |
142 | DATA (new) |
| 143 | ~~~~~~~~~~ |
143 | ~~~~~~~~~~ |
| 144 | - uses _CRIT. |
144 | - uses _CRIT. |
| 145 | - The DATA type shall be used for all files that directly affect the |
145 | - The DATA type shall be used for all files that directly affect the |
| … | |
… | |
| 151 | - If the file gets sourced, executed, or causes a change (patches) in |
151 | - If the file gets sourced, executed, or causes a change (patches) in |
| 152 | how something is sourced or execututed, it belongs in the EXEC |
152 | how something is sourced or execututed, it belongs in the EXEC |
| 153 | filetype. |
153 | filetype. |
| 154 | - This filetype should be used for the scripts directories of a |
154 | - This filetype should be used for the scripts directories of a |
| 155 | repository for important files. |
155 | repository for important files. |
|
|
156 | - This filetype is not limited to being used in the files/ |
|
|
157 | subdirectory. |
| 156 | |
158 | |
| 157 | UNKNOWN (new) |
159 | OTHER (new) |
| 158 | ~~~~~~~~~~~~~ |
160 | ~~~~~~~~~~~ |
| 159 | - uses _CRIT. |
161 | - uses _CRIT. |
| 160 | - All other files that are not covered by another type should be |
162 | - All other files that are not covered by another type should be |
| 161 | considered as 'UNKNOWN'. |
163 | considered as 'OTHER'. |
|
|
164 | - 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'. |
| 162 | |
168 | |
| 163 | On Bloat |
169 | On Bloat |
| 164 | -------- |
170 | -------- |
| 165 | If repeated use of a common path prefix is considered a bloat problem, a |
171 | If repeated use of a common path prefix is considered a bloat problem, a |
| 166 | Manifest file should be added inside the common directory, however this |
172 | Manifest file should be added inside the common directory, however this |
| 167 | should not be done blindly, as bloat by inodes is more significant for |
173 | should not be done blindly, as bloat by inodes is more significant for |
| 168 | the majority of use cases. |
174 | the majority of use cases. See also [#GLEP58] on size reductions of |
|
|
175 | Manifests. |
| 169 | |
176 | |
| 170 | Chosing a filetype |
177 | Chosing a filetype |
| 171 | ------------------ |
178 | ------------------ |
| 172 | 1. matches Manifest |
179 | 1. matches ``Manifest`` |
| 173 | => MANIFEST, stop. |
180 | => MANIFEST, stop. |
| 174 | 2. matches *.ebuild |
181 | 2. matches ``*.ebuild`` |
| 175 | => EBUILD, stop. |
182 | => EBUILD, stop. |
| 176 | 3. matches *.eclass |
183 | 3. matches ``*.eclass`` |
| 177 | => ECLASS, stop. |
184 | => ECLASS, stop. |
| 178 | 4. listed in SRC_URI |
185 | 4. listed in SRC_URI |
| 179 | => DIST, stop. |
186 | => DIST, stop. |
| 180 | 5. matches files/* |
187 | 5. matches ``files/*`` |
| 181 | => AUX, continue [see note]. |
188 | => AUX, continue [see note]. |
| 182 | 6. matches {*.sh,*.bashrc,*.patch,...} |
189 | 6. matches any of ``*.sh``, ``*.bashrc``, ``*.patch``, ... |
| 183 | => EXEC, stop. |
190 | => EXEC, stop. |
| 184 | 7. matches {metadata/cache/*,profiles/,package.*,use.mask*,...} |
191 | 7. matches any of ``metadata/cache/*``, ``profiles/``, ``package.*``, ``use.mask*``, ... |
| 185 | => DATA, stop. |
192 | => DATA, stop. |
| 186 | 8. matches {ChangeLog,metadata.xml,*.desc,...} |
193 | 8. matches any of ``ChangeLog``, ``metadata.xml``, ``*.desc``, ... |
| 187 | => MISC, stop. |
194 | => MISC, stop. |
| 188 | 9. not matched by any other rule |
195 | 9. not matched by any other rule |
| 189 | => UNKNOWN, stop. |
196 | => OTHER, stop. |
| 190 | |
197 | |
| 191 | The logic behind 5, 6, 7 is ensuring that every item that by it's |
198 | The logic behind 5, 6, 7 is ensuring that every item that by it's |
| 192 | presence or absense may be dangerous should always be treated strictly. |
199 | presence or absense may be dangerous should always be treated strictly. |
| 193 | (Consider epatch given a directory of patches ${FILESDIR}/${PV}/, where |
200 | (Consider epatch given a directory of patches ``${FILESDIR}/${PV}/``, |
| 194 | it blindly includes them, or alternatively, the package.mask file or a |
201 | where it blindly includes them, or alternatively, the package.mask file |
| 195 | profile being altered/missing). |
202 | or a profile being altered/missing). |
|
|
203 | |
|
|
204 | The above lists of file patterns are not intended to be exhaustive, |
|
|
205 | but merely demonstrative. |
| 196 | |
206 | |
| 197 | Note: The AUX entries should only be generated if we are generating a |
207 | Note: The AUX entries should only be generated if we are generating a |
| 198 | compatible Manifest that supports older versions of Portage. They should |
208 | compatible Manifest that supports older versions of Portage. They should |
| 199 | be generated along with the new type. |
209 | be generated along with the new type. |
| 200 | |
210 | |
| … | |
… | |
| 202 | ======================= |
212 | ======================= |
| 203 | For generation of existing package Manifests, the AUX entries must |
213 | For generation of existing package Manifests, the AUX entries must |
| 204 | continue to be present for the standard Portage deprecation cycle. |
214 | continue to be present for the standard Portage deprecation cycle. |
| 205 | The new entries may be included already in all Manifest files, as they |
215 | The new entries may be included already in all Manifest files, as they |
| 206 | will be ignored by older Portage versions. Over time, ECLASS, DATA, |
216 | will be ignored by older Portage versions. Over time, ECLASS, DATA, |
| 207 | EXEC, UNKNOWN may replace the existing AUX type. |
217 | EXEC, OTHER may replace the existing AUX type. |
| 208 | |
218 | |
| 209 | The adoption of this proposal does also affect [GLEPxx+1] as part of |
219 | The adoption of this proposal does also affect [#GLEP58] as part of |
| 210 | this GLEP series, however this GLEP was an offset of the research in |
220 | this GLEP series, however this GLEP was an offset of the research in |
| 211 | that GLEP. |
221 | that GLEP. |
| 212 | |
222 | |
| 213 | Thanks to |
223 | Thanks to |
| 214 | ========= |
224 | ========= |
Parent Directory
| 
Revision Log
| 
Patch