| Title: | Eclass Restructure/Redesign |
|---|---|
| Version: | 1.2 | +
| Version: | 1.3 |
| Last-Modified: | 2005/03/06 20:33:20 | +
| Last-Modified: | 2005/03/06 20:39:19 |
| Author: | Brian Harring <ferringb at gentoo.org>, John Mylchreest <johnm at gentoo.org> |
| Type: | Standards Track |
| Content-Type: | text/x-rst | +
| Content-Type: | text/x-rst |
| Created: | 29-Jan-2005 |
| Post-History: | 29-Jan-2005 | +
| Post-History: | 29-Jan-2005 6-Mar-2005 |
Eclasses within the tree currently are a bit of a mess- they're forced to maintain backwards compatibility w/ all previous functionality. In effect, their api is constant, and can only be added to- never changing the existing -functionality. This obviously is quite limiting, and leads to cruft accruing in +functionality. This obviously is quite limiting, and leads to cruft accruing in eclasses as a eclasses design is refined. This needs to be dealt with prior to eclass code reaching a critical mass where they become unmanageable/fragile (recent pushes for eclass versioning could be interpreted as proof of this).
Beyond that, eclasses were originally intended as a method to allow for ebuilds to use a pre-existing block of code, rather then having to duplicate the code in each ebuild. This is a good thing, but there are ill effects that result from -the current design. Eclasses inherit other eclasses to get a single function- in +the current design. Eclasses inherit other eclasses to get a single function- in doing so, modifying the the exported 'template' (default src_compile, default -src_unpack, various vars, etc). All the eclass designer was after was reusing a +src_unpack, various vars, etc). All the eclass designer was after was reusing a function, not making their eclass sensitive to changes in the template of the eclass it's inheriting. The eclass designer -should- be aware of changes in the function they're using, but shouldn't have to worry about their default src_* @@ -115,7 +114,7 @@ progress.
By rolling all changes into one large change, a line is intentionally drawn in the sand. Old eclasses allowed for this, behaved this way. New eclasses allow -for that, and behave this way. This should reduce misconceptions about what is +for that, and behave this way. This should reduce misconceptions about what is allowed/possible with eclasses, thus reducing bugs that result from said misconceptions.
A few words on elibs- think of them as a clear definition between behavioral @@ -126,7 +125,7 @@ being added to the tree as elibs, as is the bulk of eutils.
The various parts of this proposal are broken down into a set of changes and elaborations on why a proposed change is preferable. It's advisable to the reader that this be read serially, rather then jumping around.
@@ -153,16 +152,16 @@ required to not modify the metadata keys, nor in any way affect the ebuild aside from providing functionality, they can be conditionally pulled in. They also are allowed to pull in other elibs, but strictly just elibs- no eclasses, just -other elibs. A real world example would be the eutils eclass. +other elibs. A real world example would be the eutils eclass.Portage, since the elib's don't modify metadata, isn't required to track elibs as it tracks eclasses. Thus a change in an elib doesn't result in half the tree forced to be regenerated/marked stale when changed (this is more of an infra benefit, although regen's that take too long due to eclass changes have been known to cause rsync issues due to missing timestamps).
Elibs will not be available in the global scope of an eclass, or ebuild- nor during the -depends phase (basically a phase that sources the ebuild, to get it's metadata). Elib +depends phase (basically a phase that sources the ebuild, to get its metadata). Elib calls in the global scope will be tracked, but the elib will not be loaded till just before -the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are +the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are completely incapable of modifying metadata. There is no room for confusion, late loading of elibs gives you the functionality for all phases, except for depends- depends being the only phase that is capable of specifying metadata. Second, as an added bonus, late @@ -186,7 +185,7 @@
Regarding maintainability of elibs, it should be a less of a load then old eclasses. One of the major issues with old eclasses is that their functions are -quite incestuous- they're bound tightly to the env they're defined in. This +quite incestuous- they're bound tightly to the env they're defined in. This makes eclass functions a bit fragile- the restrictions on what can, and cannot be done in elibs will address this, making functionality less fragile (thus a bit more maintainable).
@@ -203,7 +202,7 @@Since elibs are now intended on holding common bash functionality, the focus of -eclasses should be in defining an appropriate template for ebuilds. For example, +eclasses should be in defining an appropriate template for ebuilds. For example, defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc. Additionally, eclasses should pull in any elibs they need for functionality.
Eclass functionality that isn't directly related to the metadata, or src_* and @@ -241,11 +240,11 @@
With current eclasses, once the eclass is in use, it's api can no longer be +
With current eclasses, once the eclass is in use, its api can no longer be changed, nor can the eclass ever be removed from the tree. This is why we still have ancient eclasses that are completely unused sitting in the tree, for -example inherit.eclass . The reason for this, not surprisingly is a portage -deficiency- on unmerging an installed ebuild, portage used the eclass from the +example inherit.eclass. The reason for this, not surprisingly, is a portage +deficiency: on unmerging an installed ebuild, portage used the eclass from the current tree.
For a real world example of this, if you merged a glibc 2 years back, whatever eclasses it used must still be compatible, or you may not be able to unmerge the @@ -283,7 +282,7 @@ portage versions could still access them.
There are only two way to block the existing (as of this writing) inherit functionality from accessing the new eclasses- either change the extension of eclasses to something other then 'eclass', or to have them stored in a separate @@ -299,13 +298,13 @@ to take advantage of all that the next major portage release will allow.
The proposed directory structure is ${PORTDIR}/include/{eclass,elib}. Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used -(although many would cringe at the -ng), but such a name is unwise. Consider the +(although many would cringe at the -ng), but such a name is unwise. Consider the possibility (likely a fact) that new eclasses someday may be found lacking, and -refined further (version three as it were). Or perhaps we want to add yet more +refined further (version three as it were). Or perhaps we want to add yet more functionality with direct relation to sourcing new files, and we would then need to further populate ${PORTDIR}.
The new-eclass directory will be (at least) 2 levels deep- for example:
-The elib directory will be structured in the same way, for the same reasons.
Repoman will have to be extended to work within new eclass and elib groups, and -to handle signing and committing. This is intentional, and a good thing. This +to handle signing and committing. This is intentional, and a good thing. This gives repoman the possibility of doing sanity checks on elibs/new eclasses.
Note these checks will not prevent developers from doing dumb things with eclass- these checks would only be capable of doing basic sanity checks, such as syntax checks. @@ -337,10 +336,10 @@
As clarified above, new eclasses will exist in a separate directory that will be intentionally inaccessible to the inherit function. As such, users of older portage versions will have to upgrade to merge any ebuild that uses elibs/new -eclasses. A depend on the next major portage version would transparently handle +eclasses. A depend on the next major portage version would transparently handle this for rsync users.
There still is the issue of users who haven't upgraded to the required portage -version. This is a minor concern frankly- portage releases include new +version. This is a minor concern frankly- portage releases include new functionality, and bug fixes. If they won't upgrade, it's assumed they have their reasons and are big boys, thus able to handle the complications themselves.
The real issue is broken envs, whether in binpkgs, or for installed packages. @@ -379,15 +378,15 @@ fs corruption. Regardless of the cause, it's quite likely for this to even become an issue, the system's vdb is completely unusable. It's a moot issue at that point. If you lose your vdb, or it gets seriously damaged, it's akin to lobotomizing portage- -it doesn't know what's installed, it doesn't know of it's own files, and in general, +it doesn't know what's installed, it doesn't know of its own files, and in general, a rebuilding of the system is about the only sane course of action. The missing env is truly the least of the users concern in such a case.
Continuing with the more likely scenario, users unwilling to upgrade portage will not be left out in the rain. Merging the old eclass compat ebuild will provide -the missing eclasses, thus providing that lost functionality .
+the missing eclasses, thus providing that lost functionality.Note the intention isn't to force them to upgrade, hence the ability to restore the -lost functionality. The intention is to clean up the existing mess, and allow us -to move forward. The saying "you've got to break a few eggs to make an omelet" +lost functionality. The intention is to clean up the existing mess, and allow us +to move forward. The saying "you've got to break a few eggs to make an omelet" is akin, exempting the fact we're providing a way to make the eggs whole again (the king's men would've loved such an option).
Beyond that, an appropriate window for old eclasses to exist in the tree must be -determined, and prior to that window passing an ebuild must be added to the tree +determined, and prior to that window passing, an ebuild must be added to the tree so users can get the old eclasses if needed.
For eclass devs to migrate from old to new, it is possible for them to just transfer the old eclass into an appropriate grouping in the new eclass directory, -although it's advisable they cleanse all cruft out of the eclass. You can +although it's advisable they cleanse all cruft out of the eclass. You can migrate ebuilds gradually over to the new eclass, and don't have to worry about having to support ebuilds from X years back.
Essentially, you have a chance to nail the design perfectly/cleanly, and have a @@ -430,7 +429,7 @@
To recap:
New eclasses and elib functionality will be tied to a specific portage
-version. A DEPENDs on said portage version should address this for rsync
+version. A DEPENDs on said portage version should address this for rsync
users who refuse to upgrade to a portage version that supports the new
eclasses/elibs and will gradually be unable to merge ebuilds that use said
functionality. It is their choice to upgrade, as such, the gradual
@@ -438,7 +437,7 @@
their responsibility.
Old eclasses at some point in the future should be removed from the tree,
-and released in a tarball/ebuild. This will cause installed ebuilds that
+and released in a tarball/ebuild. This will cause installed ebuilds that
rely on the old eclass to be unable to unmerge, with the same applying for
merging of binpkgs dependent on the following paragraph.
@@ -456,13 +455,14 @@
Copyright
This document has been placed in the public domain.