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

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

Parent Directory | Revision Log | View Patch Patch

Revision 1.1		Revision 1.5
1	GLEP: 33	1	GLEP: 33
2	Title: Eclass Restructure/Redesign	2	Title: Eclass Restructure/Redesign
3	Version: $Revision: 1.1 $	3	Version: $Revision: 1.5 $
4	Last-Modified: $Date: 2005/02/16 21:30:44 $	4	Last-Modified: $Date: 2005/09/15 21:02:11 $
5	Author: John Mylchreest <johnm@gentoo.org>, Brian Harring <ferringb@gentoo.org>	5	Author: Brian Harring <ferringb@gentoo.org>, John Mylchreest <johnm@gentoo.org>
6	Status: Draft	6	Status: Approved
7	Type: Standards Track	7	Type: Standards Track
8	Content-Type: text/x-rst	8	Content-Type: text/x-rst
9	Created: 29-Jan-2005	9	Created: 29-Jan-2005
10	Post-History: 29-Jan-2005	10	Post-History: 29-Jan-2005 6-Mar-2005 15-Sep-2005
11		11
		12	Status
		13	======
		14
		15	Approved by the Gentoo Council on 15 September 2005.
12		16
13	Abstract	17	Abstract
14	========	18	========
15		19
16	For any design, the transition from theoretical to applied exposes inadequacies	20	For any design, the transition from theoretical to applied exposes inadequacies
17	in the original design. This document is intended to document, and propose a	21	in the original design. This document is intended to document, and propose a
18	revision of the current eclass setup to address current eclass inadequacies.	22	revision of the current eclass setup to address current eclass inadequacies.
19		23
20	This document proposes several thing- the creation of ebuild libraries, 'elibs',	24	This document proposes several things- the creation of ebuild libraries, 'elibs',
21	a narrowing of the focus of eclasses, a move of eclasses w/in the tree, the	25	a narrowing of the focus of eclasses, a move of eclasses w/in the tree, the
22	addition of changelogs, and a way to allow for simple eclass gpg signing.	26	addition of changelogs, and a way to allow for simple eclass gpg signing.
23	In general, a large scale restructuring of what eclasses are and how they're	27	In general, a large scale restructuring of what eclasses are and how they're
24	implemented. Essentially version two of the eclass setup.	28	implemented. Essentially version two of the eclass setup.
25		29
…		…
27	Terminology	31	Terminology
28	===========	32	===========
29		33
30	From this point on, the proposed eclass setup will be called 'new eclasses', the	34	From this point on, the proposed eclass setup will be called 'new eclasses', the
31	existing crop (as of this writing) will be referenced as 'old eclasses'. The	35	existing crop (as of this writing) will be referenced as 'old eclasses'. The
32	destinction is elaborated on within this document.	36	distinction is elaborated on within this document.
33		37
34		38
35	Motivation and Rationale	39	Motivation and Rationale
36	========================	40	========================
37		41
38	Eclasses within the tree currently are a bit of a mess- they're forced to	42	Eclasses within the tree currently are a bit of a mess- they're forced to
39	maintain backwards compatability w/ all previous functionality. In effect,	43	maintain backwards compatibility w/ all previous functionality. In effect,
40	their api is constant, and can only be added to- never changing the existing	44	their api is constant, and can only be added to- never changing the existing
41	functionality. This obviously is quite limiting, and leads to cruft accrueing in	45	functionality. This obviously is quite limiting, and leads to cruft accruing in
42	eclasses as a eclasses design is refined. This needs to be dealt with prior to	46	eclasses as a eclasses design is refined. This needs to be dealt with prior to
43	eclass code reaching a critical mass where they become unmanagable/fragile	47	eclass code reaching a critical mass where they become unmanageable/fragile
44	(recent pushes for eclass versioning could be interpretted as proof of this).	48	(recent pushes for eclass versioning could be interpreted as proof of this).
45		49
46	Beyond that, eclasses were originally intended as a method to allow for ebuilds	50	Beyond that, eclasses were originally intended as a method to allow for ebuilds
47	to use a pre-existing block of code, rather then having to duplicate the code in	51	to use a pre-existing block of code, rather then having to duplicate the code in
48	each ebuild. This is a good thing, but there are ill effects that result from	52	each ebuild. This is a good thing, but there are ill effects that result from
49	the current design. Eclasses inherit other eclasses to get a single function- in	53	the current design. Eclasses inherit other eclasses to get a single function- in
50	doing so, modifying the the exported 'template' (default src_compile, default	54	doing so, modifying the the exported 'template' (default src_compile, default
51	src_unpack, various vars, etc). All the eclass designer was after was reusing a	55	src_unpack, various vars, etc). All the eclass designer was after was reusing a
52	function, not making their eclass sensitive to changes in the template of the	56	function, not making their eclass sensitive to changes in the template of the
53	eclass it's inheriting. The eclass designer -should- be aware of changes in the	57	eclass it's inheriting. The eclass designer -should- be aware of changes in the
54	function they're using, but shouldn't have to worry about their default src_*	58	function they're using, but shouldn't have to worry about their default src_*
55	and pkg_* functions being overwritten, let alone the env changes.	59	and pkg_* functions being overwritten, let alone the env changes.
56		60
…		…
61	rather then requiring them to be aware of what phase of eclass changes is in	65	rather then requiring them to be aware of what phase of eclass changes is in
62	progress.	66	progress.
63		67
64	By rolling all changes into one large change, a line is intentionally drawn in	68	By rolling all changes into one large change, a line is intentionally drawn in
65	the sand. Old eclasses allowed for this, behaved this way. New eclasses allow	69	the sand. Old eclasses allowed for this, behaved this way. New eclasses allow
66	for that, and behave this way. This should reduce misconceptions about what is	70	for that, and behave this way. This should reduce misconceptions about what is
67	allowed/possible with eclasses, thus reducing bugs that result from said	71	allowed/possible with eclasses, thus reducing bugs that result from said
68	misconceptions.	72	misconceptions.
69		73
		74	A few words on elibs- think of them as a clear definition between behavioral
		75	functionality of an eclass, and the library functionality. Eclass's modify
		76	template data, and are the basis for other ebuilds- elibs, however are just
		77	common bash functionality.
70		78
		79	Consider the majority of the portage bin/* scripts- these all are candidates for
		80	being added to the tree as elibs, as is the bulk of eutils.
		81
		82
71	Specification.	83	Specification
72	==============	84	=============
73		85
74	The various parts of this proposal are broken down into a set of changes and	86	The various parts of this proposal are broken down into a set of changes and
75	elaborations on why a proposed change is preferable. It's advisable to the	87	elaborations on why a proposed change is preferable. It's advisable to the
76	reader that this be read serially, rather then jumping around.	88	reader that this be read serially, rather then jumping around.
77		89
…		…
91	A new directory named elib should be added to the top level of the tree to serve	103	A new directory named elib should be added to the top level of the tree to serve
92	as a repository of ebuild function libraries. Rather then relying on using the	104	as a repository of ebuild function libraries. Rather then relying on using the
93	source command, an 'elib' function should be added to portage to import that	105	source command, an 'elib' function should be added to portage to import that
94	libraries functionality. The reason for the indirection via the function is	106	libraries functionality. The reason for the indirection via the function is
95	mostly related to portage internals, but it does serve as an abstraction such	107	mostly related to portage internals, but it does serve as an abstraction such
96	that (for example) zsh compatability hacks could be hidden in the elib function.	108	that (for example) zsh compatibility hacks could be hidden in the elib function.
97		109
98	Elib's will be collections of bash functions- they're not allowed to do anything	110	Elib's will be collections of bash functions- they're not allowed to do anything
99	in the global scope aside from function definition, and any -minimal-	111	in the global scope aside from function definition, and any -minimal-
100	initialization of the library that is absolutely needed. Additionally, they	112	initialization of the library that is absolutely needed. Additionally, they
101	cannot modify any ebuild functions- src_compile, src_unpack fex. Since they are	113	cannot modify any ebuild template functions- src_compile, src_unpack. Since they are
102	required to not modify the metadata keys, nor in any way affect the ebuild aside	114	required to not modify the metadata keys, nor in any way affect the ebuild aside
103	from providing functionality, they can be conditionally pulled in. They also	115	from providing functionality, they can be conditionally pulled in. They also
104	are allowed to pull in other elibs, but strictly just elibs- no eclasses, just	116	are allowed to pull in other elibs, but strictly just elibs- no eclasses, just
105	other elibs. A realworld example would be the eutils eclass.	117	other elibs. A real world example would be the eutils eclass.
106		118
107	Portage, since the elib's don't modify metadata, isn't required to track elibs	119	Portage, since the elib's don't modify metadata, isn't required to track elibs
108	as it tracks eclasses. Thus a change in an elib doesn't result in half the tree	120	as it tracks eclasses. Thus a change in an elib doesn't result in half the tree
109	forced to be regenerated/marked stale when changed (this is more of an infra	121	forced to be regenerated/marked stale when changed (this is more of an infra
110	benefit, although regen's that take too long due to eclass changes have been	122	benefit, although regen's that take too long due to eclass changes have been
111	known to cause rsync issues due to missing timestamps). The only thing portage	123	known to cause rsync issues due to missing timestamps).
112	will do for elibs, aside from provide the elib function, is track what elibs	124
113	have been loaded thus far, and load an elib only if it hasn't been loaded once	125	Elibs will not be available in the global scope of an eclass, or ebuild- nor during the
114	already. An implication of this (if it wasn't clear from the elib description)	126	depends phase (basically a phase that sources the ebuild, to get its metadata). Elib
		127	calls in the global scope will be tracked, but the elib will not be loaded till just before
		128	the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are
		129	completely incapable of modifying metadata. There is no room for confusion, late loading
		130	of elibs gives you the functionality for all phases, except for depends- depends being the
		131	only phase that is capable of specifying metadata. Second, as an added bonus, late
		132	loading reduces the amount of bash sourced for a regen- faster regens. This however is minor,
		133	and is an ancillary benefit of the first reason.
		134
		135	There are a few further restrictions with elibs--mainly, elibs to load can only be specified
		136	in either global scope, or in the setup, unpack, compile, test, and install phases. You can
		137	not load elibs in prerm, postrm, preinst, and postinst. The reason being, for \*rm phases,
		138	installed pkgs will have to look to the tree for the elib, which allows for api drift to cause
		139	breakage. For \*inst phases, same thing, except the culprit is binpkgs.
		140
115	is that elibs cannot change their exported api dependant on the api (as some	141	There is a final restriction--elibs cannot change their exported api dependent on the api
116	eclass do for example).	142	(as some eclass do for example). The reason mainly being that elibs are loaded once--not
		143	multiple times, as eclasses are.
		144
		145	To clarify, for example this is invalid.
		146	::
		147
		148	if [[ -n ${SOME_VAR} ]]; then
		149	func x() { echo "I'm accessible only via tweaking some var";}
		150	else
		151	func x() { echo "this is invalid, do not do it."; }
		152	fi
		153
117		154
118	Regarding maintainability of elibs, it should be a less of a load then old	155	Regarding maintainability of elibs, it should be a less of a load then old
119	eclasses. One of the major issues with old eclasses is that their functions are	156	eclasses. One of the major issues with old eclasses is that their functions are
120	quite incestuous- they're bound tightly to the env they're defined in. This	157	quite incestuous- they're bound tightly to the env they're defined in. This
121	makes eclass functions a bit fragile- the restrictions on what can, and cannot	158	makes eclass functions a bit fragile- the restrictions on what can, and cannot
122	be done in elibs will address this, making functionality less fragile (thus a	159	be done in elibs will address this, making functionality less fragile (thus a
123	bit more maintainable).	160	bit more maintainable).
124		161
125	There is no need for backwards compatability with elibs- they just must work	162	There is no need for backwards compatibility with elibs- they just must work
126	against the current tree. Thus elibs can be removed when the tree no longer	163	against the current tree. Thus elibs can be removed when the tree no longer
127	needs them. The reasons for this are explained below.	164	needs them. The reasons for this are explained below.
128		165
129	Structuring of the elibs directory will be exactly the same as that of the new	166	Structuring of the elibs directory will be exactly the same as that of the new
130	eclass directory (detailed below), sans a different extension.	167	eclass directory (detailed below), sans a different extension.
131		168
		169	As to why their are so many restrictions, the answer is simple- the definition of
		170	what elibs are, what they are capable of, and how to use them is nailed down as much as
		171	possible to avoid any ambiguity related to them. The intention is to make it clear,
		172	such that no misconceptions occur, resulting in bugs.
132		173
133	The reduced role of Eclasses, and a clarification of existing Eclass requirements	174	The reduced role of Eclasses, and a clarification of existing Eclass requirements
134	---------------------------------------------------------------------------------	175	---------------------------------------------------------------------------------
135		176
136	Since elibs are now intended on holding common bash functionality, the focus of	177	Since elibs are now intended on holding common bash functionality, the focus of
137	eclasses should be in defining an appropriate template for ebuilds. For example,	178	eclasses should be in defining an appropriate template for ebuilds. For example,
138	defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc.	179	defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc.
139	Additionally, eclasses should pull in any elibs they need for functionality.	180	Additionally, eclasses should pull in any elibs they need for functionality.
140		181
141	Eclass functionality that isn't directly related to the metadata, or src_* and	182	Eclass functionality that isn't directly related to the metadata, or src_* and
142	pkg_* funcs should be shifted into elibs to allow for maximal code reuse. This	183	pkg_* funcs should be shifted into elibs to allow for maximal code reuse. This
…		…
151	metadata keys exported from an ebuild on system A, must be exactly the same as	192	metadata keys exported from an ebuild on system A, must be exactly the same as
152	the keys exported on system B.	193	the keys exported on system B.
153		194
154	If an eclass (or ebuild for that matter) violates this constant requirement, it	195	If an eclass (or ebuild for that matter) violates this constant requirement, it
155	leads to portage doing the wrong thing for rsync users- for example, wrong deps	196	leads to portage doing the wrong thing for rsync users- for example, wrong deps
156	pulled in, leading to compilation failure.	197	pulled in, leading to compilation failure, or dud deps.
157		198
158	If the existing metadata isn't flexible enough for what is required for a	199	If the existing metadata isn't flexible enough for what is required for a
159	package, the parsing of the metadata is changed to address that. Cases where	200	package, the parsing of the metadata is changed to address that. Cases where
160	the constant requirement is violated are known, and a select few are allowed-	201	the constant requirement is violated are known, and a select few are allowed-
161	these are exceptions to the rule that are required due to inadequacies in	202	these are exceptions to the rule that are required due to inadequacies in
162	portage. In other words, those few exceptions are allowed because it's the	203	portage. Any case where it's determined the constant requirement may need to be
163	only way to do it at this time. Any case where it's determined the constant	204	violated the dev must make it aware to the majority of devs, along with the portage
164	requirement may need to be violated the dev must make it aware to the majority	205	devs. This should be done prior to committing.
165	of devs, and the portage devs- violation of the constant rule has far reaching
166	effects.
167		206
168	It's quite likely there is a way to allow what you're attempting- if you just go	207	It's quite likely there is a way to allow what you're attempting- if you just go
169	and do it, the rsync users (our userbase) suffer the results of compilation	208	and do it, the rsync users (our user base) suffer the results of compilation
170	failures and unneeded deps being pulled in.	209	failures and unneeded deps being pulled in.
171		210
172	After that stern reminder, back to new eclasses. Defining INHERITED and ECLASS	211	After that stern reminder, back to new eclasses. Defining INHERITED and ECLASS
173	within the eclass is no longer required. Portage already handles those vars if	212	within the eclass is no longer required. Portage already handles those vars if
174	they aren't defined.	213	they aren't defined.
175		214
176	As with elibs, it's no longer required backwards compatability be maintained	215	As with elibs, it's no longer required that backwards compatibility be maintained
177	indefinitely- compatability must be maintained against the current tree, but	216	indefinitely- compatibility must be maintained against the current tree, but
178	just that. As such new eclasses (the true distinction of new vs old is	217	just that. As such new eclasses (the true distinction of new vs old is
179	elaborated in the next section) can be removed from the tree once they're no	218	elaborated in the next section) can be removed from the tree once they're no
180	longer in use.	219	longer in use.
181		220
182		221
183	The end of backwards compatability...	222	The end of backwards compatibility...
184	-------------------------------------	223	-------------------------------------
185		224
186	With current eclasses, once the eclass is in use, it's api can no longer be	225	With current eclasses, once the eclass is in use, its api can no longer be
187	changed, nor can the eclass ever be removed from the tree. This is why we still	226	changed, nor can the eclass ever be removed from the tree. This is why we still
188	have ancient eclasses that are completely unused sitting in the tree, for	227	have ancient eclasses that are completely unused sitting in the tree, for
189	example inherit.eclass . The reason for this, not surprisingly is a portage	228	example inherit.eclass. The reason for this, not surprisingly, is a portage
190	deficiency- on unmerging an installed ebuild, portage used the eclass from the	229	deficiency: on unmerging an installed ebuild, portage used the eclass from the
191	current tree.	230	current tree.
192		231
193	For a real world example of this, if you merged a glibc 2 years back, whatever	232	For a real world example of this, if you merged a glibc 2 years back, whatever
194	eclasses it used must still be compatible, or you may not be able to unmerge the	233	eclasses it used must still be compatible, or you may not be able to unmerge the
195	older glibc version during an upgrade to a newer version. So either the glibc	234	older glibc version during an upgrade to a newer version. So either the glibc
196	maintainer is left with the option of leaving people using ancient versions out	235	maintainer is left with the option of leaving people using ancient versions out
197	in the rain, or maintaining an ever increasing load of backwards compatability	236	in the rain, or maintaining an ever increasing load of backwards compatibility
198	cruft in any used eclasses.	237	cruft in any used eclasses.
199		238
200	Binpkgs suffer a similar fate. Merging of a binpkg pulls needed eclasses from	239	Binpkgs suffer a similar fate. Merging of a binpkg pulls needed eclasses from
201	the tree, so you may not be able to even merge a binpkg if the eclasses api has	240	the tree, so you may not be able to even merge a binpkg if the eclasses api has
202	changed. If the eclass was removed, you can't even merge the binpkg, period.	241	changed. If the eclass was removed, you can't even merge the binpkg, period.
…		…
205	ebuild was built in already contains the eclasses functions, as such the env can	244	ebuild was built in already contains the eclasses functions, as such the env can
206	be re-used rather then relying on the eclass. In other words, binpkgs and	245	be re-used rather then relying on the eclass. In other words, binpkgs and
207	installed ebuilds will no longer go and pull needed eclasses from the tree,	246	installed ebuilds will no longer go and pull needed eclasses from the tree,
208	they'll use the 'saved' version of the eclass they were built/merged with.	247	they'll use the 'saved' version of the eclass they were built/merged with.
209		248
210	So the backwards compatability requirement for users of the next major portage	249	So the backwards compatibility requirement for users of the next major portage
211	version (and beyond) isn't required. All the cruft can be dropped.	250	version (and beyond) isn't required. All the cruft can be dropped.
212		251
213	The problem is that there will be users using older versions of portage that	252	The problem is that there will be users using older versions of portage that don't
214	don't support this functionality. So backwards compatability must be maintained	253	support this functionality- these older installations cannot use the
215	for them. Additionally, earlier versions of portage haven't always handled the	254	new eclasses, due to the fact that their portage version is incapable of
216	env correctly- for broken saved envs, the eclasses backwards compatability is	255	properly relying on the env- in other words, the varying api of the eclass will
217	still required. Waiting N months preserving backwards compatability in current	256	result in user-visible failures during unmerging.
218	eclasses, then dropping the support isn't much of an option. There always are
219	stragglers who don't upgrade, beyond that, there is the possibility of cases
220	where users -will- upgrade, but still be bitten (broken saved envs from earlier
221	portage installations). More importantly, it doesn't provide a route to
222	upgrade/fix things if a user lags behind, exempting trying to find a compatabile
223	version of the eclass in viewcvs (assuming it hasn't been sent to the attic
224	already). Obviously, that isn't acceptable.
225		257
226	With the next major portage release, it will be possible to drop backwards	258	So we're able to do a clean break of all old eclasses, and api cruft, but we need
227	compatability for eclasses, and all lingering cruft. What is needed is a way to	259	a means to basically disallow access to the new eclasses for all portage versions
228	take full advantage of this functionality, without completely screwing over the	260	incapable of properly handling the env requirements.
229	unfortunates and those who don't upgrade.
230		261
231	Unfortunately, the creation of new eclasses within the tree has an additional	262	Unfortunately, we cannot just rely on a different grouping/naming convention within
232	snag due to portage. The existing inherit function that is used to pull in old	263	the old eclass directory. The new eclasses must be inaccessible, and portage throws
		264	a snag into this- the existing inherit function that is used to handle existing
233	eclasses- basically, whatever it's passed (inherit kernel or inherit	265	eclasses. Basically, whatever it's passed (inherit kernel or inherit
234	kernel/kernel) it will pull in (kernel.eclass, and kernel/kernel.eclass	266	kernel/kernel) it will pull in (kernel.eclass, and kernel/kernel.eclass
235	respectively). So even if the new eclasses were implemented within a	267	respectively). So even if the new eclasses were implemented within a
236	subdirectory of the eclass dir in the tree, all current portage versions would	268	subdirectory of the eclass dir in the tree, all current portage versions would
237	still be able to access them.	269	still be able to access them.
238		270
239	In other words, these new eclasses would in effect, be old eclasses since older	271	In other words, these new eclasses would in effect, be old eclasses since older
240	portage versions could still access them.	272	portage versions could still access them.
241		273
242		274
243	Tree restructuring.	275	Tree restructuring
244	-------------------	276	------------------
245		277
246	There are only two way to block the existing (as of this writing) inherit	278	There are only two way to block the existing (as of this writing) inherit
247	functionality from accessing the new eclasses- either change the extension of	279	functionality from accessing the new eclasses- either change the extension of
248	eclasses to something other then 'eclass', or to have them stored in a seperate	280	eclasses to something other then 'eclass', or to have them stored in a separate
249	subdirectory of the tree then eclass.	281	subdirectory of the tree then eclass.
250		282
251	The latter is preferable, and the proposed solution. Reasons are- the current	283	The latter is preferable, and the proposed solution. Reasons are- the current
252	eclass directory is already overgrown. Structuring of the new eclass dir	284	eclass directory is already overgrown. Structuring of the new eclass dir
253	(clarified below) will allow for easier signing, ChangeLogs, and grouping of	285	(clarified below) will allow for easier signing, ChangeLogs, and grouping of
…		…
257		289
258	If it's unclear as to why the old inherit function cannot access the new	290	If it's unclear as to why the old inherit function cannot access the new
259	eclasses, please reread the previous section. It's unfortunately a requirement	291	eclasses, please reread the previous section. It's unfortunately a requirement
260	to take advantage of all that the next major portage release will allow.	292	to take advantage of all that the next major portage release will allow.
261		293
262	The proposed directory sructure is ${PORTDIR}/include/{eclass,elib}.	294	The proposed directory structure is ${PORTDIR}/include/{eclass,elib}.
263	Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used	295	Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used
264	(although many would cringe at the -ng), but such a name is unwise. Consider the	296	(although many would cringe at the -ng), but such a name is unwise. Consider the
265	possibility (likely a fact) that new eclasses someday may be found lacking, and	297	possibility (likely a fact) that new eclasses someday may be found lacking, and
266	refined further (version three as it were). Or perhaps we want to add yet more	298	refined further (version three as it were). Or perhaps we want to add yet more
267	functionality with direct relation to sourcing new files, and we would then need	299	functionality with direct relation to sourcing new files, and we would then need
268	to further populate ${PORTDIR}.	300	to further populate ${PORTDIR}.
269		301
270	The new-eclass directory will be (at least) 2 levels deep- for example:	302	The new-eclass directory will be (at least) 2 levels deep- for example:
271		303
…		…
280		312
281	No eclasses will be allowed in the base directory- grouping of new eclasses will	313	No eclasses will be allowed in the base directory- grouping of new eclasses will
282	be required to help keep things tidy, and for the following reasons. Grouping	314	be required to help keep things tidy, and for the following reasons. Grouping
283	of eclasses allows for the addition of ChangeLogs that are specific to that	315	of eclasses allows for the addition of ChangeLogs that are specific to that
284	group of eclasses, grouping of files/patches as needed, and allows for	316	group of eclasses, grouping of files/patches as needed, and allows for
285	saner/easier signing of eclasses- basically, you can just stick a signed	317	saner/easier signing of eclasses- you can just stick a signed
286	Manifest file w/in that grouping, thus providing the information portage needs	318	Manifest file w/in that grouping, thus providing the information portage needs
287	to ensure no files are missing, and that nothing has been tainted.	319	to ensure no files are missing, and that nothing has been tainted.
288		320
289	The elib directory will be structured in the same way, for the same reasons.	321	The elib directory will be structured in the same way, for the same reasons.
290		322
291	Repoman will have to be extended to work within new eclass and elib groups, and	323	Repoman will have to be extended to work within new eclass and elib groups, and
292	to handle signing and commiting. This is intentional, and a good thing. This	324	to handle signing and committing. This is intentional, and a good thing. This
293	gives repoman the possibility of doing sanity checks on elibs/new eclasses.	325	gives repoman the possibility of doing sanity checks on elibs/new eclasses.
294	It won't solve developers doing dumb things with eclasses (no technological
295	solution would, exempting a tazering), but it will give us a way to automate
296	checks to try and prevent honest mistakes from slipping through and breaking
297	things for our users.
298		326
		327	Note these checks will not prevent developers from doing dumb things with eclass-
		328	these checks would only be capable of doing basic sanity checks, such as syntax checks.
		329	There is no way to prevent people from doing dumb things (exempting perhaps repeated
		330	applications of a cattle prod)- these are strictly automatic checks, akin to repoman's
		331	dependency checks.
299		332
		333
300	The start of a different phase of backwards compatability	334	The start of a different phase of backwards compatibility
301	---------------------------------------------------------	335	---------------------------------------------------------
302		336
303	As clarified above, new eclasses will exist in a seperate directory that will be	337	As clarified above, new eclasses will exist in a separate directory that will be
304	intentionally inaccessible to the inherit function. As such, users of older	338	intentionally inaccessible to the inherit function. As such, users of older
305	portage versions will have to upgrade to merge any ebuild that uses elibs/new	339	portage versions will have to upgrade to merge any ebuild that uses elibs/new
306	eclasses. A depend on the next major portage version would address	340	eclasses. A depend on the next major portage version would transparently handle
307	transparently handle this for rsync users.	341	this for rsync users.
308		342
309	There still is the issue of users who haven't upgraded to the required portage	343	There still is the issue of users who haven't upgraded to the required portage
310	version. This is a minor concern frankly- portage releases include new	344	version. This is a minor concern frankly- portage releases include new
311	functionality, and bug fixes. If they won't upgrade, it's assumed they have	345	functionality, and bug fixes. If they won't upgrade, it's assumed they have
312	their reasons and are big boys, thus able to handle the complications themselves.	346	their reasons and are big boys, thus able to handle the complications themselves.
313		347
314	The real issue is broken envs, whether in binpkgs, or for installed packages.	348	The real issue is broken envs, whether in binpkgs, or for installed packages.
315	Two options exist- either the old eclasses are left in the tree indefinitely, or	349	Two options exist- either the old eclasses are left in the tree indefinitely, or
…		…
329		363
330	For users who do not upgrade within the window of N months while the old	364	For users who do not upgrade within the window of N months while the old
331	eclasses are in the tree, as stated, it's assumed they know what they are doing.	365	eclasses are in the tree, as stated, it's assumed they know what they are doing.
332	If they specifically block the new portage version, as the ebuilds in the tree	366	If they specifically block the new portage version, as the ebuilds in the tree
333	migrate to the new eclasses, they will have less and less ebuilds available to	367	migrate to the new eclasses, they will have less and less ebuilds available to
334	them. If they tried injecting the new portage version (lieing to portage,	368	them. If they tried injecting the new portage version (lying to portage,
335	essentially), portage would bail since it cannot find the new eclass. Note that	369	essentially), portage would bail since it cannot find the new eclass.
336	for them to even get to this point, they'd have to somehow disable the DEPEND on	370	For ebuilds that use the new eclasses, there really isn't any way to sidestep
337	a new version of portage- either hack up the ebuild, or do an injection.	371	the portage version requirement- same as it has been for other portage features.
338	Essentially they'd have to actively try to sidestep sanity checks implemented to
339	make the shift over from old to new transparent. If they've
340	disabled/sidestepped our attempt at a transparent migration, they can deal with
341	the repercussions of it.
342		372
343	What is a bit more annoying is that once the old eclasses are out of the tree,	373	What is a bit more annoying is that once the old eclasses are out of the tree,
		374	if a user has not upgraded to a portage version supporting env processing, they
344	users will lose the ability to unmerge any installed ebuild that used an old	375	will lose the ability to unmerge any installed ebuild that used an old
345	eclass, further users will lose the ability to merge any tbz2 that uses old	376	eclass. Same cause, different symptom being they will lose the ability to merge
346	eclasses.	377	any tbz2 that uses old eclasses also.
347		378
348	They however will not be left out in the rain. For merging old eclass	379	There is one additional case that is a rarity, but should be noted- if a user
349	binpkgs, and unmerging installed packages, they can merge the old eclass compat	380	has suffered significant corruption of their installed package database (vdb). This is
350	ebuild. The compat ebuild provides the missing eclasses, thus providing that	381	ignoring the question of whether the vdb is even usable at this point, but the possibility
351	lost functionality.	382	exists for the saved envs to be non usable due to either A) missing, or B) corrupted.
		383	In such a case, even with the new portage capabilities, they would need
		384	the old eclass compat ebuild.
352		385
		386	Note for this to happen requires either rather... unwise uses of root, or significant
		387	fs corruption. Regardless of the cause, it's quite likely for this to even become an
		388	issue, the system's vdb is completely unusable. It's a moot issue at that point.
		389	If you lose your vdb, or it gets seriously damaged, it's akin to lobotomizing portage-
		390	it doesn't know what's installed, it doesn't know of its own files, and in general,
		391	a rebuilding of the system is about the only sane course of action. The missing env is
		392	truly the least of the users concern in such a case.
		393
		394	Continuing with the more likely scenario, users unwilling to upgrade portage will
		395	not be left out in the rain. Merging the old eclass compat ebuild will provide
		396	the missing eclasses, thus providing that lost functionality.
		397
353	The intention isn't to force them to upgrade, hence the ability to restore the	398	Note the intention isn't to force them to upgrade, hence the ability to restore the
354	lost functionality. The intention is to clean up the existing mess, and allow us	399	lost functionality. The intention is to clean up the existing mess, and allow us
355	to move forward. The saying "you've got to break a few eggs to make an omelete"	400	to move forward. The saying "you've got to break a few eggs to make an omelet"
356	is akin, exempting the fact we're providing a way to make the eggs whole again	401	is akin, exempting the fact we're providing a way to make the eggs whole again
357	(the king's men would've loved such an option).	402	(the king's men would've loved such an option).
358
359	It's advisable that once all old eclasses are no longer in use in the tree, the
360	old eclass package is added to system default. Remember that even those who
361	have upgraded to a portage version that handles the env correctly, may run into
362	instances where an installed packages env is corrupt. For new bootstraps (which
363	automatically upgrade portage right off the bat), an injection of the compat
364	package would be advisable- unless they downgrade portage, they will never need
365	the old eclasses.
366		403
367		404
368	Migrating to the new setup	405	Migrating to the new setup
369	--------------------------	406	--------------------------
370		407
…		…
384	infrastructure server that generates the cache for rsync users will have to	421	infrastructure server that generates the cache for rsync users will have to
385	either be upgraded to a version of portage supporting new eclasses, or patched.	422	either be upgraded to a version of portage supporting new eclasses, or patched.
386	The former being much more preferable then the latter for the portage devs.	423	The former being much more preferable then the latter for the portage devs.
387		424
388	Beyond that, an appropriate window for old eclasses to exist in the tree must be	425	Beyond that, an appropriate window for old eclasses to exist in the tree must be
389	determined, and prior to that window passing an ebuild must be added to the tree	426	determined, and prior to that window passing, an ebuild must be added to the tree
390	so users can get the old eclasses if needed.	427	so users can get the old eclasses if needed.
391		428
392	For eclass devs to migrate from old to new, it is possible for them to just	429	For eclass devs to migrate from old to new, it is possible for them to just
393	transfer the old eclass into an appropriate grouping in the new eclass directory,	430	transfer the old eclass into an appropriate grouping in the new eclass directory,
394	although it's advisable they cleanse all cruft out of the eclass. You can	431	although it's advisable they cleanse all cruft out of the eclass. You can
395	migrate ebuilds gradually over to the new eclass, and don't have to worry about	432	migrate ebuilds gradually over to the new eclass, and don't have to worry about
396	having to support ebuilds from X years back.	433	having to support ebuilds from X years back.
397		434
398	Essentially, you have a chance to nail the design perfectly/cleanly, and have a	435	Essentially, you have a chance to nail the design perfectly/cleanly, and have a
399	window in which to redesign it. It's humbly suggested eclass devs take	436	window in which to redesign it. It's humbly suggested eclass devs take
…		…
401		438
402		439
403	Backwards Compatibility	440	Backwards Compatibility
404	=======================	441	=======================
405		442
406	All backwards compatability issues are addressed inline, but a recap is offered-	443	All backwards compatibility issues are addressed in line, but a recap is offered-
407	it's suggested that if the a particular compatability issue is	444	it's suggested that if the a particular compatibility issue is
408	questioned/worried over, the reader read the relevant section. There should be	445	questioned/worried over, the reader read the relevant section. There should be
409	a more in depth discussion of the issue, along with a more extensive explanation	446	a more in depth discussion of the issue, along with a more extensive explanation
410	of the potential solutions, and reasons for the choosen solution.	447	of the potential solutions, and reasons for the chosen solution.
411		448
412	To recap:	449	To recap:
413	::	450	::
414		451
415	New eclasses and elib functionality will be tied to a specific portage	452	New eclasses and elib functionality will be tied to a specific portage
416	version. A DEPENDs on said portage version should address this for rsync	453	version. A DEPENDs on said portage version should address this for rsync
417	users who refuse to upgrade to a portage version that supports the new	454	users who refuse to upgrade to a portage version that supports the new
418	eclasses/elibs and will gradually be unable to merge ebuilds that use said	455	eclasses/elibs and will gradually be unable to merge ebuilds that use said
419	functionality. It is their choice to upgrade, as such, the gradual	456	functionality. It is their choice to upgrade, as such, the gradual
420	'thinning' of available ebuilds should they block the portage upgrade is	457	'thinning' of available ebuilds should they block the portage upgrade is
421	their responsibility.	458	their responsibility.
422		459
423	Old eclasses at some point in the future should be removed from the tree,	460	Old eclasses at some point in the future should be removed from the tree,
424	and released in a tarball/ebuild. This will cause installed ebuilds that	461	and released in a tarball/ebuild. This will cause installed ebuilds that
425	rely on the old eclass to be unable to unmerge to behave as expected, with	462	rely on the old eclass to be unable to unmerge, with the same applying for
426	the same applying for merging of binpkgs.	463	merging of binpkgs dependent on the following paragraph.
427		464
428	This eclass ebuild should be a system depends target to make the transition	465	The old eclass-compat is only required for users who do not upgrade their
429	transparent. Future portage ebuilds, and the old eclass compat ebuild should	466	portage installation, and one further exemption- if the user has somehow
430	not inherit any eclasses. The reason for this is that in doing so, it may	467	corrupted/destroyed their installed pkgs database (/var/db/pkg currently),
431	block upgrade paths. At least for portage, this already is something of a	468	in the process, they've lost their saved environments. The eclass-compat
432	known issue for ebuild functionality- due to what it is/provides, it must	469	ebuild would be required for ebuilds that required older eclasses in such a
433	essentially be standalone, and cannot benefit from any eclass/elib	470	case. Note, this case is rare also- as clarified above, it's mentioned
434	functionality.	471	strictly to be complete, it's not much of a real world scenario as elaborated
		472	above.
435		473
436		474
437	Copyright	475	Copyright
438	=========	476	=========
439		477

 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.5
 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.5
-Removed from v.1.1
+Added in v.1.5

	ViewVC Help
Powered by ViewVC 1.1.13