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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.6 - (hide annotations) (download) (as text)
Tue Oct 10 20:25:14 2006 UTC (7 years, 6 months ago) by g2boojum
Branch: MAIN
Changes since 1.5: +1 -1 lines
File MIME type: text/html
regenerate all .html files

1 g2boojum 1.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
8     -->
9     <head>
10     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
11 g2boojum 1.5 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
12 g2boojum 1.1 <title>GLEP 33 -- Eclass Restructure/Redesign</title>
13 g2boojum 1.5 <style type="text/css">
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.
22     Default cascading style sheet for the PEP HTML output of Docutils.
23     */
25     .first {
26     margin-top: 0 }
28     .last {
29     margin-bottom: 0 }
31     .navigation {
32     width: 100% ;
33     background: #cc99ff ;
34     margin-top: 0px ;
35     margin-bottom: 0px }
37     .navigation .navicon {
38     width: 150px ;
39     height: 35px }
41     .navigation .textlinks {
42     padding-left: 1em ;
43     text-align: left }
45     .navigation td, .navigation th {
46     padding-left: 0em ;
47     padding-right: 0em ;
48     vertical-align: middle }
50     .rfc2822 {
51     margin-top: 0.5em ;
52     margin-left: 0.5em ;
53     margin-right: 0.5em ;
54     margin-bottom: 0em }
56     .rfc2822 td {
57     text-align: left }
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 }
66     a.toc-backref {
67     text-decoration: none ;
68     color: black }
70     body {
71     margin: 0px ;
72     margin-bottom: 1em ;
73     padding: 0px }
75     dd {
76     margin-bottom: 0.5em }
78     div.section {
79     margin-left: 1em ;
80     margin-right: 1em ;
81     margin-bottom: 1.5em }
83     div.section div.section {
84     margin-left: 0em ;
85     margin-right: 0em ;
86     margin-top: 1.5em }
88     div.abstract {
89     margin: 2em 5em }
91     div.abstract p.topic-title {
92     font-weight: bold ;
93     text-align: center }
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 }
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 }
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 }
113     div.figure {
114     margin-left: 2em }
116     div.footer, div.header {
117     font-size: smaller }
119     div.footer {
120     margin-left: 1em ;
121     margin-right: 1em }
123     div.system-messages {
124     margin: 5em }
126     div.system-messages h1 {
127     color: red }
129     div.system-message {
130     border: medium outset ;
131     padding: 1em }
133     div.system-message p.system-message-title {
134     color: red ;
135     font-weight: bold }
137     div.topic {
138     margin: 2em }
140     h1 {
141     font-family: sans-serif ;
142     font-size: large }
144     h2 {
145     font-family: sans-serif ;
146     font-size: medium }
148     h3 {
149     font-family: sans-serif ;
150     font-size: small }
152     h4 {
153     font-family: sans-serif ;
154     font-style: italic ;
155     font-size: small }
157     h5 {
158     font-family: sans-serif;
159     font-size: x-small }
161     h6 {
162     font-family: sans-serif;
163     font-style: italic ;
164     font-size: x-small }
166     .section hr {
167     width: 75% }
169     ol.simple, ul.simple {
170     margin-bottom: 1em }
172     ol.arabic {
173     list-style: decimal }
175     ol.loweralpha {
176     list-style: lower-alpha }
178     ol.upperalpha {
179     list-style: upper-alpha }
181     ol.lowerroman {
182     list-style: lower-roman }
184     ol.upperroman {
185     list-style: upper-roman }
187     p.caption {
188     font-style: italic }
190     p.credits {
191     font-style: italic ;
192     font-size: smaller }
194     p.label {
195     white-space: nowrap }
197     p.topic-title {
198     font-family: sans-serif ;
199     font-weight: bold }
201     pre.line-block {
202     font-family: serif ;
203     font-size: 100% }
205     pre.literal-block, pre.doctest-block {
206     margin-left: 2em ;
207     margin-right: 2em ;
208     background-color: #eeeeee }
210     span.classifier {
211     font-family: sans-serif ;
212     font-style: oblique }
214     span.classifier-delimiter {
215     font-family: sans-serif ;
216     font-weight: bold }
218     span.interpreted {
219     font-family: sans-serif }
221     span.option-argument {
222     font-style: italic }
224     span.pre {
225     white-space: pre }
227     span.problematic {
228     color: red }
230     table {
231     margin-top: 0.5em ;
232     margin-bottom: 0.5em }
234     td, th {
235     padding-left: 0.5em ;
236     padding-right: 0.5em ;
237     vertical-align: top }
239     td.num {
240     text-align: right }
242     th.field-name {
243     font-weight: bold ;
244     text-align: left ;
245     white-space: nowrap }
247     h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
248     font-size: 100% }
250     tt {
251     background-color: #eeeeee }
253     ul.auto-toc {
254     list-style-type: none }
256     </style>
257 g2boojum 1.1 </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 g2boojum 1.5 [<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 g2boojum 1.1 </td></tr></table>
270 vapier 1.3 <table class="rfc2822 docutils field-list" frame="void" rules="none">
271 g2boojum 1.1 <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 g2boojum 1.5 <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.6</td>
279 g2boojum 1.1 </tr>
280 g2boojum 1.5 <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 g2boojum 1.1 </tr>
282 g2boojum 1.2 <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>
283 g2boojum 1.1 </tr>
284 g2boojum 1.5 <tr class="field"><th class="field-name">Status:</th><td class="field-body">Moribund</td>
285 g2boojum 1.1 </tr>
286     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
287     </tr>
288 g2boojum 1.5 <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 g2boojum 1.1 </tr>
290     <tr class="field"><th class="field-name">Created:</th><td class="field-body">29-Jan-2005</td>
291     </tr>
292 g2boojum 1.5 <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 g2boojum 1.1 </tr>
294     </tbody>
295     </table>
296     <hr />
297 g2boojum 1.5 <div class="contents topic">
298     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
299 g2boojum 1.1 <ul class="simple">
300 g2boojum 1.4 <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 g2boojum 1.1 </ul>
312     </li>
313 g2boojum 1.4 <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 g2boojum 1.1 </ul>
316     </div>
317 g2boojum 1.5 <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 g2boojum 1.1 revision of the current eclass setup to address current eclass inadequacies.</p>
327 g2boojum 1.5 <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 g2boojum 1.1 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 g2boojum 1.5 <div class="section">
334     <h1><a class="toc-backref" href="#id4" id="terminology" name="terminology">Terminology</a></h1>
335 g2boojum 1.1 <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 g2boojum 1.2 distinction is elaborated on within this document.</p>
338 g2boojum 1.1 </div>
339 g2boojum 1.5 <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 g2boojum 1.1 <p>Eclasses within the tree currently are a bit of a mess- they're forced to
342 g2boojum 1.2 maintain backwards compatibility w/ all previous functionality. In effect,
343 g2boojum 1.1 their api is constant, and can only be added to- never changing the existing
344 vapier 1.3 functionality. This obviously is quite limiting, and leads to cruft accruing in
345 g2boojum 1.1 eclasses as a eclasses design is refined. This needs to be dealt with prior to
346 g2boojum 1.2 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 g2boojum 1.1 <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 vapier 1.3 the current design. Eclasses inherit other eclasses to get a single function- in
352 g2boojum 1.1 doing so, modifying the the exported 'template' (default src_compile, default
353 vapier 1.3 src_unpack, various vars, etc). All the eclass designer was after was reusing a
354 g2boojum 1.1 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 g2boojum 1.5 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 g2boojum 1.1 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 vapier 1.3 for that, and behave this way. This should reduce misconceptions about what is
367 g2boojum 1.1 allowed/possible with eclasses, thus reducing bugs that result from said
368     misconceptions.</p>
369 g2boojum 1.5 <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 g2boojum 1.2 common bash functionality.</p>
373 g2boojum 1.5 <p>Consider the majority of the portage bin/* scripts- these all are candidates for
374 g2boojum 1.2 being added to the tree as elibs, as is the bulk of eutils.</p>
375 g2boojum 1.1 </div>
376 g2boojum 1.5 <div class="section">
377     <h1><a class="toc-backref" href="#id6" id="specification" name="specification">Specification</a></h1>
378 g2boojum 1.1 <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 g2boojum 1.5 <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 g2boojum 1.1 <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 g2boojum 1.5 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 g2boojum 1.2 that (for example) zsh compatibility hacks could be hidden in the elib function.</p>
397 g2boojum 1.1 <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 g2boojum 1.5 initialization of the library that is absolutely needed. Additionally, they
400 g2boojum 1.2 cannot modify any ebuild template functions- src_compile, src_unpack. Since they are
401 g2boojum 1.1 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 vapier 1.3 other elibs. A real world example would be the eutils eclass.</p>
405 g2boojum 1.1 <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 g2boojum 1.2 known to cause rsync issues due to missing timestamps).</p>
410 g2boojum 1.5 <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 g2boojum 1.2 calls in the global scope will be tracked, but the elib will not be loaded till just before
413 g2boojum 1.5 the setup phase (pkg_setup). There are two reasons for this- first, it ensures elibs are
414 g2boojum 1.2 completely incapable of modifying metadata. There is no room for confusion, late loading
415 g2boojum 1.5 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 g2boojum 1.2 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 g2boojum 1.5 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 g2boojum 1.2 breakage. For *inst phases, same thing, except the culprit is binpkgs.</p>
424 g2boojum 1.5 <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 g2boojum 1.2 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 &quot;I'm accessible only via tweaking some var&quot;;}
431     else
432     func x() { echo &quot;this is invalid, do not do it.&quot;; }
433     fi
434     </pre>
435 g2boojum 1.1 <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 vapier 1.3 quite incestuous- they're bound tightly to the env they're defined in. This
438 g2boojum 1.1 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 g2boojum 1.2 <p>There is no need for backwards compatibility with elibs- they just must work
442 g2boojum 1.1 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 g2boojum 1.5 <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 g2boojum 1.2 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 g2boojum 1.1 </div>
451 g2boojum 1.5 <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 g2boojum 1.1 <p>Since elibs are now intended on holding common bash functionality, the focus of
454 vapier 1.3 eclasses should be in defining an appropriate template for ebuilds. For example,
455 g2boojum 1.1 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 g2boojum 1.2 pulled in, leading to compilation failure, or dud deps.</p>
471 g2boojum 1.1 <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 g2boojum 1.5 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 g2boojum 1.2 devs. This should be done prior to committing.</p>
478 g2boojum 1.1 <p>It's quite likely there is a way to allow what you're attempting- if you just go
479 g2boojum 1.2 and do it, the rsync users (our user base) suffer the results of compilation
480 g2boojum 1.1 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 g2boojum 1.2 <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 g2boojum 1.1 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 g2boojum 1.5 <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 vapier 1.3 <p>With current eclasses, once the eclass is in use, its api can no longer be
493 g2boojum 1.1 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 g2boojum 1.5 example inherit.eclass. The reason for this, not surprisingly, is a portage
496 vapier 1.3 deficiency: on unmerging an installed ebuild, portage used the eclass from the
497 g2boojum 1.1 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 g2boojum 1.2 in the rain, or maintaining an ever increasing load of backwards compatibility
503 g2boojum 1.1 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 g2boojum 1.2 <p>So the backwards compatibility requirement for users of the next major portage
513 g2boojum 1.1 version (and beyond) isn't required. All the cruft can be dropped.</p>
514 g2boojum 1.5 <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 g2boojum 1.2 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 g2boojum 1.5 <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 g2boojum 1.2 incapable of properly handling the env requirements.</p>
522 g2boojum 1.5 <p>Unfortunately, we cannot just rely on a different grouping/naming convention within
523 g2boojum 1.2 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 g2boojum 1.1 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 g2boojum 1.5 <div class="section">
534     <h2><a class="toc-backref" href="#id10" id="tree-restructuring" name="tree-restructuring">Tree restructuring</a></h2>
535 g2boojum 1.1 <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 g2boojum 1.2 eclasses to something other then 'eclass', or to have them stored in a separate
538 g2boojum 1.1 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 g2boojum 1.5 capabilities/requirements, thus it's advisable to start with a clean directory,
544 g2boojum 1.1 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 g2boojum 1.2 <p>The proposed directory structure is ${PORTDIR}/include/{eclass,elib}.
549 g2boojum 1.1 Something like ${PORTDIR}/new-eclass, or ${PORTDIR}/eclass-ng could be used
550 vapier 1.3 (although many would cringe at the -ng), but such a name is unwise. Consider the
551 g2boojum 1.1 possibility (likely a fact) that new eclasses someday may be found lacking, and
552 vapier 1.3 refined further (version three as it were). Or perhaps we want to add yet more
553 g2boojum 1.1 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 vapier 1.3 <dl class="docutils">
557 g2boojum 1.1 <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 g2boojum 1.2 saner/easier signing of eclasses- you can just stick a signed
571 g2boojum 1.1 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 vapier 1.3 to handle signing and committing. This is intentional, and a good thing. This
576 g2boojum 1.2 gives repoman the possibility of doing sanity checks on elibs/new eclasses.</p>
577 g2boojum 1.5 <p>Note these checks will not prevent developers from doing dumb things with eclass-
578 g2boojum 1.2 these checks would only be capable of doing basic sanity checks, such as syntax checks.
579 g2boojum 1.5 There is no way to prevent people from doing dumb things (exempting perhaps repeated
580 g2boojum 1.2 applications of a cattle prod)- these are strictly automatic checks, akin to repoman's
581     dependency checks.</p>
582     </div>
583 g2boojum 1.5 <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 g2boojum 1.2 <p>As clarified above, new eclasses will exist in a separate directory that will be
586 g2boojum 1.1 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 g2boojum 1.5 eclasses. A depend on the next major portage version would transparently handle
589 g2boojum 1.2 this for rsync users.</p>
590 g2boojum 1.1 <p>There still is the issue of users who haven't upgraded to the required portage
591 vapier 1.3 version. This is a minor concern frankly- portage releases include new
592 g2boojum 1.1 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 g2boojum 1.2 them. If they tried injecting the new portage version (lying to portage,
612 g2boojum 1.5 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 g2boojum 1.2 the portage version requirement- same as it has been for other portage features.</p>
615 g2boojum 1.1 <p>What is a bit more annoying is that once the old eclasses are out of the tree,
616 g2boojum 1.5 if a user has not upgraded to a portage version supporting env processing, they
617 g2boojum 1.2 will lose the ability to unmerge any installed ebuild that used an old
618 g2boojum 1.5 eclass. Same cause, different symptom being they will lose the ability to merge
619 g2boojum 1.2 any tbz2 that uses old eclasses also.</p>
620 g2boojum 1.5 <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 g2boojum 1.2 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 g2boojum 1.5 <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 g2boojum 1.2 issue, the system's vdb is completely unusable. It's a moot issue at that point.
629 g2boojum 1.5 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 g2boojum 1.2 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 g2boojum 1.5 <em>not</em> be left out in the rain. Merging the old eclass compat ebuild will provide
635 vapier 1.3 the missing eclasses, thus providing that lost functionality.</p>
636 g2boojum 1.2 <p>Note the intention isn't to force them to upgrade, hence the ability to restore the
637 vapier 1.3 lost functionality. The intention is to clean up the existing mess, and allow us
638     to move forward. The saying &quot;you've got to break a few eggs to make an omelet&quot;
639 g2boojum 1.1 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 g2boojum 1.5 <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 g2boojum 1.1 <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 vapier 1.3 determined, and prior to that window passing, an ebuild must be added to the tree
660 g2boojum 1.1 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 vapier 1.3 although it's advisable they cleanse all cruft out of the eclass. You can
664 g2boojum 1.1 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 g2boojum 1.5 <div class="section">
672     <h1><a class="toc-backref" href="#id13" id="backwards-compatibility" name="backwards-compatibility">Backwards Compatibility</a></h1>
673 g2boojum 1.2 <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 g2boojum 1.1 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 g2boojum 1.2 of the potential solutions, and reasons for the chosen solution.</p>
678 g2boojum 1.1 <p>To recap:</p>
679     <pre class="literal-block">
680     New eclasses and elib functionality will be tied to a specific portage
681 vapier 1.3 version. A DEPENDs on said portage version should address this for rsync
682 g2boojum 1.1 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.
688     Old eclasses at some point in the future should be removed from the tree,
689 vapier 1.3 and released in a tarball/ebuild. This will cause installed ebuilds that
690 g2boojum 1.5 rely on the old eclass to be unable to unmerge, with the same applying for
691 g2boojum 1.2 merging of binpkgs dependent on the following paragraph.
692 g2boojum 1.5
693     The old eclass-compat is only required for users who do not upgrade their
694 g2boojum 1.2 portage installation, and one further exemption- if the user has somehow
695 g2boojum 1.5 corrupted/destroyed their installed pkgs database (/var/db/pkg currently),
696 g2boojum 1.2 in the process, they've lost their saved environments. The eclass-compat
697 g2boojum 1.5 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 g2boojum 1.2 strictly to be complete, it's not much of a real world scenario as elaborated
700     above.
701 g2boojum 1.1 </pre>
702     </div>
703 g2boojum 1.5 <div class="section">
704     <h1><a class="toc-backref" href="#id14" id="copyright" name="copyright">Copyright</a></h1>
705 g2boojum 1.1 <p>This document has been placed in the public domain.</p>
706     </div>
707 vapier 1.3
708 g2boojum 1.1 </div>
709 vapier 1.3 <div class="footer">
710 g2boojum 1.1 <hr class="footer" />
711     <a class="reference" href="glep-0033.txt">View document source</a>.
712 g2boojum 1.6 Generated on: 2006-10-10 20:23 UTC.
713 g2boojum 1.1 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 vapier 1.3
715 g2boojum 1.1 </div>
716     </body>
717     </html>

  ViewVC Help
Powered by ViewVC 1.1.20