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

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

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

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

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

  ViewVC Help
Powered by ViewVC 1.1.20