| 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.4 $ |
| 4 | Last-Modified: $Date: 2005/02/16 21:30:44 $ |
4 | Last-Modified: $Date: 2005/09/15 02:37:38 $ |
| 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: Draft |
| 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 |
| 11 | |
11 | |
| 12 | |
12 | |
| 13 | Abstract |
13 | Abstract |
| 14 | ======== |
14 | ======== |
| 15 | |
15 | |
| 16 | For any design, the transition from theoretical to applied exposes inadequacies |
16 | 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 |
17 | 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. |
18 | revision of the current eclass setup to address current eclass inadequacies. |
| 19 | |
19 | |
| 20 | This document proposes several thing- the creation of ebuild libraries, 'elibs', |
20 | 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 |
21 | 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. |
22 | 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 |
23 | In general, a large scale restructuring of what eclasses are and how they're |
| 24 | implemented. Essentially version two of the eclass setup. |
24 | implemented. Essentially version two of the eclass setup. |
| 25 | |
25 | |
| … | |
… | |
| 27 | Terminology |
27 | Terminology |
| 28 | =========== |
28 | =========== |
| 29 | |
29 | |
| 30 | From this point on, the proposed eclass setup will be called 'new eclasses', the |
30 | 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 |
31 | existing crop (as of this writing) will be referenced as 'old eclasses'. The |
| 32 | destinction is elaborated on within this document. |
32 | distinction is elaborated on within this document. |
| 33 | |
33 | |
| 34 | |
34 | |
| 35 | Motivation and Rationale |
35 | Motivation and Rationale |
| 36 | ======================== |
36 | ======================== |
| 37 | |
37 | |
| 38 | Eclasses within the tree currently are a bit of a mess- they're forced to |
38 | 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, |
39 | maintain backwards compatibility w/ all previous functionality. In effect, |
| 40 | their api is constant, and can only be added to- never changing the existing |
40 | 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 |
41 | 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 |
42 | 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 |
43 | eclass code reaching a critical mass where they become unmanageable/fragile |
| 44 | (recent pushes for eclass versioning could be interpretted as proof of this). |
44 | (recent pushes for eclass versioning could be interpreted as proof of this). |
| 45 | |
45 | |
| 46 | Beyond that, eclasses were originally intended as a method to allow for ebuilds |
46 | 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 |
47 | 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 |
48 | 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 |
49 | 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 |
50 | 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 |
51 | 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 |
52 | 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 |
53 | 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_* |
54 | 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. |
55 | and pkg_* functions being overwritten, let alone the env changes. |
| 56 | |
56 | |
| … | |
… | |
| 61 | rather then requiring them to be aware of what phase of eclass changes is in |
61 | rather then requiring them to be aware of what phase of eclass changes is in |
| 62 | progress. |
62 | progress. |
| 63 | |
63 | |
| 64 | By rolling all changes into one large change, a line is intentionally drawn in |
64 | 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 |
65 | 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 |
66 | 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 |
67 | allowed/possible with eclasses, thus reducing bugs that result from said |
| 68 | misconceptions. |
68 | misconceptions. |
| 69 | |
69 | |
|
|
70 | A few words on elibs- think of them as a clear definition between behavioral |
|
|
71 | functionality of an eclass, and the library functionality. Eclass's modify |
|
|
72 | template data, and are the basis for other ebuilds- elibs, however are *just* |
|
|
73 | common bash functionality. |
| 70 | |
74 | |
|
|
75 | Consider the majority of the portage bin/* scripts- these all are candidates for |
|
|
76 | being added to the tree as elibs, as is the bulk of eutils. |
|
|
77 | |
|
|
78 | |
| 71 | Specification. |
79 | Specification |
| 72 | ============== |
80 | ============= |
| 73 | |
81 | |
| 74 | The various parts of this proposal are broken down into a set of changes and |
82 | 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 |
83 | elaborations on why a proposed change is preferable. It's advisable to the |
| 76 | reader that this be read serially, rather then jumping around. |
84 | reader that this be read serially, rather then jumping around. |
| 77 | |
85 | |
| … | |
… | |
| 91 | A new directory named elib should be added to the top level of the tree to serve |
99 | 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 |
100 | 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 |
101 | 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 |
102 | 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 |
103 | 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. |
104 | that (for example) zsh compatibility hacks could be hidden in the elib function. |
| 97 | |
105 | |
| 98 | Elib's will be collections of bash functions- they're not allowed to do anything |
106 | 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- |
107 | in the global scope aside from function definition, and any -minimal- |
| 100 | initialization of the library that is absolutely needed. Additionally, they |
108 | initialization of the library that is absolutely needed. Additionally, they |
| 101 | cannot modify any ebuild functions- src_compile, src_unpack fex. Since they are |
109 | 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 |
110 | 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 |
111 | 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 |
112 | 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. |
113 | other elibs. A real world example would be the eutils eclass. |
| 106 | |
114 | |
| 107 | Portage, since the elib's don't modify metadata, isn't required to track elibs |
115 | 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 |
116 | 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 |
117 | 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 |
118 | 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 |
119 | known to cause rsync issues due to missing timestamps). |
| 112 | will do for elibs, aside from provide the elib function, is track what elibs |
120 | |
| 113 | have been loaded thus far, and load an elib only if it hasn't been loaded once |
121 | 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) |
122 | depends phase (basically a phase that sources the ebuild, to get its metadata). Elib |
|
|
123 | calls in the global scope will be tracked, but the elib will not be loaded till just before |
|
|
124 | the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are |
|
|
125 | completely incapable of modifying metadata. There is no room for confusion, late loading |
|
|
126 | of elibs gives you the functionality for all phases, except for depends- depends being the |
|
|
127 | only phase that is capable of specifying metadata. Second, as an added bonus, late |
|
|
128 | loading reduces the amount of bash sourced for a regen- faster regens. This however is minor, |
|
|
129 | and is an ancillary benefit of the first reason. |
|
|
130 | |
|
|
131 | There are a few further restrictions with elibs--mainly, elibs to load can only be specified |
|
|
132 | in either global scope, or in the setup, unpack, compile, test, and install phases. You can |
|
|
133 | not load elibs in prerm, postrm, preinst, and postinst. The reason being, for \*rm phases, |
|
|
134 | installed pkgs will have to look to the tree for the elib, which allows for api drift to cause |
|
|
135 | breakage. For \*inst phases, same thing, except the culprit is binpkgs. |
|
|
136 | |
| 115 | is that elibs cannot change their exported api dependant on the api (as some |
137 | There is a final restriction--elibs cannot change their exported api dependent on the api |
| 116 | eclass do for example). |
138 | (as some eclass do for example). The reason mainly being that elibs are loaded once--not |
|
|
139 | multiple times, as eclasses are. |
|
|
140 | |
|
|
141 | To clarify, for example this is invalid. |
|
|
142 | :: |
|
|
143 | |
|
|
144 | if [[ -n ${SOME_VAR} ]]; then |
|
|
145 | func x() { echo "I'm accessible only via tweaking some var";} |
|
|
146 | else |
|
|
147 | func x() { echo "this is invalid, do not do it."; } |
|
|
148 | fi |
|
|
149 | |
| 117 | |
150 | |
| 118 | Regarding maintainability of elibs, it should be a less of a load then old |
151 | 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 |
152 | 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 |
153 | 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 |
154 | 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 |
155 | be done in elibs will address this, making functionality less fragile (thus a |
| 123 | bit more maintainable). |
156 | bit more maintainable). |
| 124 | |
157 | |
| 125 | There is no need for backwards compatability with elibs- they just must work |
158 | 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 |
159 | against the current tree. Thus elibs can be removed when the tree no longer |
| 127 | needs them. The reasons for this are explained below. |
160 | needs them. The reasons for this are explained below. |
| 128 | |
161 | |
| 129 | Structuring of the elibs directory will be exactly the same as that of the new |
162 | Structuring of the elibs directory will be exactly the same as that of the new |
| 130 | eclass directory (detailed below), sans a different extension. |
163 | eclass directory (detailed below), sans a different extension. |
| 131 | |
164 | |
|
|
165 | As to why their are so many restrictions, the answer is simple- the definition of |
|
|
166 | what elibs are, what they are capable of, and how to use them is nailed down as much as |
|
|
167 | possible to avoid *any* ambiguity related to them. The intention is to make it clear, |
|
|
168 | such that no misconceptions occur, resulting in bugs. |
| 132 | |
169 | |
| 133 | The reduced role of Eclasses, and a clarification of existing Eclass requirements |
170 | The reduced role of Eclasses, and a clarification of existing Eclass requirements |
| 134 | --------------------------------------------------------------------------------- |
171 | --------------------------------------------------------------------------------- |
| 135 | |
172 | |
| 136 | Since elibs are now intended on holding common bash functionality, the focus of |
173 | 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, |
174 | eclasses should be in defining an appropriate template for ebuilds. For example, |
| 138 | defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc. |
175 | defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc. |
| 139 | Additionally, eclasses should pull in any elibs they need for functionality. |
176 | Additionally, eclasses should pull in any elibs they need for functionality. |
| 140 | |
177 | |
| 141 | Eclass functionality that isn't directly related to the metadata, or src_* and |
178 | 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 |
179 | 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 |
188 | metadata keys exported from an ebuild on system A, must be *exactly* the same as |
| 152 | the keys exported on system B. |
189 | the keys exported on system B. |
| 153 | |
190 | |
| 154 | If an eclass (or ebuild for that matter) violates this constant requirement, it |
191 | 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 |
192 | leads to portage doing the wrong thing for rsync users- for example, wrong deps |
| 156 | pulled in, leading to compilation failure. |
193 | pulled in, leading to compilation failure, or dud deps. |
| 157 | |
194 | |
| 158 | If the existing metadata isn't flexible enough for what is required for a |
195 | 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 |
196 | 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- |
197 | 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 |
198 | 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 |
199 | 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 |
200 | 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 |
201 | 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 | |
202 | |
| 168 | It's quite likely there is a way to allow what you're attempting- if you just go |
203 | 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 |
204 | and do it, the rsync users (our user base) suffer the results of compilation |
| 170 | failures and unneeded deps being pulled in. |
205 | failures and unneeded deps being pulled in. |
| 171 | |
206 | |
| 172 | After that stern reminder, back to new eclasses. Defining INHERITED and ECLASS |
207 | 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 |
208 | within the eclass is no longer required. Portage already handles those vars if |
| 174 | they aren't defined. |
209 | they aren't defined. |
| 175 | |
210 | |
| 176 | As with elibs, it's no longer required backwards compatability be maintained |
211 | As with elibs, it's no longer required that backwards compatibility be maintained |
| 177 | indefinitely- compatability must be maintained against the current tree, but |
212 | 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 |
213 | 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 |
214 | elaborated in the next section) can be removed from the tree once they're no |
| 180 | longer in use. |
215 | longer in use. |
| 181 | |
216 | |
| 182 | |
217 | |
| 183 | The end of backwards compatability... |
218 | The end of backwards compatibility... |
| 184 | ------------------------------------- |
219 | ------------------------------------- |
| 185 | |
220 | |
| 186 | With current eclasses, once the eclass is in use, it's api can no longer be |
221 | 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 |
222 | 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 |
223 | 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 |
224 | 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 |
225 | deficiency: on unmerging an installed ebuild, portage used the eclass from the |
| 191 | current tree. |
226 | current tree. |
| 192 | |
227 | |
| 193 | For a real world example of this, if you merged a glibc 2 years back, whatever |
228 | 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 |
229 | 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 |
230 | 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 |
231 | 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 |
232 | in the rain, or maintaining an ever increasing load of backwards compatibility |
| 198 | cruft in any used eclasses. |
233 | cruft in any used eclasses. |
| 199 | |
234 | |
| 200 | Binpkgs suffer a similar fate. Merging of a binpkg pulls needed eclasses from |
235 | 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 |
236 | 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. |
237 | 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 |
240 | 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 |
241 | 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, |
242 | 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. |
243 | they'll use the 'saved' version of the eclass they were built/merged with. |
| 209 | |
244 | |
| 210 | So the backwards compatability requirement for users of the next major portage |
245 | 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. |
246 | version (and beyond) isn't required. All the cruft can be dropped. |
| 212 | |
247 | |
| 213 | The problem is that there will be users using older versions of portage that |
248 | 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 |
249 | support this functionality- these older installations *cannot* use the |
| 215 | for them. Additionally, earlier versions of portage haven't always handled the |
250 | 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 |
251 | 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 |
252 | 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 | |
253 | |
| 226 | With the next major portage release, it will be possible to drop backwards |
254 | 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 |
255 | 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 |
256 | incapable of properly handling the env requirements. |
| 229 | unfortunates and those who don't upgrade. |
|
|
| 230 | |
257 | |
| 231 | Unfortunately, the creation of new eclasses within the tree has an additional |
258 | 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 |
259 | the old eclass directory. The new eclasses must be inaccessible, and portage throws |
|
|
260 | 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 |
261 | eclasses. Basically, whatever it's passed (inherit kernel or inherit |
| 234 | kernel/kernel) it will pull in (kernel.eclass, and kernel/kernel.eclass |
262 | kernel/kernel) it will pull in (kernel.eclass, and kernel/kernel.eclass |
| 235 | respectively). So even if the new eclasses were implemented within a |
263 | 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 |
264 | subdirectory of the eclass dir in the tree, all current portage versions would |
| 237 | still be able to access them. |
265 | still be able to access them. |
| 238 | |
266 | |
| 239 | In other words, these new eclasses would in effect, be old eclasses since older |
267 | In other words, these new eclasses would in effect, be old eclasses since older |
| 240 | portage versions could still access them. |
268 | portage versions could still access them. |
| 241 | |
269 | |
| 242 | |
270 | |
| 243 | Tree restructuring. |
271 | Tree restructuring |
| 244 | ------------------- |
272 | ------------------ |
| 245 | |
273 | |
| 246 | There are only two way to block the existing (as of this writing) inherit |
274 | 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 |
275 | 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 |
276 | eclasses to something other then 'eclass', or to have them stored in a separate |
| 249 | subdirectory of the tree then eclass. |
277 | subdirectory of the tree then eclass. |
| 250 | |
278 | |
| 251 | The latter is preferable, and the proposed solution. Reasons are- the current |
279 | The latter is preferable, and the proposed solution. Reasons are- the current |
| 252 | eclass directory is already overgrown. Structuring of the new eclass dir |
280 | eclass directory is already overgrown. Structuring of the new eclass dir |
| 253 | (clarified below) will allow for easier signing, ChangeLogs, and grouping of |
281 | (clarified below) will allow for easier signing, ChangeLogs, and grouping of |
| … | |
… | |
| 257 | |
285 | |
| 258 | If it's unclear as to why the old inherit function *cannot* access the new |
286 | 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 |
287 | 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. |
288 | to take advantage of all that the next major portage release will allow. |
| 261 | |
289 | |
| 262 | The proposed directory sructure is ${PORTDIR}/include/{eclass,elib}. |
290 | The proposed directory structure is ${PORTDIR}/include/{eclass,elib}. |
| 263 | Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used |
291 | 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 |
292 | (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 |
293 | 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 |
294 | 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 |
295 | functionality with direct relation to sourcing new files, and we would then need |
| 268 | to further populate ${PORTDIR}. |
296 | to further populate ${PORTDIR}. |
| 269 | |
297 | |
| 270 | The new-eclass directory will be (at least) 2 levels deep- for example: |
298 | The new-eclass directory will be (at least) 2 levels deep- for example: |
| 271 | |
299 | |
| … | |
… | |
| 280 | |
308 | |
| 281 | No eclasses will be allowed in the base directory- grouping of new eclasses will |
309 | 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 |
310 | 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 |
311 | 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 |
312 | 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 |
313 | saner/easier signing of eclasses- you can just stick a signed |
| 286 | Manifest file w/in that grouping, thus providing the information portage needs |
314 | 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. |
315 | to ensure no files are missing, and that nothing has been tainted. |
| 288 | |
316 | |
| 289 | The elib directory will be structured in the same way, for the same reasons. |
317 | The elib directory will be structured in the same way, for the same reasons. |
| 290 | |
318 | |
| 291 | Repoman will have to be extended to work within new eclass and elib groups, and |
319 | 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 |
320 | 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. |
321 | 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 | |
322 | |
|
|
323 | Note these checks will not prevent developers from doing dumb things with eclass- |
|
|
324 | these checks would only be capable of doing basic sanity checks, such as syntax checks. |
|
|
325 | There is no way to prevent people from doing dumb things (exempting perhaps repeated |
|
|
326 | applications of a cattle prod)- these are strictly automatic checks, akin to repoman's |
|
|
327 | dependency checks. |
| 299 | |
328 | |
|
|
329 | |
| 300 | The start of a different phase of backwards compatability |
330 | The start of a different phase of backwards compatibility |
| 301 | --------------------------------------------------------- |
331 | --------------------------------------------------------- |
| 302 | |
332 | |
| 303 | As clarified above, new eclasses will exist in a seperate directory that will be |
333 | 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 |
334 | 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 |
335 | 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 |
336 | eclasses. A depend on the next major portage version would transparently handle |
| 307 | transparently handle this for rsync users. |
337 | this for rsync users. |
| 308 | |
338 | |
| 309 | There still is the issue of users who haven't upgraded to the required portage |
339 | 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 |
340 | 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 |
341 | 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. |
342 | their reasons and are big boys, thus able to handle the complications themselves. |
| 313 | |
343 | |
| 314 | The real issue is broken envs, whether in binpkgs, or for installed packages. |
344 | 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 |
345 | Two options exist- either the old eclasses are left in the tree indefinitely, or |
| … | |
… | |
| 329 | |
359 | |
| 330 | For users who do not upgrade within the window of N months while the old |
360 | 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. |
361 | 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 |
362 | 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 |
363 | 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, |
364 | 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 |
365 | 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 |
366 | 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. |
367 | 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 | |
368 | |
| 343 | What is a bit more annoying is that once the old eclasses are out of the tree, |
369 | What is a bit more annoying is that once the old eclasses are out of the tree, |
|
|
370 | 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 |
371 | 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 |
372 | eclass. Same cause, different symptom being they will lose the ability to merge |
| 346 | eclasses. |
373 | any tbz2 that uses old eclasses also. |
| 347 | |
374 | |
| 348 | They however will *not* be left out in the rain. For merging old eclass |
375 | 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 |
376 | has suffered significant corruption of their installed package database (vdb). This is |
| 350 | ebuild. The compat ebuild provides the missing eclasses, thus providing that |
377 | ignoring the question of whether the vdb is even usable at this point, but the possibility |
| 351 | lost functionality. |
378 | exists for the saved envs to be non usable due to either A) missing, or B) corrupted. |
|
|
379 | In such a case, even with the new portage capabilities, they would need |
|
|
380 | the old eclass compat ebuild. |
| 352 | |
381 | |
|
|
382 | Note for this to happen requires either rather... unwise uses of root, or significant |
|
|
383 | fs corruption. Regardless of the cause, it's quite likely for this to even become an |
|
|
384 | issue, the system's vdb is completely unusable. It's a moot issue at that point. |
|
|
385 | If you lose your vdb, or it gets seriously damaged, it's akin to lobotomizing portage- |
|
|
386 | it doesn't know what's installed, it doesn't know of its own files, and in general, |
|
|
387 | a rebuilding of the system is about the only sane course of action. The missing env is |
|
|
388 | truly the least of the users concern in such a case. |
|
|
389 | |
|
|
390 | Continuing 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 |
|
|
392 | the missing eclasses, thus providing that lost functionality. |
|
|
393 | |
| 353 | The intention isn't to force them to upgrade, hence the ability to restore the |
394 | 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 |
395 | 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" |
396 | 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 |
397 | 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). |
398 | (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 | |
399 | |
| 367 | |
400 | |
| 368 | Migrating to the new setup |
401 | Migrating to the new setup |
| 369 | -------------------------- |
402 | -------------------------- |
| 370 | |
403 | |
| … | |
… | |
| 384 | infrastructure server that generates the cache for rsync users will have to |
417 | 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. |
418 | 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. |
419 | The former being much more preferable then the latter for the portage devs. |
| 387 | |
420 | |
| 388 | Beyond that, an appropriate window for old eclasses to exist in the tree must be |
421 | 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 |
422 | 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. |
423 | so users can get the old eclasses if needed. |
| 391 | |
424 | |
| 392 | For eclass devs to migrate from old to new, it is possible for them to just |
425 | 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, |
426 | 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 |
427 | 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 |
428 | migrate ebuilds gradually over to the new eclass, and don't have to worry about |
| 396 | having to support ebuilds from X years back. |
429 | having to support ebuilds from X years back. |
| 397 | |
430 | |
| 398 | Essentially, you have a chance to nail the design perfectly/cleanly, and have a |
431 | 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 |
432 | window in which to redesign it. It's humbly suggested eclass devs take |
| … | |
… | |
| 401 | |
434 | |
| 402 | |
435 | |
| 403 | Backwards Compatibility |
436 | Backwards Compatibility |
| 404 | ======================= |
437 | ======================= |
| 405 | |
438 | |
| 406 | All backwards compatability issues are addressed inline, but a recap is offered- |
439 | 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 |
440 | it's suggested that if the a particular compatibility issue is |
| 408 | questioned/worried over, the reader read the relevant section. There should be |
441 | 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 |
442 | 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. |
443 | of the potential solutions, and reasons for the chosen solution. |
| 411 | |
444 | |
| 412 | To recap: |
445 | To recap: |
| 413 | :: |
446 | :: |
| 414 | |
447 | |
| 415 | New eclasses and elib functionality will be tied to a specific portage |
448 | 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 |
449 | 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 |
450 | 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 |
451 | 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 |
452 | functionality. It is their choice to upgrade, as such, the gradual |
| 420 | 'thinning' of available ebuilds should they block the portage upgrade is |
453 | 'thinning' of available ebuilds should they block the portage upgrade is |
| 421 | their responsibility. |
454 | their responsibility. |
| 422 | |
455 | |
| 423 | Old eclasses at some point in the future should be removed from the tree, |
456 | 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 |
457 | 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 |
458 | rely on the old eclass to be unable to unmerge, with the same applying for |
| 426 | the same applying for merging of binpkgs. |
459 | merging of binpkgs dependent on the following paragraph. |
| 427 | |
460 | |
| 428 | This eclass ebuild should be a system depends target to make the transition |
461 | 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 |
462 | 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 |
463 | corrupted/destroyed their installed pkgs database (/var/db/pkg currently), |
| 431 | block upgrade paths. At least for portage, this already is something of a |
464 | 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 |
465 | ebuild would be required for ebuilds that required older eclasses in such a |
| 433 | essentially be standalone, and cannot benefit from any eclass/elib |
466 | case. Note, this case is rare also- as clarified above, it's mentioned |
| 434 | functionality. |
467 | strictly to be complete, it's not much of a real world scenario as elaborated |
|
|
468 | above. |
| 435 | |
469 | |
| 436 | |
470 | |
| 437 | Copyright |
471 | Copyright |
| 438 | ========= |
472 | ========= |
| 439 | |
473 | |
Parent Directory
| 
Revision Log
| 
Patch