/[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.4 Revision 1.9
1GLEP: 60 1GLEP: 60
2Title: Manifest2 filetypes 2Title: Manifest2 filetypes
3Version: $Revision: 1.4 $ 3Version: $Revision: 1.9 $
4Last-Modified: $Date: 2010/01/13 00:35:49 $ 4Last-Modified: $Date: 2010/01/31 09:55:43 $
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, October 2008 11Updated: June 2008, July 2008, October 2008, January 2010
12Updates: 44 12Updates: 44
13Post-History: 13Post-History: December 2009, January 2010
14 14
15Abstract 15Abstract
16======== 16========
17Clarification of the Manifest2 [#GLEP44] specification, including new types to 17Clarification of the Manifest2 [#GLEP44] specification, including new types to
18help in the tree-signing specification. 18help in the tree-signing specification.
21========== 21==========
22[#GLEP44] was not entirely clear on the usage of filetype specifiers. 22[#GLEP44] was not entirely clear on the usage of filetype specifiers.
23This document serves to provide some of the internal logic used by 23This document serves to provide some of the internal logic used by
24Portage 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
25the 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). As such, it is
31also able to stand on it's own.
26 32
27Specification 33Specification
28============= 34=============
29General 35General
30------- 36-------
33unless stated otherwise in the following sections. The Manifest file 39unless stated otherwise in the following sections. The Manifest file
34must not contain an entry for itself. 40must not contain an entry for itself.
35 41
36Excluded files 42Excluded files
37-------------- 43--------------
38When generating or validating a Manifest, or commiting to a version 44When generating or validating a Manifest, or committing to a version
39control system, the package manager should endeavour to ignore files 45control system, the package manager should endeavour to ignore files
40created by a version control system, backup files from text editors. A 46created by a version control system, backup files from text editors. A
41non-exhaustive list is suggested here: ``CVS/``, ``.svn/``, ``.bzr/``, 47non-exhaustive list is suggested here: ``CVS/``, ``.svn/``, ``.bzr/``,
42``.git/``, ``.hg/``, ``.#*``, ``*.rej``, ``*.orig``, ``*.bak``, ``*~``. 48``.git/``, ``.hg/``, ``.#*``, ``*.rej``, ``*.orig``, ``*.bak``, ``*~``.
43 49
103 109
104_CRIT (new, abstract) 110_CRIT (new, abstract)
105~~~~~~~~~~~~~~~~~~~~~ 111~~~~~~~~~~~~~~~~~~~~~
106- _CRIT is based off the _INFO type. 112- _CRIT is based off the _INFO type.
107- The modification or absence of a file listed as a _CRIT-derived type 113- The modification or absence of a file listed as a _CRIT-derived type
108 must be treated as an error. 114 MUST be treated as an error.
109 115
110EBUILD 116EBUILD
111~~~~~~ 117~~~~~~
112- Now derived from _CRIT. 118- Now derived from _CRIT.
113- Otherwise unchanged. 119- Otherwise unchanged.
125MANIFEST (new) 131MANIFEST (new)
126~~~~~~~~~~~~~~ 132~~~~~~~~~~~~~~
127- The MANIFEST type is explicitly to cover all nested Manifest files. 133- The MANIFEST type is explicitly to cover all nested Manifest files.
128- During validation, this serves as an indicator that the package 134- During validation, this serves as an indicator that the package
129 manager may need to check subtree Manifest file. 135 manager may need to check subtree Manifest file.
130- A missing MANIFEST file may be treated as a minor (eg excluding an 136- A missing MANIFEST file may be treated as a minor (e.g. excluding an
131 entire category) or critical validation failure. 137 entire category) or critical validation failure.
132- The failure should be considered as critical only if files that would 138- The failure should be considered as critical only if files that would
133 be directly covered by this Manifest are missing. Deletion of a 139 be directly covered by this Manifest are missing. Deletion of a
134 category-level Manifest while preserving the packages is forbidden. 140 category-level Manifest while preserving the packages is forbidden.
135 Deletion of an entire category is not. 141 Deletion of an entire category is not.
136 142
137ECLASS (new) 143ECLASS (new)
138~~~~~~~~~~~~ 144~~~~~~~~~~~~
139- uses _CRIT. 145- uses _CRIT.
140- This type shall be used for all eclasses only. 146- This type shall be used for all eclasses only.
141- TODO: What about patches etc under eclasses/? Probably EXEC?
142 147
143DATA (new) 148DATA (new)
144~~~~~~~~~~ 149~~~~~~~~~~
145- uses _CRIT. 150- uses _CRIT.
146- The DATA type shall be used for all files that directly affect the 151- The DATA type shall be used for all files that directly affect the
148 153
149EXEC (new) 154EXEC (new)
150~~~~~~~~~~ 155~~~~~~~~~~
151- uses _CRIT. 156- uses _CRIT.
152- If the file gets sourced, executed, or causes a change (patches) in 157- If the file gets sourced, executed, or causes a change (patches) in
153 how something is sourced or execututed, it belongs in the EXEC 158 how something is sourced or executed, it belongs in the EXEC
154 filetype. 159 filetype.
155- This filetype should be used for the scripts directories of a 160- This filetype should be used for the scripts directories of a
156 repository for important files. 161 repository for important files.
162- This filetype is not limited to being used in the files/
163 subdirectory.
157 164
158OTHER (new) 165OTHER (new)
159~~~~~~~~~~~ 166~~~~~~~~~~~
160- uses _CRIT. 167- uses _CRIT.
161- All other files that are not covered by another type should be 168- All other files that are not covered by another type should be
162 considered as 'OTHER'. 169 considered as 'OTHER'.
170- 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'.
163 174
164On Bloat 175On Bloat
165-------- 176--------
166If repeated use of a common path prefix is considered a bloat problem, a 177If repeated use of a common path prefix is considered a bloat problem, a
167Manifest file should be added inside the common directory, however this 178Manifest file should be added inside the common directory, however this
168should not be done blindly, as bloat by inodes is more significant for 179should not be done blindly, as bloat by inodes is more significant for
169the majority of use cases. 180the majority of use cases. See also [#GLEP58] on size reductions of
181Manifests.
170 182
171Chosing a filetype 183Chosing a filetype
172------------------ 184------------------
1731. matches Manifest 1851. matches ``Manifest``
174 => MANIFEST, stop. 186 => MANIFEST, stop.
1752. matches ``*.ebuild`` 1872. matches ``*.ebuild``
176 => EBUILD, stop. 188 => EBUILD, stop.
1773. matches ``*.eclass`` 1893. matches ``*.eclass``
178 => ECLASS, stop. 190 => ECLASS, stop.
188 => MISC, stop. 200 => MISC, stop.
1899. not matched by any other rule 2019. not matched by any other rule
190 => OTHER, stop. 202 => OTHER, stop.
191 203
192The logic behind 5, 6, 7 is ensuring that every item that by it's 204The logic behind 5, 6, 7 is ensuring that every item that by it's
193presence or absense may be dangerous should always be treated strictly. 205presence or absence may be dangerous should always be treated strictly.
194(Consider epatch given a directory of patches ``${FILESDIR}/${PV}/``, 206(Consider epatch given a directory of patches ``${FILESDIR}/${PV}/``,
195where it blindly includes them, or alternatively, the package.mask file 207where it blindly includes them, or alternatively, the package.mask file
196or a profile being altered/missing). 208or a profile being altered/missing).
209
210The above lists of file patterns are not intended to be exhaustive,
211but merely demonstrative.
197 212
198Note: The AUX entries should only be generated if we are generating a 213Note: The AUX entries should only be generated if we are generating a
199compatible Manifest that supports older versions of Portage. They should 214compatible Manifest that supports older versions of Portage. They should
200be generated along with the new type. 215be generated along with the new type.
201 216
221.. [#GLEP44] Mauch, M. (2005) GLEP44 - Manifest2 format. 236.. [#GLEP44] Mauch, M. (2005) GLEP44 - Manifest2 format.
222 http://www.gentoo.org/proj/en/glep/glep-0044.html 237 http://www.gentoo.org/proj/en/glep/glep-0044.html
223 238
224Copyright 239Copyright
225========= 240=========
226Copyright (c) 2007 by Robin Hugh Johnson. This material may be 241Copyright (c) 2007-2010 by Robin Hugh Johnson. This material may be
227distributed only subject to the terms and conditions set forth in the 242distributed only subject to the terms and conditions set forth in the
228Open Publication License, v1.0. 243Open Publication License, v1.0.
229 244
230vim: tw=72 ts=2 expandtab: 245vim: tw=72 ts=2 expandtab:

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.9

  ViewVC Help
Powered by ViewVC 1.1.20