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

Contents of /xml/htdocs/proj/en/glep/glep-0033.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.4 - (show annotations) (download) (as text)
Thu Sep 15 21:04:13 2005 UTC (8 years, 7 months ago) by g2boojum
Branch: MAIN
Changes since 1.3: +34 -29 lines
File MIME type: text/html
updates

1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <!--
5 This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
6 PEP, see http://www.python.org/peps/pep-0001.html for instructions and links
7 to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
8 -->
9 <head>
10 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
12 <title>GLEP 33 -- Eclass Restructure/Redesign</title>
13 <link rel="stylesheet" href="tools/glep.css" type="text/css" />
14 </head>
15 <body bgcolor="white">
16 <table class="navigation" cellpadding="0" cellspacing="0"
17 width="100%" border="0">
18 <tr><td class="navicon" width="150" height="35">
19 <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
20 <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
21 border="0" width="150" height="35" /></a></td>
22 <td class="textlinks" align="left">
23 [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
24 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
25 [<b><a href="./glep-0033.txt">GLEP Source</a></b>]
26 </td></tr></table>
27 <table class="rfc2822 docutils field-list" frame="void" rules="none">
28 <col class="field-name" />
29 <col class="field-body" />
30 <tbody valign="top">
31 <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">33</td>
32 </tr>
33 <tr class="field"><th class="field-name">Title:</th><td class="field-body">Eclass Restructure/Redesign</td>
34 </tr>
35 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.5</td>
36 </tr>
37 <tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference" href="http://www.gentoo.org/cgi-bin/viewcvs/xml/htdocs/proj/en/glep/glep-0033.txt?cvsroot=gentoo">2005/09/15 21:02:11</a></td>
38 </tr>
39 <tr class="field"><th class="field-name">Author:</th><td class="field-body">Brian Harring &lt;ferringb&#32;&#97;t&#32;gentoo.org&gt;, John Mylchreest &lt;johnm&#32;&#97;t&#32;gentoo.org&gt;</td>
40 </tr>
41 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Approved</td>
42 </tr>
43 <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
44 </tr>
45 <tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="http://www.python.org/peps/glep-0012.html">text/x-rst</a></td>
46 </tr>
47 <tr class="field"><th class="field-name">Created:</th><td class="field-body">29-Jan-2005</td>
48 </tr>
49 <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">29-Jan-2005 6-Mar-2005 15-Sep-2005</td>
50 </tr>
51 </tbody>
52 </table>
53 <hr />
54 <div class="contents topic" id="contents">
55 <p class="topic-title first"><a name="contents">Contents</a></p>
56 <ul class="simple">
57 <li><a class="reference" href="#status" id="id2" name="id2">Status</a></li>
58 <li><a class="reference" href="#abstract" id="id3" name="id3">Abstract</a></li>
59 <li><a class="reference" href="#terminology" id="id4" name="id4">Terminology</a></li>
60 <li><a class="reference" href="#motivation-and-rationale" id="id5" name="id5">Motivation and Rationale</a></li>
61 <li><a class="reference" href="#specification" id="id6" name="id6">Specification</a><ul>
62 <li><a class="reference" href="#ebuild-libraries-elibs-for-short" id="id7" name="id7">Ebuild Libraries (elibs for short)</a></li>
63 <li><a class="reference" href="#the-reduced-role-of-eclasses-and-a-clarification-of-existing-eclass-requirements" id="id8" name="id8">The reduced role of Eclasses, and a clarification of existing Eclass requirements</a></li>
64 <li><a class="reference" href="#the-end-of-backwards-compatibility" id="id9" name="id9">The end of backwards compatibility...</a></li>
65 <li><a class="reference" href="#tree-restructuring" id="id10" name="id10">Tree restructuring</a></li>
66 <li><a class="reference" href="#the-start-of-a-different-phase-of-backwards-compatibility" id="id11" name="id11">The start of a different phase of backwards compatibility</a></li>
67 <li><a class="reference" href="#migrating-to-the-new-setup" id="id12" name="id12">Migrating to the new setup</a></li>
68 </ul>
69 </li>
70 <li><a class="reference" href="#backwards-compatibility" id="id13" name="id13">Backwards Compatibility</a></li>
71 <li><a class="reference" href="#copyright" id="id14" name="id14">Copyright</a></li>
72 </ul>
73 </div>
74 <div class="section" id="status">
75 <h1><a class="toc-backref" href="#id2" name="status">Status</a></h1>
76 <p>Approved by the Gentoo Council on 15 September 2005.</p>
77 </div>
78 <div class="section" id="abstract">
79 <h1><a class="toc-backref" href="#id3" name="abstract">Abstract</a></h1>
80 <p>For any design, the transition from theoretical to applied exposes inadequacies
81 in the original design. This document is intended to document, and propose a
82 revision of the current eclass setup to address current eclass inadequacies.</p>
83 <p>This document proposes several things- the creation of ebuild libraries, 'elibs',
84 a narrowing of the focus of eclasses, a move of eclasses w/in the tree, the
85 addition of changelogs, and a way to allow for simple eclass gpg signing.
86 In general, a large scale restructuring of what eclasses are and how they're
87 implemented. Essentially version two of the eclass setup.</p>
88 </div>
89 <div class="section" id="terminology">
90 <h1><a class="toc-backref" href="#id4" name="terminology">Terminology</a></h1>
91 <p>From this point on, the proposed eclass setup will be called 'new eclasses', the
92 existing crop (as of this writing) will be referenced as 'old eclasses'. The
93 distinction is elaborated on within this document.</p>
94 </div>
95 <div class="section" id="motivation-and-rationale">
96 <h1><a class="toc-backref" href="#id5" name="motivation-and-rationale">Motivation and Rationale</a></h1>
97 <p>Eclasses within the tree currently are a bit of a mess- they're forced to
98 maintain backwards compatibility w/ all previous functionality. In effect,
99 their api is constant, and can only be added to- never changing the existing
100 functionality. This obviously is quite limiting, and leads to cruft accruing in
101 eclasses as a eclasses design is refined. This needs to be dealt with prior to
102 eclass code reaching a critical mass where they become unmanageable/fragile
103 (recent pushes for eclass versioning could be interpreted as proof of this).</p>
104 <p>Beyond that, eclasses were originally intended as a method to allow for ebuilds
105 to use a pre-existing block of code, rather then having to duplicate the code in
106 each ebuild. This is a good thing, but there are ill effects that result from
107 the current design. Eclasses inherit other eclasses to get a single function- in
108 doing so, modifying the the exported 'template' (default src_compile, default
109 src_unpack, various vars, etc). All the eclass designer was after was reusing a
110 function, not making their eclass sensitive to changes in the template of the
111 eclass it's inheriting. The eclass designer -should- be aware of changes in the
112 function they're using, but shouldn't have to worry about their default src_*
113 and pkg_* functions being overwritten, let alone the env changes.</p>
114 <p>Addressing up front why a collection of eclass refinements are being rolled into
115 a single set of changes, parts of this proposal -could- be split into multiple
116 phases. Why do it though? It's simpler for developers to know that the first
117 eclass specification was this, and that the second specification is that,
118 rather then requiring them to be aware of what phase of eclass changes is in
119 progress.</p>
120 <p>By rolling all changes into one large change, a line is intentionally drawn in
121 the sand. Old eclasses allowed for this, behaved this way. New eclasses allow
122 for that, and behave this way. This should reduce misconceptions about what is
123 allowed/possible with eclasses, thus reducing bugs that result from said
124 misconceptions.</p>
125 <p>A few words on elibs- think of them as a clear definition between behavioral
126 functionality of an eclass, and the library functionality. Eclass's modify
127 template data, and are the basis for other ebuilds- elibs, however are <em>just</em>
128 common bash functionality.</p>
129 <p>Consider the majority of the portage bin/* scripts- these all are candidates for
130 being added to the tree as elibs, as is the bulk of eutils.</p>
131 </div>
132 <div class="section" id="specification">
133 <h1><a class="toc-backref" href="#id6" name="specification">Specification</a></h1>
134 <p>The various parts of this proposal are broken down into a set of changes and
135 elaborations on why a proposed change is preferable. It's advisable to the
136 reader that this be read serially, rather then jumping around.</p>
137 <div class="section" id="ebuild-libraries-elibs-for-short">
138 <h2><a class="toc-backref" href="#id7" name="ebuild-libraries-elibs-for-short">Ebuild Libraries (elibs for short)</a></h2>
139 <p>As briefly touched upon in Motivation and Rationale, the original eclass design
140 allowed for the eclass to modify the metadata of an ebuild, metadata being the
141 DEPENDS, RDEPENDS, SRC_URI, IUSE, etc, vars that are required to be constant,
142 and used by portage for dep resolution, fetching, etc. Using the earlier
143 example, if you're after a single function from an eclass (say epatch from
144 eutils), you -don't- want the metadata modifications the eclass you're
145 inheriting might do. You want to treat the eclass you're pulling from as a
146 library, pure and simple.</p>
147 <p>A new directory named elib should be added to the top level of the tree to serve
148 as a repository of ebuild function libraries. Rather then relying on using the
149 source command, an 'elib' function should be added to portage to import that
150 libraries functionality. The reason for the indirection via the function is
151 mostly related to portage internals, but it does serve as an abstraction such
152 that (for example) zsh compatibility hacks could be hidden in the elib function.</p>
153 <p>Elib's will be collections of bash functions- they're not allowed to do anything
154 in the global scope aside from function definition, and any -minimal-
155 initialization of the library that is absolutely needed. Additionally, they
156 cannot modify any ebuild template functions- src_compile, src_unpack. Since they are
157 required to not modify the metadata keys, nor in any way affect the ebuild aside
158 from providing functionality, they can be conditionally pulled in. They also
159 are allowed to pull in other elibs, but strictly just elibs- no eclasses, just
160 other elibs. A real world example would be the eutils eclass.</p>
161 <p>Portage, since the elib's don't modify metadata, isn't required to track elibs
162 as it tracks eclasses. Thus a change in an elib doesn't result in half the tree
163 forced to be regenerated/marked stale when changed (this is more of an infra
164 benefit, although regen's that take too long due to eclass changes have been
165 known to cause rsync issues due to missing timestamps).</p>
166 <p>Elibs will not be available in the global scope of an eclass, or ebuild- nor during the
167 depends phase (basically a phase that sources the ebuild, to get its metadata). Elib
168 calls in the global scope will be tracked, but the elib will not be loaded till just before
169 the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are
170 completely incapable of modifying metadata. There is no room for confusion, late loading
171 of elibs gives you the functionality for all phases, except for depends- depends being the
172 only phase that is capable of specifying metadata. Second, as an added bonus, late
173 loading reduces the amount of bash sourced for a regen- faster regens. This however is minor,
174 and is an ancillary benefit of the first reason.</p>
175 <p>There are a few further restrictions with elibs--mainly, elibs to load can only be specified
176 in either global scope, or in the setup, unpack, compile, test, and install phases. You can
177 not load elibs in prerm, postrm, preinst, and postinst. The reason being, for *rm phases,
178 installed pkgs will have to look to the tree for the elib, which allows for api drift to cause
179 breakage. For *inst phases, same thing, except the culprit is binpkgs.</p>
180 <p>There is a final restriction--elibs cannot change their exported api dependent on the api
181 (as some eclass do for example). The reason mainly being that elibs are loaded once--not
182 multiple times, as eclasses are.</p>
183 <p>To clarify, for example this is invalid.</p>
184 <pre class="literal-block">
185 if [[ -n ${SOME_VAR} ]]; then
186 func x() { echo &quot;I'm accessible only via tweaking some var&quot;;}
187 else
188 func x() { echo &quot;this is invalid, do not do it.&quot;; }
189 fi
190 </pre>
191 <p>Regarding maintainability of elibs, it should be a less of a load then old
192 eclasses. One of the major issues with old eclasses is that their functions are
193 quite incestuous- they're bound tightly to the env they're defined in. This
194 makes eclass functions a bit fragile- the restrictions on what can, and cannot
195 be done in elibs will address this, making functionality less fragile (thus a
196 bit more maintainable).</p>
197 <p>There is no need for backwards compatibility with elibs- they just must work
198 against the current tree. Thus elibs can be removed when the tree no longer
199 needs them. The reasons for this are explained below.</p>
200 <p>Structuring of the elibs directory will be exactly the same as that of the new
201 eclass directory (detailed below), sans a different extension.</p>
202 <p>As to why their are so many restrictions, the answer is simple- the definition of
203 what elibs are, what they are capable of, and how to use them is nailed down as much as
204 possible to avoid <em>any</em> ambiguity related to them. The intention is to make it clear,
205 such that no misconceptions occur, resulting in bugs.</p>
206 </div>
207 <div class="section" id="the-reduced-role-of-eclasses-and-a-clarification-of-existing-eclass-requirements">
208 <h2><a class="toc-backref" href="#id8" name="the-reduced-role-of-eclasses-and-a-clarification-of-existing-eclass-requirements">The reduced role of Eclasses, and a clarification of existing Eclass requirements</a></h2>
209 <p>Since elibs are now intended on holding common bash functionality, the focus of
210 eclasses should be in defining an appropriate template for ebuilds. For example,
211 defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc.
212 Additionally, eclasses should pull in any elibs they need for functionality.</p>
213 <p>Eclass functionality that isn't directly related to the metadata, or src_* and
214 pkg_* funcs should be shifted into elibs to allow for maximal code reuse. This
215 however isn't a hard requirement, merely a strongly worded suggestion.</p>
216 <p>Previously, it was 'strongly' suggested by developers to avoid having any code
217 executed in the global scope that wasn't required. This suggestion is now a
218 requirement. Execute only what must be executed in the global scope. Any code
219 executed in the global scope that is related to configuring/building the package
220 must be placed in pkg_setup. Metadata keys (already a rule, but now stated as
221 an absolute requirement to clarify it) <em>must</em> be constant. The results of
222 metadata keys exported from an ebuild on system A, must be <em>exactly</em> the same as
223 the keys exported on system B.</p>
224 <p>If an eclass (or ebuild for that matter) violates this constant requirement, it
225 leads to portage doing the wrong thing for rsync users- for example, wrong deps
226 pulled in, leading to compilation failure, or dud deps.</p>
227 <p>If the existing metadata isn't flexible enough for what is required for a
228 package, the parsing of the metadata is changed to address that. Cases where
229 the constant requirement is violated are known, and a select few are allowed-
230 these are exceptions to the rule that are required due to inadequacies in
231 portage. Any case where it's determined the constant requirement may need to be
232 violated the dev must make it aware to the majority of devs, along with the portage
233 devs. This should be done prior to committing.</p>
234 <p>It's quite likely there is a way to allow what you're attempting- if you just go
235 and do it, the rsync users (our user base) suffer the results of compilation
236 failures and unneeded deps being pulled in.</p>
237 <p>After that stern reminder, back to new eclasses. Defining INHERITED and ECLASS
238 within the eclass is no longer required. Portage already handles those vars if
239 they aren't defined.</p>
240 <p>As with elibs, it's no longer required that backwards compatibility be maintained
241 indefinitely- compatibility must be maintained against the current tree, but
242 just that. As such new eclasses (the true distinction of new vs old is
243 elaborated in the next section) can be removed from the tree once they're no
244 longer in use.</p>
245 </div>
246 <div class="section" id="the-end-of-backwards-compatibility">
247 <h2><a class="toc-backref" href="#id9" name="the-end-of-backwards-compatibility">The end of backwards compatibility...</a></h2>
248 <p>With current eclasses, once the eclass is in use, its api can no longer be
249 changed, nor can the eclass ever be removed from the tree. This is why we still
250 have <em>ancient</em> eclasses that are completely unused sitting in the tree, for
251 example inherit.eclass. The reason for this, not surprisingly, is a portage
252 deficiency: on unmerging an installed ebuild, portage used the eclass from the
253 current tree.</p>
254 <p>For a real world example of this, if you merged a glibc 2 years back, whatever
255 eclasses it used must still be compatible, or you may not be able to unmerge the
256 older glibc version during an upgrade to a newer version. So either the glibc
257 maintainer is left with the option of leaving people using ancient versions out
258 in the rain, or maintaining an ever increasing load of backwards compatibility
259 cruft in any used eclasses.</p>
260 <p>Binpkgs suffer a similar fate. Merging of a binpkg pulls needed eclasses from
261 the tree, so you may not be able to even merge a binpkg if the eclasses api has
262 changed. If the eclass was removed, you can't even merge the binpkg, period.</p>
263 <p>The next major release of portage will address this- the environment that the
264 ebuild was built in already contains the eclasses functions, as such the env can
265 be re-used rather then relying on the eclass. In other words, binpkgs and
266 installed ebuilds will no longer go and pull needed eclasses from the tree,
267 they'll use the 'saved' version of the eclass they were built/merged with.</p>
268 <p>So the backwards compatibility requirement for users of the next major portage
269 version (and beyond) isn't required. All the cruft can be dropped.</p>
270 <p>The problem is that there will be users using older versions of portage that don't
271 support this functionality- these older installations <em>cannot</em> use the
272 new eclasses, due to the fact that their portage version is incapable of
273 properly relying on the env- in other words, the varying api of the eclass will
274 result in user-visible failures during unmerging.</p>
275 <p>So we're able to do a clean break of all old eclasses, and api cruft, but we need
276 a means to basically disallow access to the new eclasses for all portage versions
277 incapable of properly handling the env requirements.</p>
278 <p>Unfortunately, we cannot just rely on a different grouping/naming convention within
279 the old eclass directory. The new eclasses must be inaccessible, and portage throws
280 a snag into this- the existing inherit function that is used to handle existing
281 eclasses. Basically, whatever it's passed (inherit kernel or inherit
282 kernel/kernel) it will pull in (kernel.eclass, and kernel/kernel.eclass
283 respectively). So even if the new eclasses were implemented within a
284 subdirectory of the eclass dir in the tree, all current portage versions would
285 still be able to access them.</p>
286 <p>In other words, these new eclasses would in effect, be old eclasses since older
287 portage versions could still access them.</p>
288 </div>
289 <div class="section" id="tree-restructuring">
290 <h2><a class="toc-backref" href="#id10" name="tree-restructuring">Tree restructuring</a></h2>
291 <p>There are only two way to block the existing (as of this writing) inherit
292 functionality from accessing the new eclasses- either change the extension of
293 eclasses to something other then 'eclass', or to have them stored in a separate
294 subdirectory of the tree then eclass.</p>
295 <p>The latter is preferable, and the proposed solution. Reasons are- the current
296 eclass directory is already overgrown. Structuring of the new eclass dir
297 (clarified below) will allow for easier signing, ChangeLogs, and grouping of
298 eclasses. New eclasses allow for something akin to a clean break and have new
299 capabilities/requirements, thus it's advisable to start with a clean directory,
300 devoid of all cruft from the old eclass implementation.</p>
301 <p>If it's unclear as to why the old inherit function <em>cannot</em> access the new
302 eclasses, please reread the previous section. It's unfortunately a requirement
303 to take advantage of all that the next major portage release will allow.</p>
304 <p>The proposed directory structure is ${PORTDIR}/include/{eclass,elib}.
305 Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used
306 (although many would cringe at the -ng), but such a name is unwise. Consider the
307 possibility (likely a fact) that new eclasses someday may be found lacking, and
308 refined further (version three as it were). Or perhaps we want to add yet more
309 functionality with direct relation to sourcing new files, and we would then need
310 to further populate ${PORTDIR}.</p>
311 <p>The new-eclass directory will be (at least) 2 levels deep- for example:</p>
312 <dl class="docutils">
313 <dt>::</dt>
314 <dd>kernel/
315 kernel/linux-info.eclass
316 kernel/linux-mod.eclass
317 kernel/kernel-2.6.eclass
318 kernel/kernel-2.4.eclass
319 kernel/ChangeLog
320 kernel/Manifest</dd>
321 </dl>
322 <p>No eclasses will be allowed in the base directory- grouping of new eclasses will
323 be required to help keep things tidy, and for the following reasons. Grouping
324 of eclasses allows for the addition of ChangeLogs that are specific to that
325 group of eclasses, grouping of files/patches as needed, and allows for
326 saner/easier signing of eclasses- you can just stick a signed
327 Manifest file w/in that grouping, thus providing the information portage needs
328 to ensure no files are missing, and that nothing has been tainted.</p>
329 <p>The elib directory will be structured in the same way, for the same reasons.</p>
330 <p>Repoman will have to be extended to work within new eclass and elib groups, and
331 to handle signing and committing. This is intentional, and a good thing. This
332 gives repoman the possibility of doing sanity checks on elibs/new eclasses.</p>
333 <p>Note these checks will not prevent developers from doing dumb things with eclass-
334 these checks would only be capable of doing basic sanity checks, such as syntax checks.
335 There is no way to prevent people from doing dumb things (exempting perhaps repeated
336 applications of a cattle prod)- these are strictly automatic checks, akin to repoman's
337 dependency checks.</p>
338 </div>
339 <div class="section" id="the-start-of-a-different-phase-of-backwards-compatibility">
340 <h2><a class="toc-backref" href="#id11" name="the-start-of-a-different-phase-of-backwards-compatibility">The start of a different phase of backwards compatibility</a></h2>
341 <p>As clarified above, new eclasses will exist in a separate directory that will be
342 intentionally inaccessible to the inherit function. As such, users of older
343 portage versions <em>will</em> have to upgrade to merge any ebuild that uses elibs/new
344 eclasses. A depend on the next major portage version would transparently handle
345 this for rsync users.</p>
346 <p>There still is the issue of users who haven't upgraded to the required portage
347 version. This is a minor concern frankly- portage releases include new
348 functionality, and bug fixes. If they won't upgrade, it's assumed they have
349 their reasons and are big boys, thus able to handle the complications themselves.</p>
350 <p>The real issue is broken envs, whether in binpkgs, or for installed packages.
351 Two options exist- either the old eclasses are left in the tree indefinitely, or
352 they're left for N months, then shifted out of the tree, and into a tarball that
353 can be merged.</p>
354 <p>Shifting them out of the tree is advisable for several reasons- less cruft in
355 the tree, but more importantly the fact that they are not signed (thus an angle
356 for attack). Note that the proposed method of eclass signing doesn't even try
357 to address them. Frankly, it's not worth the effort supporting two variations
358 of eclass signing, when the old eclass setup isn't designed to allow for easy
359 signing.</p>
360 <p>If this approach is taken, then either the old eclasses would have to be merged
361 to an overlay directory's eclass directory (ugly), or to a safe location that
362 portage's inherit function knows to look for (less ugly).</p>
363 <p>For users who do not upgrade within the window of N months while the old
364 eclasses are in the tree, as stated, it's assumed they know what they are doing.
365 If they specifically block the new portage version, as the ebuilds in the tree
366 migrate to the new eclasses, they will have less and less ebuilds available to
367 them. If they tried injecting the new portage version (lying to portage,
368 essentially), portage would bail since it cannot find the new eclass.
369 For ebuilds that use the new eclasses, there really isn't any way to sidestep
370 the portage version requirement- same as it has been for other portage features.</p>
371 <p>What is a bit more annoying is that once the old eclasses are out of the tree,
372 if a user has not upgraded to a portage version supporting env processing, they
373 will lose the ability to unmerge any installed ebuild that used an old
374 eclass. Same cause, different symptom being they will lose the ability to merge
375 any tbz2 that uses old eclasses also.</p>
376 <p>There is one additional case that is a rarity, but should be noted- if a user
377 has suffered significant corruption of their installed package database (vdb). This is
378 ignoring the question of whether the vdb is even usable at this point, but the possibility
379 exists for the saved envs to be non usable due to either A) missing, or B) corrupted.
380 In such a case, even with the new portage capabilities, they would need
381 the old eclass compat ebuild.</p>
382 <p>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.</p>
389 <p>Continuing with the more likely scenario, users unwilling to upgrade portage will
390 <em>not</em> be left out in the rain. Merging the old eclass compat ebuild will provide
391 the missing eclasses, thus providing that lost functionality.</p>
392 <p>Note the intention isn't to force them to upgrade, hence the ability to restore the
393 lost functionality. The intention is to clean up the existing mess, and allow us
394 to move forward. The saying &quot;you've got to break a few eggs to make an omelet&quot;
395 is akin, exempting the fact we're providing a way to make the eggs whole again
396 (the king's men would've loved such an option).</p>
397 </div>
398 <div class="section" id="migrating-to-the-new-setup">
399 <h2><a class="toc-backref" href="#id12" name="migrating-to-the-new-setup">Migrating to the new setup</a></h2>
400 <p>As has been done in the past whenever a change in the tree results in ebuilds
401 requiring a specific version of portage, as ebuilds migrate to the new eclasses,
402 they should depend on a version of portage that supports it. From the users
403 viewpoint, this transparently handles the migration.</p>
404 <p>This isn't so transparent for devs or a particular infrastructure server however.
405 Devs, due to them using cvs for their tree, lack the pregenerated cache rsync
406 users have. Devs will have to be early adopters of the new portage. Older
407 portage versions won't be able to access the new eclasses, thus the local cache
408 generation for that ebuild will fail, ergo the depends on a newer portage
409 version won't transparently handle it for them.</p>
410 <p>Additionally, prior to any ebuilds in the tree using the new eclasses, the
411 infrastructure server that generates the cache for rsync users will have to
412 either be upgraded to a version of portage supporting new eclasses, or patched.
413 The former being much more preferable then the latter for the portage devs.</p>
414 <p>Beyond that, an appropriate window for old eclasses to exist in the tree must be
415 determined, and prior to that window passing, an ebuild must be added to the tree
416 so users can get the old eclasses if needed.</p>
417 <p>For eclass devs to migrate from old to new, it is possible for them to just
418 transfer the old eclass into an appropriate grouping in the new eclass directory,
419 although it's advisable they cleanse all cruft out of the eclass. You can
420 migrate ebuilds gradually over to the new eclass, and don't have to worry about
421 having to support ebuilds from X years back.</p>
422 <p>Essentially, you have a chance to nail the design perfectly/cleanly, and have a
423 window in which to redesign it. It's humbly suggested eclass devs take
424 advantage of it. :)</p>
425 </div>
426 </div>
427 <div class="section" id="backwards-compatibility">
428 <h1><a class="toc-backref" href="#id13" name="backwards-compatibility">Backwards Compatibility</a></h1>
429 <p>All backwards compatibility issues are addressed in line, but a recap is offered-
430 it's suggested that if the a particular compatibility issue is
431 questioned/worried over, the reader read the relevant section. There should be
432 a more in depth discussion of the issue, along with a more extensive explanation
433 of the potential solutions, and reasons for the chosen solution.</p>
434 <p>To recap:</p>
435 <pre class="literal-block">
436 New eclasses and elib functionality will be tied to a specific portage
437 version. A DEPENDs on said portage version should address this for rsync
438 users who refuse to upgrade to a portage version that supports the new
439 eclasses/elibs and will gradually be unable to merge ebuilds that use said
440 functionality. It is their choice to upgrade, as such, the gradual
441 'thinning' of available ebuilds should they block the portage upgrade is
442 their responsibility.
443
444 Old eclasses at some point in the future should be removed from the tree,
445 and released in a tarball/ebuild. This will cause installed ebuilds that
446 rely on the old eclass to be unable to unmerge, with the same applying for
447 merging of binpkgs dependent on the following paragraph.
448
449 The old eclass-compat is only required for users who do not upgrade their
450 portage installation, and one further exemption- if the user has somehow
451 corrupted/destroyed their installed pkgs database (/var/db/pkg currently),
452 in the process, they've lost their saved environments. The eclass-compat
453 ebuild would be required for ebuilds that required older eclasses in such a
454 case. Note, this case is rare also- as clarified above, it's mentioned
455 strictly to be complete, it's not much of a real world scenario as elaborated
456 above.
457 </pre>
458 </div>
459 <div class="section" id="copyright">
460 <h1><a class="toc-backref" href="#id14" name="copyright">Copyright</a></h1>
461 <p>This document has been placed in the public domain.</p>
462 </div>
463
464 </div>
465 <div class="footer">
466 <hr class="footer" />
467 <a class="reference" href="glep-0033.txt">View document source</a>.
468 Generated on: 2005-09-15 21:03 UTC.
469 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
470
471 </div>
472 </body>
473 </html>

  ViewVC Help
Powered by ViewVC 1.1.20