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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

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

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.10

  ViewVC Help
Powered by ViewVC 1.1.20