/[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.3 Revision 1.5
1GLEP: 33 1GLEP: 33
2Title: Eclass Restructure/Redesign 2Title: Eclass Restructure/Redesign
3Version: $Revision: 1.3 $ 3Version: $Revision: 1.5 $
4Last-Modified: $Date: 2005/03/06 20:39:19 $ 4Last-Modified: $Date: 2005/09/15 21:02:11 $
5Author: Brian Harring <ferringb@gentoo.org>, John Mylchreest <johnm@gentoo.org> 5Author: Brian Harring <ferringb@gentoo.org>, John Mylchreest <johnm@gentoo.org>
6Status: Draft 6Status: Approved
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 6-Mar-2005 10Post-History: 29-Jan-2005 6-Mar-2005 15-Sep-2005
11 11
12Status
13======
14
15Approved by the Gentoo Council on 15 September 2005.
12 16
13Abstract 17Abstract
14======== 18========
15 19
16For any design, the transition from theoretical to applied exposes inadequacies 20For any design, the transition from theoretical to applied exposes inadequacies
36======================== 40========================
37 41
38Eclasses within the tree currently are a bit of a mess- they're forced to 42Eclasses within the tree currently are a bit of a mess- they're forced to
39maintain backwards compatibility w/ all previous functionality. In effect, 43maintain backwards compatibility w/ all previous functionality. In effect,
40their api is constant, and can only be added to- never changing the existing 44their api is constant, and can only be added to- never changing the existing
41functionality. This obviously is quite limiting, and leads to cruft accruing in 45functionality. 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 46eclasses as a eclasses design is refined. This needs to be dealt with prior to
43eclass code reaching a critical mass where they become unmanageable/fragile 47eclass code reaching a critical mass where they become unmanageable/fragile
44(recent pushes for eclass versioning could be interpreted as proof of this). 48(recent pushes for eclass versioning could be interpreted as proof of this).
45 49
46Beyond that, eclasses were originally intended as a method to allow for ebuilds 50Beyond 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 51to 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 52each 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 53the current design. Eclasses inherit other eclasses to get a single function- in
50doing so, modifying the the exported 'template' (default src_compile, default 54doing so, modifying the the exported 'template' (default src_compile, default
51src_unpack, various vars, etc). All the eclass designer was after was reusing a 55src_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 56function, 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 57eclass 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_* 58function they're using, but shouldn't have to worry about their default src_*
55and pkg_* functions being overwritten, let alone the env changes. 59and pkg_* functions being overwritten, let alone the env changes.
56 60
61rather then requiring them to be aware of what phase of eclass changes is in 65rather then requiring them to be aware of what phase of eclass changes is in
62progress. 66progress.
63 67
64By rolling all changes into one large change, a line is intentionally drawn in 68By 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 69the 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 70for that, and behave this way. This should reduce misconceptions about what is
67allowed/possible with eclasses, thus reducing bugs that result from said 71allowed/possible with eclasses, thus reducing bugs that result from said
68misconceptions. 72misconceptions.
69 73
70A few words on elibs- think of them as a clear definition between behavioral 74A few words on elibs- think of them as a clear definition between behavioral
71functionality of an eclass, and the library functionality. Eclass's modify 75functionality of an eclass, and the library functionality. Eclass's modify
74 78
75Consider the majority of the portage bin/* scripts- these all are candidates for 79Consider the majority of the portage bin/* scripts- these all are candidates for
76being added to the tree as elibs, as is the bulk of eutils. 80being added to the tree as elibs, as is the bulk of eutils.
77 81
78 82
79Specification. 83Specification
80============== 84=============
81 85
82The various parts of this proposal are broken down into a set of changes and 86The various parts of this proposal are broken down into a set of changes and
83elaborations on why a proposed change is preferable. It's advisable to the 87elaborations on why a proposed change is preferable. It's advisable to the
84reader that this be read serially, rather then jumping around. 88reader that this be read serially, rather then jumping around.
85 89
108initialization of the library that is absolutely needed. Additionally, they 112initialization of the library that is absolutely needed. Additionally, they
109cannot modify any ebuild template functions- src_compile, src_unpack. Since they are 113cannot modify any ebuild template functions- src_compile, src_unpack. Since they are
110required to not modify the metadata keys, nor in any way affect the ebuild aside 114required to not modify the metadata keys, nor in any way affect the ebuild aside
111from providing functionality, they can be conditionally pulled in. They also 115from providing functionality, they can be conditionally pulled in. They also
112are allowed to pull in other elibs, but strictly just elibs- no eclasses, just 116are allowed to pull in other elibs, but strictly just elibs- no eclasses, just
113other elibs. A real world example would be the eutils eclass. 117other elibs. A real world example would be the eutils eclass.
114 118
115Portage, since the elib's don't modify metadata, isn't required to track elibs 119Portage, since the elib's don't modify metadata, isn't required to track elibs
116as it tracks eclasses. Thus a change in an elib doesn't result in half the tree 120as it tracks eclasses. Thus a change in an elib doesn't result in half the tree
117forced to be regenerated/marked stale when changed (this is more of an infra 121forced to be regenerated/marked stale when changed (this is more of an infra
118benefit, although regen's that take too long due to eclass changes have been 122benefit, although regen's that take too long due to eclass changes have been
119known to cause rsync issues due to missing timestamps). 123known to cause rsync issues due to missing timestamps).
120 124
121Elibs will not be available in the global scope of an eclass, or ebuild- nor during the 125Elibs will not be available in the global scope of an eclass, or ebuild- nor during the
122depends phase (basically a phase that sources the ebuild, to get it's metadata). Elib 126depends phase (basically a phase that sources the ebuild, to get its metadata). Elib
123calls in the global scope will be tracked, but the elib will not be loaded till just before 127calls in the global scope will be tracked, but the elib will not be loaded till just before
124the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are 128the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are
125completely incapable of modifying metadata. There is no room for confusion, late loading 129completely incapable of modifying metadata. There is no room for confusion, late loading
126of elibs gives you the functionality for all phases, except for depends- depends being the 130of elibs gives you the functionality for all phases, except for depends- depends being the
127only phase that is capable of specifying metadata. Second, as an added bonus, late 131only phase that is capable of specifying metadata. Second, as an added bonus, late
128loading reduces the amount of bash sourced for a regen- faster regens. This however is minor, 132loading reduces the amount of bash sourced for a regen- faster regens. This however is minor,
129and is an ancillary benefit of the first reason. 133and is an ancillary benefit of the first reason.
148 fi 152 fi
149 153
150 154
151Regarding maintainability of elibs, it should be a less of a load then old 155Regarding maintainability of elibs, it should be a less of a load then old
152eclasses. One of the major issues with old eclasses is that their functions are 156eclasses. One of the major issues with old eclasses is that their functions are
153quite incestuous- they're bound tightly to the env they're defined in. This 157quite incestuous- they're bound tightly to the env they're defined in. This
154makes eclass functions a bit fragile- the restrictions on what can, and cannot 158makes eclass functions a bit fragile- the restrictions on what can, and cannot
155be done in elibs will address this, making functionality less fragile (thus a 159be done in elibs will address this, making functionality less fragile (thus a
156bit more maintainable). 160bit more maintainable).
157 161
158There is no need for backwards compatibility with elibs- they just must work 162There is no need for backwards compatibility with elibs- they just must work
169 173
170The reduced role of Eclasses, and a clarification of existing Eclass requirements 174The reduced role of Eclasses, and a clarification of existing Eclass requirements
171--------------------------------------------------------------------------------- 175---------------------------------------------------------------------------------
172 176
173Since elibs are now intended on holding common bash functionality, the focus of 177Since elibs are now intended on holding common bash functionality, the focus of
174eclasses should be in defining an appropriate template for ebuilds. For example, 178eclasses should be in defining an appropriate template for ebuilds. For example,
175defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc. 179defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc.
176Additionally, eclasses should pull in any elibs they need for functionality. 180Additionally, eclasses should pull in any elibs they need for functionality.
177 181
178Eclass functionality that isn't directly related to the metadata, or src_* and 182Eclass functionality that isn't directly related to the metadata, or src_* and
179pkg_* funcs should be shifted into elibs to allow for maximal code reuse. This 183pkg_* funcs should be shifted into elibs to allow for maximal code reuse. This
216 220
217 221
218The end of backwards compatibility... 222The end of backwards compatibility...
219------------------------------------- 223-------------------------------------
220 224
221With current eclasses, once the eclass is in use, it's api can no longer be 225With current eclasses, once the eclass is in use, its api can no longer be
222changed, nor can the eclass ever be removed from the tree. This is why we still 226changed, nor can the eclass ever be removed from the tree. This is why we still
223have *ancient* eclasses that are completely unused sitting in the tree, for 227have *ancient* eclasses that are completely unused sitting in the tree, for
224example inherit.eclass . The reason for this, not surprisingly is a portage 228example inherit.eclass. The reason for this, not surprisingly, is a portage
225deficiency- on unmerging an installed ebuild, portage used the eclass from the 229deficiency: on unmerging an installed ebuild, portage used the eclass from the
226current tree. 230current tree.
227 231
228For a real world example of this, if you merged a glibc 2 years back, whatever 232For a real world example of this, if you merged a glibc 2 years back, whatever
229eclasses it used must still be compatible, or you may not be able to unmerge the 233eclasses it used must still be compatible, or you may not be able to unmerge the
230older glibc version during an upgrade to a newer version. So either the glibc 234older glibc version during an upgrade to a newer version. So either the glibc
266 270
267In other words, these new eclasses would in effect, be old eclasses since older 271In other words, these new eclasses would in effect, be old eclasses since older
268portage versions could still access them. 272portage versions could still access them.
269 273
270 274
271Tree restructuring. 275Tree restructuring
272------------------- 276------------------
273 277
274There are only two way to block the existing (as of this writing) inherit 278There are only two way to block the existing (as of this writing) inherit
275functionality from accessing the new eclasses- either change the extension of 279functionality from accessing the new eclasses- either change the extension of
276eclasses to something other then 'eclass', or to have them stored in a separate 280eclasses to something other then 'eclass', or to have them stored in a separate
277subdirectory of the tree then eclass. 281subdirectory of the tree then eclass.
287eclasses, please reread the previous section. It's unfortunately a requirement 291eclasses, please reread the previous section. It's unfortunately a requirement
288to take advantage of all that the next major portage release will allow. 292to take advantage of all that the next major portage release will allow.
289 293
290The proposed directory structure is ${PORTDIR}/include/{eclass,elib}. 294The proposed directory structure is ${PORTDIR}/include/{eclass,elib}.
291Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used 295Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used
292(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
293possibility (likely a fact) that new eclasses someday may be found lacking, and 297possibility (likely a fact) that new eclasses someday may be found lacking, and
294refined further (version three as it were). Or perhaps we want to add yet more 298refined further (version three as it were). Or perhaps we want to add yet more
295functionality with direct relation to sourcing new files, and we would then need 299functionality with direct relation to sourcing new files, and we would then need
296to further populate ${PORTDIR}. 300to further populate ${PORTDIR}.
297 301
298The new-eclass directory will be (at least) 2 levels deep- for example: 302The new-eclass directory will be (at least) 2 levels deep- for example:
299 303
315to ensure no files are missing, and that nothing has been tainted. 319to ensure no files are missing, and that nothing has been tainted.
316 320
317The elib directory will be structured in the same way, for the same reasons. 321The elib directory will be structured in the same way, for the same reasons.
318 322
319Repoman will have to be extended to work within new eclass and elib groups, and 323Repoman will have to be extended to work within new eclass and elib groups, and
320to handle signing and committing. This is intentional, and a good thing. This 324to handle signing and committing. This is intentional, and a good thing. This
321gives repoman the possibility of doing sanity checks on elibs/new eclasses. 325gives repoman the possibility of doing sanity checks on elibs/new eclasses.
322 326
323Note these checks will not prevent developers from doing dumb things with eclass- 327Note these checks will not prevent developers from doing dumb things with eclass-
324these checks would only be capable of doing basic sanity checks, such as syntax checks. 328these checks would only be capable of doing basic sanity checks, such as syntax checks.
325There is no way to prevent people from doing dumb things (exempting perhaps repeated 329There is no way to prevent people from doing dumb things (exempting perhaps repeated
331--------------------------------------------------------- 335---------------------------------------------------------
332 336
333As clarified above, new eclasses will exist in a separate directory that will be 337As clarified above, new eclasses will exist in a separate directory that will be
334intentionally inaccessible to the inherit function. As such, users of older 338intentionally inaccessible to the inherit function. As such, users of older
335portage versions *will* have to upgrade to merge any ebuild that uses elibs/new 339portage versions *will* have to upgrade to merge any ebuild that uses elibs/new
336eclasses. A depend on the next major portage version would transparently handle 340eclasses. A depend on the next major portage version would transparently handle
337this for rsync users. 341this for rsync users.
338 342
339There still is the issue of users who haven't upgraded to the required portage 343There still is the issue of users who haven't upgraded to the required portage
340version. This is a minor concern frankly- portage releases include new 344version. This is a minor concern frankly- portage releases include new
341functionality, and bug fixes. If they won't upgrade, it's assumed they have 345functionality, and bug fixes. If they won't upgrade, it's assumed they have
342their reasons and are big boys, thus able to handle the complications themselves. 346their reasons and are big boys, thus able to handle the complications themselves.
343 347
344The real issue is broken envs, whether in binpkgs, or for installed packages. 348The real issue is broken envs, whether in binpkgs, or for installed packages.
345Two options exist- either the old eclasses are left in the tree indefinitely, or 349Two options exist- either the old eclasses are left in the tree indefinitely, or
381 385
382Note for this to happen requires either rather... unwise uses of root, or significant 386Note for this to happen requires either rather... unwise uses of root, or significant
383fs corruption. Regardless of the cause, it's quite likely for this to even become an 387fs corruption. Regardless of the cause, it's quite likely for this to even become an
384issue, the system's vdb is completely unusable. It's a moot issue at that point. 388issue, the system's vdb is completely unusable. It's a moot issue at that point.
385If you lose your vdb, or it gets seriously damaged, it's akin to lobotomizing portage- 389If you lose your vdb, or it gets seriously damaged, it's akin to lobotomizing portage-
386it doesn't know what's installed, it doesn't know of it's own files, and in general, 390it doesn't know what's installed, it doesn't know of its own files, and in general,
387a rebuilding of the system is about the only sane course of action. The missing env is 391a rebuilding of the system is about the only sane course of action. The missing env is
388truly the least of the users concern in such a case. 392truly the least of the users concern in such a case.
389 393
390Continuing with the more likely scenario, users unwilling to upgrade portage will 394Continuing with the more likely scenario, users unwilling to upgrade portage will
391*not* be left out in the rain. Merging the old eclass compat ebuild will provide 395*not* be left out in the rain. Merging the old eclass compat ebuild will provide
392the missing eclasses, thus providing that lost functionality . 396the missing eclasses, thus providing that lost functionality.
393 397
394Note the intention isn't to force them to upgrade, hence the ability to restore the 398Note the intention isn't to force them to upgrade, hence the ability to restore the
395lost functionality. The intention is to clean up the existing mess, and allow us 399lost functionality. The intention is to clean up the existing mess, and allow us
396to move forward. The saying "you've got to break a few eggs to make an omelet" 400to move forward. The saying "you've got to break a few eggs to make an omelet"
397is akin, exempting the fact we're providing a way to make the eggs whole again 401is akin, exempting the fact we're providing a way to make the eggs whole again
398(the king's men would've loved such an option). 402(the king's men would've loved such an option).
399 403
400 404
401Migrating to the new setup 405Migrating to the new setup
417infrastructure server that generates the cache for rsync users will have to 421infrastructure server that generates the cache for rsync users will have to
418either be upgraded to a version of portage supporting new eclasses, or patched. 422either be upgraded to a version of portage supporting new eclasses, or patched.
419The former being much more preferable then the latter for the portage devs. 423The former being much more preferable then the latter for the portage devs.
420 424
421Beyond that, an appropriate window for old eclasses to exist in the tree must be 425Beyond that, an appropriate window for old eclasses to exist in the tree must be
422determined, and prior to that window passing an ebuild must be added to the tree 426determined, and prior to that window passing, an ebuild must be added to the tree
423so users can get the old eclasses if needed. 427so users can get the old eclasses if needed.
424 428
425For eclass devs to migrate from old to new, it is possible for them to just 429For eclass devs to migrate from old to new, it is possible for them to just
426transfer the old eclass into an appropriate grouping in the new eclass directory, 430transfer the old eclass into an appropriate grouping in the new eclass directory,
427although it's advisable they cleanse all cruft out of the eclass. You can 431although it's advisable they cleanse all cruft out of the eclass. You can
428migrate ebuilds gradually over to the new eclass, and don't have to worry about 432migrate ebuilds gradually over to the new eclass, and don't have to worry about
429having to support ebuilds from X years back. 433having to support ebuilds from X years back.
430 434
431Essentially, you have a chance to nail the design perfectly/cleanly, and have a 435Essentially, you have a chance to nail the design perfectly/cleanly, and have a
432window in which to redesign it. It's humbly suggested eclass devs take 436window in which to redesign it. It's humbly suggested eclass devs take
444 448
445To recap: 449To recap:
446:: 450::
447 451
448 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
449 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
450 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
451 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
452 functionality. It is their choice to upgrade, as such, the gradual 456 functionality. It is their choice to upgrade, as such, the gradual
453 'thinning' of available ebuilds should they block the portage upgrade is 457 'thinning' of available ebuilds should they block the portage upgrade is
454 their responsibility. 458 their responsibility.
455 459
456 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,
457 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
458 rely on the old eclass to be unable to unmerge, with the same applying for 462 rely on the old eclass to be unable to unmerge, with the same applying for
459 merging of binpkgs dependent on the following paragraph. 463 merging of binpkgs dependent on the following paragraph.
460 464
461 The old eclass-compat is only required for users who do not upgrade their 465 The old eclass-compat is only required for users who do not upgrade their
462 portage installation, and one further exemption- if the user has somehow 466 portage installation, and one further exemption- if the user has somehow

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.5

  ViewVC Help
Powered by ViewVC 1.1.20