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.4: http://docutils.sourceforge.net/" /> |
12 |
<title>GLEP 33 -- Eclass Restructure/Redesign</title> |
13 |
<style type="text/css"> |
14 |
|
15 |
/* |
16 |
:Author: David Goodger |
17 |
:Contact: goodger@users.sourceforge.net |
18 |
:date: $Date: 2003/06/02 17:03:08 $ |
19 |
:version: $Revision: 1.1 $ |
20 |
:copyright: This stylesheet has been placed in the public domain. |
21 |
|
22 |
Default cascading style sheet for the PEP HTML output of Docutils. |
23 |
*/ |
24 |
|
25 |
.first { |
26 |
margin-top: 0 } |
27 |
|
28 |
.last { |
29 |
margin-bottom: 0 } |
30 |
|
31 |
.navigation { |
32 |
width: 100% ; |
33 |
background: #cc99ff ; |
34 |
margin-top: 0px ; |
35 |
margin-bottom: 0px } |
36 |
|
37 |
.navigation .navicon { |
38 |
width: 150px ; |
39 |
height: 35px } |
40 |
|
41 |
.navigation .textlinks { |
42 |
padding-left: 1em ; |
43 |
text-align: left } |
44 |
|
45 |
.navigation td, .navigation th { |
46 |
padding-left: 0em ; |
47 |
padding-right: 0em ; |
48 |
vertical-align: middle } |
49 |
|
50 |
.rfc2822 { |
51 |
margin-top: 0.5em ; |
52 |
margin-left: 0.5em ; |
53 |
margin-right: 0.5em ; |
54 |
margin-bottom: 0em } |
55 |
|
56 |
.rfc2822 td { |
57 |
text-align: left } |
58 |
|
59 |
.rfc2822 th.field-name { |
60 |
text-align: right ; |
61 |
font-family: sans-serif ; |
62 |
padding-right: 0.5em ; |
63 |
font-weight: bold ; |
64 |
margin-bottom: 0em } |
65 |
|
66 |
a.toc-backref { |
67 |
text-decoration: none ; |
68 |
color: black } |
69 |
|
70 |
body { |
71 |
margin: 0px ; |
72 |
margin-bottom: 1em ; |
73 |
padding: 0px } |
74 |
|
75 |
dd { |
76 |
margin-bottom: 0.5em } |
77 |
|
78 |
div.section { |
79 |
margin-left: 1em ; |
80 |
margin-right: 1em ; |
81 |
margin-bottom: 1.5em } |
82 |
|
83 |
div.section div.section { |
84 |
margin-left: 0em ; |
85 |
margin-right: 0em ; |
86 |
margin-top: 1.5em } |
87 |
|
88 |
div.abstract { |
89 |
margin: 2em 5em } |
90 |
|
91 |
div.abstract p.topic-title { |
92 |
font-weight: bold ; |
93 |
text-align: center } |
94 |
|
95 |
div.attention, div.caution, div.danger, div.error, div.hint, |
96 |
div.important, div.note, div.tip, div.warning { |
97 |
margin: 2em ; |
98 |
border: medium outset ; |
99 |
padding: 1em } |
100 |
|
101 |
div.attention p.admonition-title, div.caution p.admonition-title, |
102 |
div.danger p.admonition-title, div.error p.admonition-title, |
103 |
div.warning p.admonition-title { |
104 |
color: red ; |
105 |
font-weight: bold ; |
106 |
font-family: sans-serif } |
107 |
|
108 |
div.hint p.admonition-title, div.important p.admonition-title, |
109 |
div.note p.admonition-title, div.tip p.admonition-title { |
110 |
font-weight: bold ; |
111 |
font-family: sans-serif } |
112 |
|
113 |
div.figure { |
114 |
margin-left: 2em } |
115 |
|
116 |
div.footer, div.header { |
117 |
font-size: smaller } |
118 |
|
119 |
div.footer { |
120 |
margin-left: 1em ; |
121 |
margin-right: 1em } |
122 |
|
123 |
div.system-messages { |
124 |
margin: 5em } |
125 |
|
126 |
div.system-messages h1 { |
127 |
color: red } |
128 |
|
129 |
div.system-message { |
130 |
border: medium outset ; |
131 |
padding: 1em } |
132 |
|
133 |
div.system-message p.system-message-title { |
134 |
color: red ; |
135 |
font-weight: bold } |
136 |
|
137 |
div.topic { |
138 |
margin: 2em } |
139 |
|
140 |
h1 { |
141 |
font-family: sans-serif ; |
142 |
font-size: large } |
143 |
|
144 |
h2 { |
145 |
font-family: sans-serif ; |
146 |
font-size: medium } |
147 |
|
148 |
h3 { |
149 |
font-family: sans-serif ; |
150 |
font-size: small } |
151 |
|
152 |
h4 { |
153 |
font-family: sans-serif ; |
154 |
font-style: italic ; |
155 |
font-size: small } |
156 |
|
157 |
h5 { |
158 |
font-family: sans-serif; |
159 |
font-size: x-small } |
160 |
|
161 |
h6 { |
162 |
font-family: sans-serif; |
163 |
font-style: italic ; |
164 |
font-size: x-small } |
165 |
|
166 |
.section hr { |
167 |
width: 75% } |
168 |
|
169 |
ol.simple, ul.simple { |
170 |
margin-bottom: 1em } |
171 |
|
172 |
ol.arabic { |
173 |
list-style: decimal } |
174 |
|
175 |
ol.loweralpha { |
176 |
list-style: lower-alpha } |
177 |
|
178 |
ol.upperalpha { |
179 |
list-style: upper-alpha } |
180 |
|
181 |
ol.lowerroman { |
182 |
list-style: lower-roman } |
183 |
|
184 |
ol.upperroman { |
185 |
list-style: upper-roman } |
186 |
|
187 |
p.caption { |
188 |
font-style: italic } |
189 |
|
190 |
p.credits { |
191 |
font-style: italic ; |
192 |
font-size: smaller } |
193 |
|
194 |
p.label { |
195 |
white-space: nowrap } |
196 |
|
197 |
p.topic-title { |
198 |
font-family: sans-serif ; |
199 |
font-weight: bold } |
200 |
|
201 |
pre.line-block { |
202 |
font-family: serif ; |
203 |
font-size: 100% } |
204 |
|
205 |
pre.literal-block, pre.doctest-block { |
206 |
margin-left: 2em ; |
207 |
margin-right: 2em ; |
208 |
background-color: #eeeeee } |
209 |
|
210 |
span.classifier { |
211 |
font-family: sans-serif ; |
212 |
font-style: oblique } |
213 |
|
214 |
span.classifier-delimiter { |
215 |
font-family: sans-serif ; |
216 |
font-weight: bold } |
217 |
|
218 |
span.interpreted { |
219 |
font-family: sans-serif } |
220 |
|
221 |
span.option-argument { |
222 |
font-style: italic } |
223 |
|
224 |
span.pre { |
225 |
white-space: pre } |
226 |
|
227 |
span.problematic { |
228 |
color: red } |
229 |
|
230 |
table { |
231 |
margin-top: 0.5em ; |
232 |
margin-bottom: 0.5em } |
233 |
|
234 |
td, th { |
235 |
padding-left: 0.5em ; |
236 |
padding-right: 0.5em ; |
237 |
vertical-align: top } |
238 |
|
239 |
td.num { |
240 |
text-align: right } |
241 |
|
242 |
th.field-name { |
243 |
font-weight: bold ; |
244 |
text-align: left ; |
245 |
white-space: nowrap } |
246 |
|
247 |
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { |
248 |
font-size: 100% } |
249 |
|
250 |
tt { |
251 |
background-color: #eeeeee } |
252 |
|
253 |
ul.auto-toc { |
254 |
list-style-type: none } |
255 |
|
256 |
</style> |
257 |
</head> |
258 |
<body bgcolor="white"> |
259 |
<table class="navigation" cellpadding="0" cellspacing="0" |
260 |
width="100%" border="0"> |
261 |
<tr><td class="navicon" width="150" height="35"> |
262 |
<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page"> |
263 |
<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]" |
264 |
border="0" width="150" height="35" /></a></td> |
265 |
<td class="textlinks" align="left"> |
266 |
[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>] |
267 |
[<b><a href="http://www.gentoo.org/peps">GLEP Index</a></b>] |
268 |
[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0033.txt">GLEP Source</a></b>] |
269 |
</td></tr></table> |
270 |
<table class="rfc2822 docutils field-list" frame="void" rules="none"> |
271 |
<col class="field-name" /> |
272 |
<col class="field-body" /> |
273 |
<tbody valign="top"> |
274 |
<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">33</td> |
275 |
</tr> |
276 |
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Eclass Restructure/Redesign</td> |
277 |
</tr> |
278 |
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.6</td> |
279 |
</tr> |
280 |
<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.cgi/xml/htdocs/proj/en/glep/glep-0033.txt?cvsroot=gentoo">2006/09/05 20:54:30</a></td> |
281 |
</tr> |
282 |
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Brian Harring <ferringb at gentoo.org>, John Mylchreest <johnm at gentoo.org></td> |
283 |
</tr> |
284 |
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Moribund</td> |
285 |
</tr> |
286 |
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> |
287 |
</tr> |
288 |
<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference" href="glep-0002.html">text/x-rst</a></td> |
289 |
</tr> |
290 |
<tr class="field"><th class="field-name">Created:</th><td class="field-body">29-Jan-2005</td> |
291 |
</tr> |
292 |
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">29-Jan-2005 6-Mar-2005 15-Sep-2005 5-Sep-2006</td> |
293 |
</tr> |
294 |
</tbody> |
295 |
</table> |
296 |
<hr /> |
297 |
<div class="contents topic"> |
298 |
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> |
299 |
<ul class="simple"> |
300 |
<li><a class="reference" href="#status" id="id2" name="id2">Status</a></li> |
301 |
<li><a class="reference" href="#abstract" id="id3" name="id3">Abstract</a></li> |
302 |
<li><a class="reference" href="#terminology" id="id4" name="id4">Terminology</a></li> |
303 |
<li><a class="reference" href="#motivation-and-rationale" id="id5" name="id5">Motivation and Rationale</a></li> |
304 |
<li><a class="reference" href="#specification" id="id6" name="id6">Specification</a><ul> |
305 |
<li><a class="reference" href="#ebuild-libraries-elibs-for-short" id="id7" name="id7">Ebuild Libraries (elibs for short)</a></li> |
306 |
<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> |
307 |
<li><a class="reference" href="#the-end-of-backwards-compatibility" id="id9" name="id9">The end of backwards compatibility...</a></li> |
308 |
<li><a class="reference" href="#tree-restructuring" id="id10" name="id10">Tree restructuring</a></li> |
309 |
<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> |
310 |
<li><a class="reference" href="#migrating-to-the-new-setup" id="id12" name="id12">Migrating to the new setup</a></li> |
311 |
</ul> |
312 |
</li> |
313 |
<li><a class="reference" href="#backwards-compatibility" id="id13" name="id13">Backwards Compatibility</a></li> |
314 |
<li><a class="reference" href="#copyright" id="id14" name="id14">Copyright</a></li> |
315 |
</ul> |
316 |
</div> |
317 |
<div class="section"> |
318 |
<h1><a class="toc-backref" href="#id2" id="status" name="status">Status</a></h1> |
319 |
<p>Approved by the Gentoo Council on 15 September 2005. As of Sept. 2006 |
320 |
this GLEP is on hold, pending future revisions.</p> |
321 |
</div> |
322 |
<div class="section"> |
323 |
<h1><a class="toc-backref" href="#id3" id="abstract" name="abstract">Abstract</a></h1> |
324 |
<p>For any design, the transition from theoretical to applied exposes inadequacies |
325 |
in the original design. This document is intended to document, and propose a |
326 |
revision of the current eclass setup to address current eclass inadequacies.</p> |
327 |
<p>This document proposes several things- the creation of ebuild libraries, 'elibs', |
328 |
a narrowing of the focus of eclasses, a move of eclasses w/in the tree, the |
329 |
addition of changelogs, and a way to allow for simple eclass gpg signing. |
330 |
In general, a large scale restructuring of what eclasses are and how they're |
331 |
implemented. Essentially version two of the eclass setup.</p> |
332 |
</div> |
333 |
<div class="section"> |
334 |
<h1><a class="toc-backref" href="#id4" id="terminology" name="terminology">Terminology</a></h1> |
335 |
<p>From this point on, the proposed eclass setup will be called 'new eclasses', the |
336 |
existing crop (as of this writing) will be referenced as 'old eclasses'. The |
337 |
distinction is elaborated on within this document.</p> |
338 |
</div> |
339 |
<div class="section"> |
340 |
<h1><a class="toc-backref" href="#id5" id="motivation-and-rationale" name="motivation-and-rationale">Motivation and Rationale</a></h1> |
341 |
<p>Eclasses within the tree currently are a bit of a mess- they're forced to |
342 |
maintain backwards compatibility w/ all previous functionality. In effect, |
343 |
their api is constant, and can only be added to- never changing the existing |
344 |
functionality. This obviously is quite limiting, and leads to cruft accruing in |
345 |
eclasses as a eclasses design is refined. This needs to be dealt with prior to |
346 |
eclass code reaching a critical mass where they become unmanageable/fragile |
347 |
(recent pushes for eclass versioning could be interpreted as proof of this).</p> |
348 |
<p>Beyond that, eclasses were originally intended as a method to allow for ebuilds |
349 |
to use a pre-existing block of code, rather then having to duplicate the code in |
350 |
each ebuild. This is a good thing, but there are ill effects that result from |
351 |
the current design. Eclasses inherit other eclasses to get a single function- in |
352 |
doing so, modifying the the exported 'template' (default src_compile, default |
353 |
src_unpack, various vars, etc). All the eclass designer was after was reusing a |
354 |
function, not making their eclass sensitive to changes in the template of the |
355 |
eclass it's inheriting. The eclass designer -should- be aware of changes in the |
356 |
function they're using, but shouldn't have to worry about their default src_* |
357 |
and pkg_* functions being overwritten, let alone the env changes.</p> |
358 |
<p>Addressing up front why a collection of eclass refinements are being rolled into |
359 |
a single set of changes, parts of this proposal -could- be split into multiple |
360 |
phases. Why do it though? It's simpler for developers to know that the first |
361 |
eclass specification was this, and that the second specification is that, |
362 |
rather then requiring them to be aware of what phase of eclass changes is in |
363 |
progress.</p> |
364 |
<p>By rolling all changes into one large change, a line is intentionally drawn in |
365 |
the sand. Old eclasses allowed for this, behaved this way. New eclasses allow |
366 |
for that, and behave this way. This should reduce misconceptions about what is |
367 |
allowed/possible with eclasses, thus reducing bugs that result from said |
368 |
misconceptions.</p> |
369 |
<p>A few words on elibs- think of them as a clear definition between behavioral |
370 |
functionality of an eclass, and the library functionality. Eclass's modify |
371 |
template data, and are the basis for other ebuilds- elibs, however are <em>just</em> |
372 |
common bash functionality.</p> |
373 |
<p>Consider the majority of the portage bin/* scripts- these all are candidates for |
374 |
being added to the tree as elibs, as is the bulk of eutils.</p> |
375 |
</div> |
376 |
<div class="section"> |
377 |
<h1><a class="toc-backref" href="#id6" id="specification" name="specification">Specification</a></h1> |
378 |
<p>The various parts of this proposal are broken down into a set of changes and |
379 |
elaborations on why a proposed change is preferable. It's advisable to the |
380 |
reader that this be read serially, rather then jumping around.</p> |
381 |
<div class="section"> |
382 |
<h2><a class="toc-backref" href="#id7" id="ebuild-libraries-elibs-for-short" name="ebuild-libraries-elibs-for-short">Ebuild Libraries (elibs for short)</a></h2> |
383 |
<p>As briefly touched upon in Motivation and Rationale, the original eclass design |
384 |
allowed for the eclass to modify the metadata of an ebuild, metadata being the |
385 |
DEPENDS, RDEPENDS, SRC_URI, IUSE, etc, vars that are required to be constant, |
386 |
and used by portage for dep resolution, fetching, etc. Using the earlier |
387 |
example, if you're after a single function from an eclass (say epatch from |
388 |
eutils), you -don't- want the metadata modifications the eclass you're |
389 |
inheriting might do. You want to treat the eclass you're pulling from as a |
390 |
library, pure and simple.</p> |
391 |
<p>A new directory named elib should be added to the top level of the tree to serve |
392 |
as a repository of ebuild function libraries. Rather then relying on using the |
393 |
source command, an 'elib' function should be added to portage to import that |
394 |
libraries functionality. The reason for the indirection via the function is |
395 |
mostly related to portage internals, but it does serve as an abstraction such |
396 |
that (for example) zsh compatibility hacks could be hidden in the elib function.</p> |
397 |
<p>Elib's will be collections of bash functions- they're not allowed to do anything |
398 |
in the global scope aside from function definition, and any -minimal- |
399 |
initialization of the library that is absolutely needed. Additionally, they |
400 |
cannot modify any ebuild template functions- src_compile, src_unpack. Since they are |
401 |
required to not modify the metadata keys, nor in any way affect the ebuild aside |
402 |
from providing functionality, they can be conditionally pulled in. They also |
403 |
are allowed to pull in other elibs, but strictly just elibs- no eclasses, just |
404 |
other elibs. A real world example would be the eutils eclass.</p> |
405 |
<p>Portage, since the elib's don't modify metadata, isn't required to track elibs |
406 |
as it tracks eclasses. Thus a change in an elib doesn't result in half the tree |
407 |
forced to be regenerated/marked stale when changed (this is more of an infra |
408 |
benefit, although regen's that take too long due to eclass changes have been |
409 |
known to cause rsync issues due to missing timestamps).</p> |
410 |
<p>Elibs will not be available in the global scope of an eclass, or ebuild- nor during the |
411 |
depends phase (basically a phase that sources the ebuild, to get its metadata). Elib |
412 |
calls in the global scope will be tracked, but the elib will not be loaded till just before |
413 |
the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are |
414 |
completely incapable of modifying metadata. There is no room for confusion, late loading |
415 |
of elibs gives you the functionality for all phases, except for depends- depends being the |
416 |
only phase that is capable of specifying metadata. Second, as an added bonus, late |
417 |
loading reduces the amount of bash sourced for a regen- faster regens. This however is minor, |
418 |
and is an ancillary benefit of the first reason.</p> |
419 |
<p>There are a few further restrictions with elibs--mainly, elibs to load can only be specified |
420 |
in either global scope, or in the setup, unpack, compile, test, and install phases. You can |
421 |
not load elibs in prerm, postrm, preinst, and postinst. The reason being, for *rm phases, |
422 |
installed pkgs will have to look to the tree for the elib, which allows for api drift to cause |
423 |
breakage. For *inst phases, same thing, except the culprit is binpkgs.</p> |
424 |
<p>There is a final restriction--elibs cannot change their exported api dependent on the api |
425 |
(as some eclass do for example). The reason mainly being that elibs are loaded once--not |
426 |
multiple times, as eclasses are.</p> |
427 |
<p>To clarify, for example this is invalid.</p> |
428 |
<pre class="literal-block"> |
429 |
if [[ -n ${SOME_VAR} ]]; then |
430 |
func x() { echo "I'm accessible only via tweaking some var";} |
431 |
else |
432 |
func x() { echo "this is invalid, do not do it."; } |
433 |
fi |
434 |
</pre> |
435 |
<p>Regarding maintainability of elibs, it should be a less of a load then old |
436 |
eclasses. One of the major issues with old eclasses is that their functions are |
437 |
quite incestuous- they're bound tightly to the env they're defined in. This |
438 |
makes eclass functions a bit fragile- the restrictions on what can, and cannot |
439 |
be done in elibs will address this, making functionality less fragile (thus a |
440 |
bit more maintainable).</p> |
441 |
<p>There is no need for backwards compatibility with elibs- they just must work |
442 |
against the current tree. Thus elibs can be removed when the tree no longer |
443 |
needs them. The reasons for this are explained below.</p> |
444 |
<p>Structuring of the elibs directory will be exactly the same as that of the new |
445 |
eclass directory (detailed below), sans a different extension.</p> |
446 |
<p>As to why their are so many restrictions, the answer is simple- the definition of |
447 |
what elibs are, what they are capable of, and how to use them is nailed down as much as |
448 |
possible to avoid <em>any</em> ambiguity related to them. The intention is to make it clear, |
449 |
such that no misconceptions occur, resulting in bugs.</p> |
450 |
</div> |
451 |
<div class="section"> |
452 |
<h2><a class="toc-backref" href="#id8" id="the-reduced-role-of-eclasses-and-a-clarification-of-existing-eclass-requirements" 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> |
453 |
<p>Since elibs are now intended on holding common bash functionality, the focus of |
454 |
eclasses should be in defining an appropriate template for ebuilds. For example, |
455 |
defining common DEPENDS, RDEPENDS, src_compile functions, src_unpack, etc. |
456 |
Additionally, eclasses should pull in any elibs they need for functionality.</p> |
457 |
<p>Eclass functionality that isn't directly related to the metadata, or src_* and |
458 |
pkg_* funcs should be shifted into elibs to allow for maximal code reuse. This |
459 |
however isn't a hard requirement, merely a strongly worded suggestion.</p> |
460 |
<p>Previously, it was 'strongly' suggested by developers to avoid having any code |
461 |
executed in the global scope that wasn't required. This suggestion is now a |
462 |
requirement. Execute only what must be executed in the global scope. Any code |
463 |
executed in the global scope that is related to configuring/building the package |
464 |
must be placed in pkg_setup. Metadata keys (already a rule, but now stated as |
465 |
an absolute requirement to clarify it) <em>must</em> be constant. The results of |
466 |
metadata keys exported from an ebuild on system A, must be <em>exactly</em> the same as |
467 |
the keys exported on system B.</p> |
468 |
<p>If an eclass (or ebuild for that matter) violates this constant requirement, it |
469 |
leads to portage doing the wrong thing for rsync users- for example, wrong deps |
470 |
pulled in, leading to compilation failure, or dud deps.</p> |
471 |
<p>If the existing metadata isn't flexible enough for what is required for a |
472 |
package, the parsing of the metadata is changed to address that. Cases where |
473 |
the constant requirement is violated are known, and a select few are allowed- |
474 |
these are exceptions to the rule that are required due to inadequacies in |
475 |
portage. Any case where it's determined the constant requirement may need to be |
476 |
violated the dev must make it aware to the majority of devs, along with the portage |
477 |
devs. This should be done prior to committing.</p> |
478 |
<p>It's quite likely there is a way to allow what you're attempting- if you just go |
479 |
and do it, the rsync users (our user base) suffer the results of compilation |
480 |
failures and unneeded deps being pulled in.</p> |
481 |
<p>After that stern reminder, back to new eclasses. Defining INHERITED and ECLASS |
482 |
within the eclass is no longer required. Portage already handles those vars if |
483 |
they aren't defined.</p> |
484 |
<p>As with elibs, it's no longer required that backwards compatibility be maintained |
485 |
indefinitely- compatibility must be maintained against the current tree, but |
486 |
just that. As such new eclasses (the true distinction of new vs old is |
487 |
elaborated in the next section) can be removed from the tree once they're no |
488 |
longer in use.</p> |
489 |
</div> |
490 |
<div class="section"> |
491 |
<h2><a class="toc-backref" href="#id9" id="the-end-of-backwards-compatibility" name="the-end-of-backwards-compatibility">The end of backwards compatibility...</a></h2> |
492 |
<p>With current eclasses, once the eclass is in use, its api can no longer be |
493 |
changed, nor can the eclass ever be removed from the tree. This is why we still |
494 |
have <em>ancient</em> eclasses that are completely unused sitting in the tree, for |
495 |
example inherit.eclass. The reason for this, not surprisingly, is a portage |
496 |
deficiency: on unmerging an installed ebuild, portage used the eclass from the |
497 |
current tree.</p> |
498 |
<p>For a real world example of this, if you merged a glibc 2 years back, whatever |
499 |
eclasses it used must still be compatible, or you may not be able to unmerge the |
500 |
older glibc version during an upgrade to a newer version. So either the glibc |
501 |
maintainer is left with the option of leaving people using ancient versions out |
502 |
in the rain, or maintaining an ever increasing load of backwards compatibility |
503 |
cruft in any used eclasses.</p> |
504 |
<p>Binpkgs suffer a similar fate. Merging of a binpkg pulls needed eclasses from |
505 |
the tree, so you may not be able to even merge a binpkg if the eclasses api has |
506 |
changed. If the eclass was removed, you can't even merge the binpkg, period.</p> |
507 |
<p>The next major release of portage will address this- the environment that the |
508 |
ebuild was built in already contains the eclasses functions, as such the env can |
509 |
be re-used rather then relying on the eclass. In other words, binpkgs and |
510 |
installed ebuilds will no longer go and pull needed eclasses from the tree, |
511 |
they'll use the 'saved' version of the eclass they were built/merged with.</p> |
512 |
<p>So the backwards compatibility requirement for users of the next major portage |
513 |
version (and beyond) isn't required. All the cruft can be dropped.</p> |
514 |
<p>The problem is that there will be users using older versions of portage that don't |
515 |
support this functionality- these older installations <em>cannot</em> use the |
516 |
new eclasses, due to the fact that their portage version is incapable of |
517 |
properly relying on the env- in other words, the varying api of the eclass will |
518 |
result in user-visible failures during unmerging.</p> |
519 |
<p>So we're able to do a clean break of all old eclasses, and api cruft, but we need |
520 |
a means to basically disallow access to the new eclasses for all portage versions |
521 |
incapable of properly handling the env requirements.</p> |
522 |
<p>Unfortunately, we cannot just rely on a different grouping/naming convention within |
523 |
the old eclass directory. The new eclasses must be inaccessible, and portage throws |
524 |
a snag into this- the existing inherit function that is used to handle existing |
525 |
eclasses. Basically, whatever it's passed (inherit kernel or inherit |
526 |
kernel/kernel) it will pull in (kernel.eclass, and kernel/kernel.eclass |
527 |
respectively). So even if the new eclasses were implemented within a |
528 |
subdirectory of the eclass dir in the tree, all current portage versions would |
529 |
still be able to access them.</p> |
530 |
<p>In other words, these new eclasses would in effect, be old eclasses since older |
531 |
portage versions could still access them.</p> |
532 |
</div> |
533 |
<div class="section"> |
534 |
<h2><a class="toc-backref" href="#id10" id="tree-restructuring" name="tree-restructuring">Tree restructuring</a></h2> |
535 |
<p>There are only two way to block the existing (as of this writing) inherit |
536 |
functionality from accessing the new eclasses- either change the extension of |
537 |
eclasses to something other then 'eclass', or to have them stored in a separate |
538 |
subdirectory of the tree then eclass.</p> |
539 |
<p>The latter is preferable, and the proposed solution. Reasons are- the current |
540 |
eclass directory is already overgrown. Structuring of the new eclass dir |
541 |
(clarified below) will allow for easier signing, ChangeLogs, and grouping of |
542 |
eclasses. New eclasses allow for something akin to a clean break and have new |
543 |
capabilities/requirements, thus it's advisable to start with a clean directory, |
544 |
devoid of all cruft from the old eclass implementation.</p> |
545 |
<p>If it's unclear as to why the old inherit function <em>cannot</em> access the new |
546 |
eclasses, please reread the previous section. It's unfortunately a requirement |
547 |
to take advantage of all that the next major portage release will allow.</p> |
548 |
<p>The proposed directory structure is ${PORTDIR}/include/{eclass,elib}. |
549 |
Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used |
550 |
(although many would cringe at the -ng), but such a name is unwise. Consider the |
551 |
possibility (likely a fact) that new eclasses someday may be found lacking, and |
552 |
refined further (version three as it were). Or perhaps we want to add yet more |
553 |
functionality with direct relation to sourcing new files, and we would then need |
554 |
to further populate ${PORTDIR}.</p> |
555 |
<p>The new-eclass directory will be (at least) 2 levels deep- for example:</p> |
556 |
<dl class="docutils"> |
557 |
<dt>::</dt> |
558 |
<dd>kernel/ |
559 |
kernel/linux-info.eclass |
560 |
kernel/linux-mod.eclass |
561 |
kernel/kernel-2.6.eclass |
562 |
kernel/kernel-2.4.eclass |
563 |
kernel/ChangeLog |
564 |
kernel/Manifest</dd> |
565 |
</dl> |
566 |
<p>No eclasses will be allowed in the base directory- grouping of new eclasses will |
567 |
be required to help keep things tidy, and for the following reasons. Grouping |
568 |
of eclasses allows for the addition of ChangeLogs that are specific to that |
569 |
group of eclasses, grouping of files/patches as needed, and allows for |
570 |
saner/easier signing of eclasses- you can just stick a signed |
571 |
Manifest file w/in that grouping, thus providing the information portage needs |
572 |
to ensure no files are missing, and that nothing has been tainted.</p> |
573 |
<p>The elib directory will be structured in the same way, for the same reasons.</p> |
574 |
<p>Repoman will have to be extended to work within new eclass and elib groups, and |
575 |
to handle signing and committing. This is intentional, and a good thing. This |
576 |
gives repoman the possibility of doing sanity checks on elibs/new eclasses.</p> |
577 |
<p>Note these checks will not prevent developers from doing dumb things with eclass- |
578 |
these checks would only be capable of doing basic sanity checks, such as syntax checks. |
579 |
There is no way to prevent people from doing dumb things (exempting perhaps repeated |
580 |
applications of a cattle prod)- these are strictly automatic checks, akin to repoman's |
581 |
dependency checks.</p> |
582 |
</div> |
583 |
<div class="section"> |
584 |
<h2><a class="toc-backref" href="#id11" id="the-start-of-a-different-phase-of-backwards-compatibility" name="the-start-of-a-different-phase-of-backwards-compatibility">The start of a different phase of backwards compatibility</a></h2> |
585 |
<p>As clarified above, new eclasses will exist in a separate directory that will be |
586 |
intentionally inaccessible to the inherit function. As such, users of older |
587 |
portage versions <em>will</em> have to upgrade to merge any ebuild that uses elibs/new |
588 |
eclasses. A depend on the next major portage version would transparently handle |
589 |
this for rsync users.</p> |
590 |
<p>There still is the issue of users who haven't upgraded to the required portage |
591 |
version. This is a minor concern frankly- portage releases include new |
592 |
functionality, and bug fixes. If they won't upgrade, it's assumed they have |
593 |
their reasons and are big boys, thus able to handle the complications themselves.</p> |
594 |
<p>The real issue is broken envs, whether in binpkgs, or for installed packages. |
595 |
Two options exist- either the old eclasses are left in the tree indefinitely, or |
596 |
they're left for N months, then shifted out of the tree, and into a tarball that |
597 |
can be merged.</p> |
598 |
<p>Shifting them out of the tree is advisable for several reasons- less cruft in |
599 |
the tree, but more importantly the fact that they are not signed (thus an angle |
600 |
for attack). Note that the proposed method of eclass signing doesn't even try |
601 |
to address them. Frankly, it's not worth the effort supporting two variations |
602 |
of eclass signing, when the old eclass setup isn't designed to allow for easy |
603 |
signing.</p> |
604 |
<p>If this approach is taken, then either the old eclasses would have to be merged |
605 |
to an overlay directory's eclass directory (ugly), or to a safe location that |
606 |
portage's inherit function knows to look for (less ugly).</p> |
607 |
<p>For users who do not upgrade within the window of N months while the old |
608 |
eclasses are in the tree, as stated, it's assumed they know what they are doing. |
609 |
If they specifically block the new portage version, as the ebuilds in the tree |
610 |
migrate to the new eclasses, they will have less and less ebuilds available to |
611 |
them. If they tried injecting the new portage version (lying to portage, |
612 |
essentially), portage would bail since it cannot find the new eclass. |
613 |
For ebuilds that use the new eclasses, there really isn't any way to sidestep |
614 |
the portage version requirement- same as it has been for other portage features.</p> |
615 |
<p>What is a bit more annoying is that once the old eclasses are out of the tree, |
616 |
if a user has not upgraded to a portage version supporting env processing, they |
617 |
will lose the ability to unmerge any installed ebuild that used an old |
618 |
eclass. Same cause, different symptom being they will lose the ability to merge |
619 |
any tbz2 that uses old eclasses also.</p> |
620 |
<p>There is one additional case that is a rarity, but should be noted- if a user |
621 |
has suffered significant corruption of their installed package database (vdb). This is |
622 |
ignoring the question of whether the vdb is even usable at this point, but the possibility |
623 |
exists for the saved envs to be non usable due to either A) missing, or B) corrupted. |
624 |
In such a case, even with the new portage capabilities, they would need |
625 |
the old eclass compat ebuild.</p> |
626 |
<p>Note for this to happen requires either rather... unwise uses of root, or significant |
627 |
fs corruption. Regardless of the cause, it's quite likely for this to even become an |
628 |
issue, the system's vdb is completely unusable. It's a moot issue at that point. |
629 |
If you lose your vdb, or it gets seriously damaged, it's akin to lobotomizing portage- |
630 |
it doesn't know what's installed, it doesn't know of its own files, and in general, |
631 |
a rebuilding of the system is about the only sane course of action. The missing env is |
632 |
truly the least of the users concern in such a case.</p> |
633 |
<p>Continuing with the more likely scenario, users unwilling to upgrade portage will |
634 |
<em>not</em> be left out in the rain. Merging the old eclass compat ebuild will provide |
635 |
the missing eclasses, thus providing that lost functionality.</p> |
636 |
<p>Note the intention isn't to force them to upgrade, hence the ability to restore the |
637 |
lost functionality. The intention is to clean up the existing mess, and allow us |
638 |
to move forward. The saying "you've got to break a few eggs to make an omelet" |
639 |
is akin, exempting the fact we're providing a way to make the eggs whole again |
640 |
(the king's men would've loved such an option).</p> |
641 |
</div> |
642 |
<div class="section"> |
643 |
<h2><a class="toc-backref" href="#id12" id="migrating-to-the-new-setup" name="migrating-to-the-new-setup">Migrating to the new setup</a></h2> |
644 |
<p>As has been done in the past whenever a change in the tree results in ebuilds |
645 |
requiring a specific version of portage, as ebuilds migrate to the new eclasses, |
646 |
they should depend on a version of portage that supports it. From the users |
647 |
viewpoint, this transparently handles the migration.</p> |
648 |
<p>This isn't so transparent for devs or a particular infrastructure server however. |
649 |
Devs, due to them using cvs for their tree, lack the pregenerated cache rsync |
650 |
users have. Devs will have to be early adopters of the new portage. Older |
651 |
portage versions won't be able to access the new eclasses, thus the local cache |
652 |
generation for that ebuild will fail, ergo the depends on a newer portage |
653 |
version won't transparently handle it for them.</p> |
654 |
<p>Additionally, prior to any ebuilds in the tree using the new eclasses, the |
655 |
infrastructure server that generates the cache for rsync users will have to |
656 |
either be upgraded to a version of portage supporting new eclasses, or patched. |
657 |
The former being much more preferable then the latter for the portage devs.</p> |
658 |
<p>Beyond that, an appropriate window for old eclasses to exist in the tree must be |
659 |
determined, and prior to that window passing, an ebuild must be added to the tree |
660 |
so users can get the old eclasses if needed.</p> |
661 |
<p>For eclass devs to migrate from old to new, it is possible for them to just |
662 |
transfer the old eclass into an appropriate grouping in the new eclass directory, |
663 |
although it's advisable they cleanse all cruft out of the eclass. You can |
664 |
migrate ebuilds gradually over to the new eclass, and don't have to worry about |
665 |
having to support ebuilds from X years back.</p> |
666 |
<p>Essentially, you have a chance to nail the design perfectly/cleanly, and have a |
667 |
window in which to redesign it. It's humbly suggested eclass devs take |
668 |
advantage of it. :)</p> |
669 |
</div> |
670 |
</div> |
671 |
<div class="section"> |
672 |
<h1><a class="toc-backref" href="#id13" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1> |
673 |
<p>All backwards compatibility issues are addressed in line, but a recap is offered- |
674 |
it's suggested that if the a particular compatibility issue is |
675 |
questioned/worried over, the reader read the relevant section. There should be |
676 |
a more in depth discussion of the issue, along with a more extensive explanation |
677 |
of the potential solutions, and reasons for the chosen solution.</p> |
678 |
<p>To recap:</p> |
679 |
<pre class="literal-block"> |
680 |
New eclasses and elib functionality will be tied to a specific portage |
681 |
version. A DEPENDs on said portage version should address this for rsync |
682 |
users who refuse to upgrade to a portage version that supports the new |
683 |
eclasses/elibs and will gradually be unable to merge ebuilds that use said |
684 |
functionality. It is their choice to upgrade, as such, the gradual |
685 |
'thinning' of available ebuilds should they block the portage upgrade is |
686 |
their responsibility. |
687 |
|
688 |
Old eclasses at some point in the future should be removed from the tree, |
689 |
and released in a tarball/ebuild. This will cause installed ebuilds that |
690 |
rely on the old eclass to be unable to unmerge, with the same applying for |
691 |
merging of binpkgs dependent on the following paragraph. |
692 |
|
693 |
The old eclass-compat is only required for users who do not upgrade their |
694 |
portage installation, and one further exemption- if the user has somehow |
695 |
corrupted/destroyed their installed pkgs database (/var/db/pkg currently), |
696 |
in the process, they've lost their saved environments. The eclass-compat |
697 |
ebuild would be required for ebuilds that required older eclasses in such a |
698 |
case. Note, this case is rare also- as clarified above, it's mentioned |
699 |
strictly to be complete, it's not much of a real world scenario as elaborated |
700 |
above. |
701 |
</pre> |
702 |
</div> |
703 |
<div class="section"> |
704 |
<h1><a class="toc-backref" href="#id14" id="copyright" name="copyright">Copyright</a></h1> |
705 |
<p>This document has been placed in the public domain.</p> |
706 |
</div> |
707 |
|
708 |
</div> |
709 |
<div class="footer"> |
710 |
<hr class="footer" /> |
711 |
<a class="reference" href="glep-0033.txt">View document source</a>. |
712 |
Generated on: 2006-09-05 20:55 UTC. |
713 |
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. |
714 |
|
715 |
</div> |
716 |
</body> |
717 |
</html> |
718 |
|