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

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

Parent Directory | Revision Log | View Patch Patch

Revision 1.3		Revision 1.9
1	GLEP: 60	1	GLEP: 60
2	Title: Manifest2 filetypes	2	Title: Manifest2 filetypes
3	Version: $Revision: 1.3 $	3	Version: $Revision: 1.9 $
4	Last-Modified: $Date: 2008/10/28 07:46:51 $	4	Last-Modified: $Date: 2010/01/31 09:55:43 $
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, October 2008	11	Updated: June 2008, July 2008, October 2008, January 2010
12	Updates: 44	12	Updates: 44
13	Post-History:	13	Post-History: December 2009, January 2010
14		14
15	Abstract	15	Abstract
16	========	16	========
17	Clarification of the Manifest2 [#GLEP44] specification, including new types to	17	Clarification of the Manifest2 [#GLEP44] specification, including new types to
18	help in the tree-signing specification.	18	help 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.
23	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
24	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
25	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.
		26
		27	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	the tree (e.g. a user excluding a package or category). As such, it is
		31	also able to stand on it's own.
26		32
27	Specification	33	Specification
28	=============	34	=============
29	General	35	General
30	-------	36	-------
…		…
33	unless stated otherwise in the following sections. The Manifest file	39	unless stated otherwise in the following sections. The Manifest file
34	must not contain an entry for itself.	40	must not contain an entry for itself.
35		41
36	Excluded files	42	Excluded files
37	--------------	43	--------------
38	When generating or validating a Manifest, or commiting to a version	44	When generating or validating a Manifest, or committing to a version
39	control system, the package manager should endeavour to ignore files	45	control system, the package manager should endeavour to ignore files
40	created by a version control system, backup files from text editors. A	46	created by a version control system, backup files from text editors. A
41	non-exhaustive list is suggested here: ``CVS/``, ``.svn/``, ``.bzr/``,	47	non-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
110	EBUILD	116	EBUILD
111	~~~~~~	117	~~~~~~
112	- Now derived from _CRIT.	118	- Now derived from _CRIT.
113	- Otherwise unchanged.	119	- Otherwise unchanged.
…		…
125	MANIFEST (new)	131	MANIFEST (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
137	ECLASS (new)	143	ECLASS (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
143	DATA (new)	148	DATA (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
149	EXEC (new)	154	EXEC (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
158	UNKNOWN (new)	165	OTHER (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 'UNKNOWN'.	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
164	On Bloat	175	On Bloat
165	--------	176	--------
166	If repeated use of a common path prefix is considered a bloat problem, a	177	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	178	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	179	should not be done blindly, as bloat by inodes is more significant for
169	the majority of use cases.	180	the majority of use cases. See also [#GLEP58] on size reductions of
		181	Manifests.
170		182
171	Chosing a filetype	183	Chosing a filetype
172	------------------	184	------------------
173	1. matches Manifest	185	1. matches ``Manifest``
174	=> MANIFEST, stop.	186	=> MANIFEST, stop.
175	2. matches ``*.ebuild``	187	2. matches ``*.ebuild``
176	=> EBUILD, stop.	188	=> EBUILD, stop.
177	3. matches ``*.eclass``	189	3. matches ``*.eclass``
178	=> ECLASS, stop.	190	=> ECLASS, stop.
…		…
185	7. matches any of ``metadata/cache/``, ``profiles/``, ``package.``, ``use.mask*``, ...	197	7. matches any of ``metadata/cache/``, ``profiles/``, ``package.``, ``use.mask*``, ...
186	=> DATA, stop.	198	=> DATA, stop.
187	8. matches any of ``ChangeLog``, ``metadata.xml``, ``*.desc``, ...	199	8. matches any of ``ChangeLog``, ``metadata.xml``, ``*.desc``, ...
188	=> MISC, stop.	200	=> MISC, stop.
189	9. not matched by any other rule	201	9. not matched by any other rule
190	=> UNKNOWN, stop.	202	=> OTHER, stop.
191		203
192	The logic behind 5, 6, 7 is ensuring that every item that by it's	204	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.	205	presence 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}/``,
195	where it blindly includes them, or alternatively, the package.mask file	207	where it blindly includes them, or alternatively, the package.mask file
196	or a profile being altered/missing).	208	or a profile being altered/missing).
		209
		210	The above lists of file patterns are not intended to be exhaustive,
		211	but merely demonstrative.
197		212
198	Note: The AUX entries should only be generated if we are generating a	213	Note: The AUX entries should only be generated if we are generating a
199	compatible Manifest that supports older versions of Portage. They should	214	compatible Manifest that supports older versions of Portage. They should
200	be generated along with the new type.	215	be generated along with the new type.
201		216
…		…
203	=======================	218	=======================
204	For generation of existing package Manifests, the AUX entries must	219	For generation of existing package Manifests, the AUX entries must
205	continue to be present for the standard Portage deprecation cycle.	220	continue to be present for the standard Portage deprecation cycle.
206	The new entries may be included already in all Manifest files, as they	221	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,	222	will be ignored by older Portage versions. Over time, ECLASS, DATA,
208	EXEC, UNKNOWN may replace the existing AUX type.	223	EXEC, OTHER may replace the existing AUX type.
209		224
210	The adoption of this proposal does also affect [#GLEP58] as part of	225	The adoption of this proposal does also affect [#GLEP58] as part of
211	this GLEP series, however this GLEP was an offset of the research in	226	this GLEP series, however this GLEP was an offset of the research in
212	that GLEP.	227	that GLEP.
213		228
…		…
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
224	Copyright	239	Copyright
225	=========	240	=========
226	Copyright (c) 2007 by Robin Hugh Johnson. This material may be	241	Copyright (c) 2007-2010 by Robin Hugh Johnson. This material may be
227	distributed only subject to the terms and conditions set forth in the	242	distributed only subject to the terms and conditions set forth in the
228	Open Publication License, v1.0.	243	Open Publication License, v1.0.
229		244
230	vim: tw=72 ts=2 expandtab:	245	vim: tw=72 ts=2 expandtab:

 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.9
 Legend:



Removed from v.1.3
 


changed lines


 
Added in v.1.9
-Removed from v.1.3
+Added in v.1.9

	ViewVC Help
Powered by ViewVC 1.1.13