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

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

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

Revision 1.2 Revision 1.7
… …
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
5<head> 5<head>
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> 7 <meta name="generator" content="Docutils 0.8.1: http://docutils.sourceforge.net/" />
8 <title>GLEP 55 -- Use EAPI-suffixed ebuilds (.ebuild-EAPI)</title> 8 <title>GLEP 55 -- Use EAPI-suffixed ebuilds (.ebuild-EAPI)</title>
9 <link rel="stylesheet" href="tools/glep.css" type="text/css" /> 9 <link rel="stylesheet" href="tools/glep.css" type="text/css" /></head>
10</head>
11<body bgcolor="white"> 10<body bgcolor="white">
12<table class="navigation" cellpadding="0" cellspacing="0" 11<table class="navigation" cellpadding="0" cellspacing="0"
13 width="100%" border="0"> 12 width="100%" border="0">
14<tr><td class="navicon" width="150" height="35"> 13<tr><td class="navicon" width="150" height="35">
15<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page"> 14<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
… …
26<tbody valign="top"> 25<tbody valign="top">
27<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">55</td> 26<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">55</td>
28</tr> 27</tr>
29<tr class="field"><th class="field-name">Title:</th><td class="field-body">Use EAPI-suffixed ebuilds (.ebuild-EAPI)</td> 28<tr class="field"><th class="field-name">Title:</th><td class="field-body">Use EAPI-suffixed ebuilds (.ebuild-EAPI)</td>
30</tr> 29</tr>
31<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td> 30<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.5</td>
32</tr> 31</tr>
33<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-0055.txt?cvsroot=gentoo">2008/01/05 02:36:35</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-0055.txt?cvsroot=gentoo">2009/05/17 20:56:53</a></td>
34</tr> 33</tr>
35<tr class="field"><th class="field-name">Author:</th><td class="field-body">Piotr Jaroszyński &lt;peper&#32;&#97;t&#32;gentoo.org&gt;</td> 34<tr class="field"><th class="field-name">Author:</th><td class="field-body">Piotr Jaroszyński &lt;peper&#32;&#97;t&#32;gentoo.org&gt;</td>
36</tr> 35</tr>
37<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">Rejected</td>
38</tr> 37</tr>
39<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>
40</tr> 39</tr>
41<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> 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>
42</tr> 41</tr>
43<tr class="field"><th class="field-name">Created:</th><td class="field-body">17-Dec-2007</td> 42<tr class="field"><th class="field-name">Created:</th><td class="field-body">17-Dec-2007</td>
44</tr> 43</tr>
45<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">17-Dec-2007, 22-Dec-2007</td> 44<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">17-Dec-2007, 22-Dec-2007, 17-May-2009</td>
46</tr> 45</tr>
47</tbody> 46</tbody>
48</table> 47</table>
49<hr /> 48<hr />
50<div class="contents topic"> 49<div class="contents topic" id="contents">
51<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> 50<p class="topic-title first">Contents</p>
52<ul class="simple"> 51<ul class="simple">
52<li><a class="reference internal" href="#status" id="id3">Status</a></li>
53<li><a class="reference" href="#abstract" id="id3" name="id3">Abstract</a></li> 53<li><a class="reference internal" href="#abstract" id="id4">Abstract</a></li>
54<li><a class="reference" href="#problem" id="id4" name="id4">Problem</a></li> 54<li><a class="reference internal" href="#problem" id="id5">Problem</a></li>
55<li><a class="reference internal" href="#current-behaviour" id="id6">Current behaviour</a><ul>
56<li><a class="reference internal" href="#incompatible-change-of-inherit-e-g-make-it-look-in-the-package-dir-too" id="id7">Incompatible change of inherit (e.g. make it look in the package dir too)</a></li>
57<li><a class="reference internal" href="#new-global-scope-function" id="id8">New global scope function</a></li>
58<li><a class="reference internal" href="#new-version-format" id="id9">New version format</a></li>
59<li><a class="reference internal" href="#use-newer-bash-features" id="id10">Use newer bash features</a></li>
60</ul>
61</li>
55<li><a class="reference" href="#abstract-solution" id="id5" name="id5">Abstract solution</a></li> 62<li><a class="reference internal" href="#abstract-solution" id="id11">Abstract solution</a></li>
56<li><a class="reference" href="#proposed-solution" id="id6" name="id6">Proposed solution</a></li> 63<li><a class="reference internal" href="#proposed-solution" id="id12">Proposed solution</a></li>
57<li><a class="reference" href="#specification" id="id7" name="id7">Specification</a></li> 64<li><a class="reference internal" href="#specification" id="id13">Specification</a></li>
58<li><a class="reference" href="#application" id="id8" name="id8">Application</a></li> 65<li><a class="reference internal" href="#summary-of-ideas" id="id14">Summary of ideas</a><ul>
59<li><a class="reference" href="#other-ideas" id="id9" name="id9">Other ideas</a></li> 66<li><a class="reference internal" href="#eapi-suffixed-ebuilds-proposed-solution" id="id15">EAPI-suffixed ebuilds (proposed solution)</a></li>
67<li><a class="reference internal" href="#eapi-in-the-filename-with-one-time-extension-change" id="id16">EAPI in the filename with one-time extension change</a></li>
68<li><a class="reference internal" href="#easily-fetchable-eapi-inside-the-ebuild" id="id17">Easily fetchable EAPI inside the ebuild</a></li>
69<li><a class="reference internal" href="#easily-fetchable-eapi-inside-the-ebuild-and-one-time-extension-change" id="id18">Easily fetchable EAPI inside the ebuild and one-time extension change</a></li>
70<li><a class="reference internal" href="#use-different-subdirectories-for-different-eapis-i-e-cat-pkg-eapix" id="id19">Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/</a></li>
71</ul>
72</li>
60<li><a class="reference" href="#references" id="id10" name="id10">References</a></li> 73<li><a class="reference internal" href="#references" id="id20">References</a></li>
61<li><a class="reference" href="#copyright" id="id11" name="id11">Copyright</a></li> 74<li><a class="reference internal" href="#copyright" id="id21">Copyright</a></li>
62</ul> 75</ul>
63</div> 76</div>
64<blockquote> 77<blockquote>
65<p>&quot;A little learning is a dangerous thing; drink deep, or taste not the Pierian 78<p>&quot;A little learning is a dangerous thing; drink deep, or taste not the Pierian
66spring: there shallow draughts intoxicate the brain, and drinking largely 79spring: there shallow draughts intoxicate the brain, and drinking largely
67sobers us again.&quot;</p> 80sobers us again.&quot;</p>
68<p class="attribution">&mdash;Alexander Pope, An Essay on Criticism</p> 81<p class="attribution">&mdash;Alexander Pope, An Essay on Criticism</p>
69</blockquote> 82</blockquote>
70<div class="section"> 83<div class="section" id="status">
84<h1><a class="toc-backref" href="#id3">Status</a></h1>
85<p>This GLEP was voted down by the Council in its meeting on 2010-08-23.
86The Council rejected it again in its meeting on 2012-05-08, in favour
87of parsing the EAPI from the bash assignment statement in ebuilds.</p>
88</div>
89<div class="section" id="abstract">
71<h1><a class="toc-backref" href="#id3" id="abstract" name="abstract">Abstract</a></h1> 90<h1><a class="toc-backref" href="#id4">Abstract</a></h1>
72<p>This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for 91<p>This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for
73example, foo-1.2.3.ebuild-1).</p> 92example, foo-1.2.3.ebuild-1).</p>
74</div> 93</div>
75<div class="section"> 94<div class="section" id="problem">
76<h1><a class="toc-backref" href="#id4" id="problem" name="problem">Problem</a></h1> 95<h1><a class="toc-backref" href="#id5">Problem</a></h1>
77<p>The current way of specifying the EAPI in ebuilds is flawed. In order to get the 96<p>The current way of specifying the EAPI in ebuilds is flawed. In order to get the
78EAPI the package manager needs to source the ebuild, which itself needs the EAPI 97EAPI the package manager needs to source the ebuild, which itself needs the EAPI
79in the first place. Otherwise it imposes a serious limitation, namely every ebuild, 98in the first place. Otherwise it imposes a serious limitation, namely every ebuild,
80using any of the future EAPIs, will have to be source'able by old package 99using any of the future EAPIs, will have to be source'able by old package
81managers and hence there is no way to do any of the following:</p> 100managers and hence there is no way to do any of the following:</p>
… …
83<ul class="simple"> 102<ul class="simple">
84<li>Change the behaviour of inherit in any way (for example, to extend or change 103<li>Change the behaviour of inherit in any way (for example, to extend or change
85eclass functionality).</li> 104eclass functionality).</li>
86<li>Add new global scope functions in any sane way.</li> 105<li>Add new global scope functions in any sane way.</li>
87<li>Extend versioning rules in an EAPI - for example, addition of the scm 106<li>Extend versioning rules in an EAPI - for example, addition of the scm
88suffix - GLEP54 <a class="footnote-reference" href="#glep54" id="id1" name="id1">[1]</a>.</li> 107suffix - GLEP54 <a class="footnote-reference" href="#glep54" id="id1">[1]</a> or allowing more sensible version formats like
108<tt class="docutils literal"><span class="pre">1-rc1</span></tt>, <tt class="docutils literal"><span class="pre">1-alpha</span></tt> etc. to match upstream more closely.</li>
109<li>Use newer bash features.</li>
89</ul> 110</ul>
90</blockquote> 111</blockquote>
91</div> 112</div>
92<div class="section"> 113<div class="section" id="current-behaviour">
93<h1><a class="toc-backref" href="#id5" id="abstract-solution" name="abstract-solution">Abstract solution</a></h1> 114<h1><a class="toc-backref" href="#id6">Current behaviour</a></h1>
115<p>Following subsections show what happens if you introduce any of the mentioned
116changes in an ebuild and try to install it with portage 2.1.6.13.</p>
117<div class="section" id="incompatible-change-of-inherit-e-g-make-it-look-in-the-package-dir-too">
118<h2><a class="toc-backref" href="#id7">Incompatible change of inherit (e.g. make it look in the package dir too)</a></h2>
119<p><tt class="docutils literal"><span class="pre">sys-apps/foo-1.ebuild</span></tt>:</p>
120<pre class="literal-block">
121EAPI=&quot;5&quot;
122inherit &quot;foo&quot;
123
124DESCRIPTION=&quot;&quot;
125HOMEPAGE=&quot;&quot;
126SRC_URI=&quot;&quot;
127...
128</pre>
129<p>Result:</p>
130<pre class="literal-block">
131*
132* ERROR: sys-apps/foo-1 failed.
133* Call stack:
134* ebuild.sh, line 1879: Called _source_ebuild
135* ebuild.sh, line 1818: Called source '/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild'
136* foo-1.ebuild, line 6: Called inherit 'foo'
137* ebuild.sh, line 1218: Called die
138* The specific snippet of code:
139* [ ! -e &quot;$location&quot; ] &amp;&amp; die &quot;${1}.eclass could not be found by inherit()&quot;
140* The die message:
141* foo.eclass could not be found by inherit()
142*
143* If you need support, post the topmost build error, and the call stack if relevant.
144* This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/'
145*
146
147!!! All ebuilds that could satisfy &quot;sys-apps/foo&quot; have been masked.
148!!! One of the following masked packages is required to complete your request:
149- sys-apps/foo-1 (masked by: corruption)
150</pre>
151<p>Current portage looks for eclasses only in the <tt class="docutils literal">eclass</tt> directory of a
152repository. This results in a fatal error and ebuild being masked by corruption
153- might be pretty confusing to users.</p>
154</div>
155<div class="section" id="new-global-scope-function">
156<h2><a class="toc-backref" href="#id8">New global scope function</a></h2>
157<p><tt class="docutils literal"><span class="pre">sys-apps/foo-1.ebuild</span></tt>:</p>
158<pre class="literal-block">
159EAPI=&quot;5&quot;
160new_global_scope_function &quot;foo&quot;
161
162DESCRIPTION=&quot;&quot;
163HOMEPAGE=&quot;&quot;
164SRC_URI=&quot;&quot;
165...
166</pre>
167<p>Result:</p>
168<pre class="literal-block">
169/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 7: new_global_scope_function: command not found
170
171!!! All ebuilds that could satisfy &quot;sys-apps/foo&quot; have been masked.
172!!! One of the following masked packages is required to complete your request:
173- sys-apps/foo-1 (masked by: EAPI 5)
174
175The current version of portage supports EAPI '2'. You must upgrade to a
176newer version of portage before EAPI masked packages can be installed.
177</pre>
178<p>Not that bad as user is advised to upgrade portage.</p>
179</div>
180<div class="section" id="new-version-format">
181<h2><a class="toc-backref" href="#id9">New version format</a></h2>
182<p><tt class="docutils literal"><span class="pre">sys-apps/foo-2-rc1.ebuild</span></tt>:</p>
183<pre class="literal-block">
184Invalid ebuild name: /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-2-rc1.ebuild
185
186emerge: there are no ebuilds to satisfy &quot;sys-apps/foo&quot;
187</pre>
188<p>Not the best error message, especially if there are lots of them.</p>
189</div>
190<div class="section" id="use-newer-bash-features">
191<h2><a class="toc-backref" href="#id10">Use newer bash features</a></h2>
192<p><tt class="docutils literal">|&amp;</tt> is a new type of redirection added in bash-4. It cannot be used even in
193local scope as bash still parses the whole ebuild.</p>
194<p><tt class="docutils literal"><span class="pre">sys-apps/foo-1.ebuild</span></tt>:</p>
195<pre class="literal-block">
196EAPI=&quot;5&quot;
197
198foo() {
199 echo &quot;foo&quot; |&amp; cat
200}
201</pre>
202<p>Result:</p>
203<pre class="literal-block">
204/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: syntax error near unexpected token `&amp;'
205/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: ` echo &quot;foo&quot; |&amp; cat'
206*
207* ERROR: sys-apps/foo-1 failed.
208* Call stack:
209* ebuild.sh, line 1879: Called _source_ebuild
210* ebuild.sh, line 1818: Called die
211* The specific snippet of code:
212* source &quot;${EBUILD}&quot; || die &quot;error sourcing ebuild&quot;
213* The die message:
214* error sourcing ebuild
215*
216* If you need support, post the topmost build error, and the call stack if relevant.
217* This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/'
218* ... done!
219
220!!! All ebuilds that could satisfy &quot;sys-apps/foo&quot; have been masked.
221!!! One of the following masked packages is required to complete your request:
222- sys-apps/foo-1 (masked by: corruption)
223</pre>
224<p>Again, not the best error.</p>
225</div>
226</div>
227<div class="section" id="abstract-solution">
228<h1><a class="toc-backref" href="#id11">Abstract solution</a></h1>
94<p>A solution to this problem has to lift those limitations and the only way to do 229<p>A solution to this problem has to lift those limitations and the only way to do
95it is to make the EAPI of an ebuild available to the package managers in a way 230it is to make the EAPI of an ebuild available to the package managers in a way
96that doesn't require them to source the ebuild. Another important requirement is 231that doesn't require them to source the ebuild. Another important requirement is
97for the solution to be backward compatible, which has the pleasant side-effect 232for the solution to be backward compatible, which has the pleasant side-effect
98of making the solution applicable in the Gentoo tree right away. Opposed to 233of making the solution applicable in the Gentoo tree right away. Opposed to
99waiting an arbitrary amount of time, which is never long enough anyway, as the 234waiting an arbitrary amount of time, which is never long enough anyway, as the
100issues listed on the common portage problems page - <a class="footnote-reference" href="#portageproblems" id="id2" name="id2">[2]</a> - show.</p> 235issues listed on the common portage problems page - <a class="footnote-reference" href="#portageproblems" id="id2">[2]</a> - show.</p>
101</div> 236</div>
102<div class="section"> 237<div class="section" id="proposed-solution">
103<h1><a class="toc-backref" href="#id6" id="proposed-solution" name="proposed-solution">Proposed solution</a></h1> 238<h1><a class="toc-backref" href="#id12">Proposed solution</a></h1>
104<p>The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This 239<p>The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This
105allows package managers to trivially read the EAPI from the ebuild filename. It 240allows package managers to trivially read the EAPI from the ebuild filename. It
106is also backwards compatible, because currently ebuilds are recognised by the 241is also backwards compatible, because currently ebuilds are recognised by the
107<tt class="docutils literal"><span class="pre">.ebuild</span></tt> file extension and hence EAPI-suffixed ebuilds are simply ignored by 242<tt class="docutils literal">.ebuild</tt> file extension and hence EAPI-suffixed ebuilds are simply ignored by
108the package managers.</p> 243the package managers.</p>
109</div> 244</div>
110<div class="section"> 245<div class="section" id="specification">
111<h1><a class="toc-backref" href="#id7" id="specification" name="specification">Specification</a></h1> 246<h1><a class="toc-backref" href="#id13">Specification</a></h1>
112<p>Ebuild filename extension syntax: <tt class="docutils literal"><span class="pre">ebuild[-&lt;EAPI&gt;]</span></tt>, where <tt class="docutils literal"><span class="pre">[]</span></tt> denotes an 247<p>Ebuild filename extension syntax: <tt class="docutils literal"><span class="pre">ebuild[-&lt;EAPI&gt;]</span></tt>, where <tt class="docutils literal">[]</tt> denotes an
113optional part, and <tt class="docutils literal"><span class="pre">&lt;EAPI&gt;</span></tt> is the EAPI of the ebuild.</p> 248optional part, and <tt class="docutils literal">&lt;EAPI&gt;</tt> is the EAPI of the ebuild.</p>
114<p>Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the 249<p>The EAPI used by the ebuild is the EAPI included in the filename if it is set.
115EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI 250Otherwise the EAPI set inside the ebuild is used, which defaults to 0 (this is
116used by the ebuild can be established by following these steps:</p> 251the current behaviour).</p>
117<blockquote>
118<ul class="simple">
119<li>If the pre-source EAPI is not set it defaults to 0.</li>
120<li>If the pre-source EAPI is not recognised it is returned immediately.</li>
121<li>If the post-source EAPI is not set, it defaults to the pre-source EAPI.</li>
122<li>post-source EAPI is returned.</li>
123</ul>
124</blockquote>
125<p>The above process should be only used to generate the metadata cache. Should the
126pre-source EAPI be unsupported the cache entry cannot be generated.</p>
127<p>Ebuilds with unsupported EAPIs are masked.</p> 252<p>Ebuilds with unsupported EAPIs are masked.</p>
128<p>QA tools should consider it an error for both EAPIs to be set explicitly to 253<p>It should be considered an error to set the EAPI both in the filename and in the
129different values. Package managers may warn, but must use the post-source EAPI 254ebuild.</p>
130in such cases.</p>
131<p>Examples:</p> 255<p>Examples:</p>
132<blockquote> 256<blockquote>
133<ul> 257<ul>
134<li><dl class="first docutils"> 258<li><dl class="first docutils">
135<dt><tt class="docutils literal"><span class="pre">pkg-1.ebuild</span></tt>, no EAPI set inside the ebuild</dt> 259<dt><tt class="docutils literal"><span class="pre">pkg-1.ebuild</span></tt>, no EAPI set inside the ebuild</dt>
136<dd><p class="first last">pre-source EAPI defaults to 0, post-source EAPI defaults to pre-source EAPI. 260<dd><p class="first last">EAPI defaults to 0.</p>
137EAPI 0 is used.</p>
138</dd> 261</dd>
139</dl> 262</dl>
140</li> 263</li>
141<li><dl class="first docutils"> 264<li><dl class="first docutils">
142<dt><tt class="docutils literal"><span class="pre">pkg-2.ebuild-1</span></tt>, no EAPI set inside the ebuild</dt> 265<dt><tt class="docutils literal"><span class="pre">pkg-2.ebuild-1</span></tt>, no EAPI set inside the ebuild</dt>
143<dd><p class="first last">pre-source EAPI is 1, post-source EAPI defaults to pre-source EAPI. 266<dd><p class="first last">EAPI 1 is used.</p>
144EAPI 1 is used.</p>
145</dd> 267</dd>
146</dl> 268</dl>
147</li> 269</li>
148<li><dl class="first docutils"> 270<li><dl class="first docutils">
149<dt><tt class="docutils literal"><span class="pre">pkg-3.ebuild</span></tt>, <tt class="docutils literal"><span class="pre">EAPI=&quot;1&quot;</span></tt></dt> 271<dt><tt class="docutils literal"><span class="pre">pkg-3.ebuild-1</span></tt>, <tt class="docutils literal"><span class="pre">EAPI=&quot;1&quot;</span></tt></dt>
150<dd><p class="first last">pre-source EAPI defaults to 0, post-source EAPI is 1. 272<dd><p class="first last">EAPI set in both places - error.</p>
151EAPI 1 is used.</p>
152</dd>
153</dl>
154</li>
155<li><dl class="first docutils">
156<dt><tt class="docutils literal"><span class="pre">pkg-4.ebuild-2</span></tt>, <tt class="docutils literal"><span class="pre">EAPI=&quot;1&quot;</span></tt></dt>
157<dd><p class="first last">pre-source EAPI is 2, post-source EAPI is 1.
158EAPI 1 is used, but note that one should <strong>never</strong> explicitly set both
159EAPIs to different values.</p>
160</dd>
161</dl>
162</li>
163<li><dl class="first docutils">
164<dt><tt class="docutils literal"><span class="pre">pkg-5.ebuild-2</span></tt>, no EAPI set inside the ebuild, package manager not supporting EAPI 2</dt>
165<dd><p class="first last">pre-source EAPI is 2, post-source EAPI is never checked.
166ebuild is masked because of the unsupported pre-source EAPI.</p>
167</dd>
168</dl>
169</li>
170<li><dl class="first docutils">
171<dt><tt class="docutils literal"><span class="pre">pkg-6.ebuild</span></tt>, <tt class="docutils literal"><span class="pre">EAPI=&quot;2&quot;</span></tt>, package manager not supporting EAPI 2</dt>
172<dd><p class="first last">pre-source EAPI defaults to 0, post-source EAPI is 2 (assuming the
173package manager didn't die when sourcing the ebuild thinking that EAPI 0
174is used).
175ebuild is masked because of the unsupported post-source EAPI.</p>
176</dd> 273</dd>
177</dl> 274</dl>
178</li> 275</li>
179</ul> 276</ul>
180</blockquote> 277</blockquote>
… …
183allowing authors to provide backwards compatible ebuilds, it would introduce 280allowing authors to provide backwards compatible ebuilds, it would introduce
184problems too. The first is the requirement to have strict EAPI ordering, the 281problems too. The first is the requirement to have strict EAPI ordering, the
185second is ensuring that all the ebuilds for a single category/package-version 282second is ensuring that all the ebuilds for a single category/package-version
186are equivalent, i.e. installing any of them has exactly the same effect on a 283are equivalent, i.e. installing any of them has exactly the same effect on a
187given system.</p> 284given system.</p>
285<p>Also note that it is not a new restriction. It is already possible to illegally
286have multiple versions with different EAPIs as e.g. <tt class="docutils literal">1.0 == 1.00 == <span class="pre">1.00-r0</span></tt>
287and hence you could have <tt class="docutils literal"><span class="pre">foo-1.0.ebuild</span></tt> with EAPI X and <tt class="docutils literal"><span class="pre">foo-1.00.ebuild</span></tt>
288with EAPI Y.</p>
188</div> 289</div>
189<div class="section"> 290<div class="section" id="summary-of-ideas">
190<h1><a class="toc-backref" href="#id8" id="application" name="application">Application</a></h1> 291<h1><a class="toc-backref" href="#id14">Summary of ideas</a></h1>
191<p>Note that the developers should only set the pre-source EAPI. The process 292<div class="section" id="eapi-suffixed-ebuilds-proposed-solution">
192described above is only necessary to avoid undefined behaviour in corner cases 293<h2><a class="toc-backref" href="#id15">EAPI-suffixed ebuilds (proposed solution)</a></h2>
193and to retain backwards compatibility.</p> 294<dl class="docutils">
194<p>QA tools may warn if the post-source EAPI is set at all, thus helping with the 295<dt>Properties:</dt>
195transition to the new format.</p> 296<dd><ul class="first last simple">
297<li>Can be used right away: yes</li>
298<li>Hurts performance: no</li>
299</ul>
300</dd>
301</dl>
302<p>Some say it is clear and simple, others that it is ugly and unintuitive.</p>
196</div> 303</div>
197<div class="section"> 304<div class="section" id="eapi-in-the-filename-with-one-time-extension-change">
198<h1><a class="toc-backref" href="#id9" id="other-ideas" name="other-ideas">Other ideas</a></h1> 305<h2><a class="toc-backref" href="#id16">EAPI in the filename with one-time extension change</a></h2>
199<p>There were some other solutions proposed on the mailing list:</p> 306<p>One of the proposed filename formats:
307<tt class="docutils literal"><span class="pre">&lt;PKG&gt;-&lt;VER&gt;.eapi-&lt;EAPI&gt;.eb</span></tt></p>
308<dl class="docutils">
309<dt>Properties:</dt>
310<dd><ul class="first last simple">
311<li>Can be used right away: yes</li>
312<li>Hurts performance: no</li>
313</ul>
314</dd>
315</dl>
316<p>This is equivalent to the proposed solution.</p>
317<p>Some say it is better because the extension is static.</p>
318</div>
319<div class="section" id="easily-fetchable-eapi-inside-the-ebuild">
320<h2><a class="toc-backref" href="#id17">Easily fetchable EAPI inside the ebuild</a></h2>
321<dl class="docutils">
322<dt>Properties:</dt>
323<dd><ul class="first last simple">
324<li>Can be used right away: no</li>
325<li>Hurts performance: yes</li>
326</ul>
327</dd>
328</dl>
329<p>Cannot be used right away as it would trigger the errors shown in Current
330behaviour section for old package managers.</p>
331<p>Performance decrease comes from the fact that with version format changes in the
332picture package managers need EAPI to parse the ebuild's version. That means that merely
333picking the best version of a package requires loading EAPI (from cache or the
334ebuild) for each available ebuild.</p>
335<p>Here is more or less how the package manager figures out the best available
336version for a package with N versions available.</p>
200<blockquote> 337<blockquote>
338<ul class="simple">
339<li>EAPI in the filename<ul>
340<li>Read the directory containing the package - readdir()</li>
341<li>For each ebuild, read its EAPI and using that parse its version - no I/O</li>
342<li>Sort the versions - no I/O</li>
343<li>Going down from the highest to the lowest version<ul>
344<li>Get the metadata from cache - 2 x stat() + read()</li>
345<li>break if the version is visible</li>
201<ul> 346</ul>
347</li>
348</ul>
349</li>
350<li>EAPI in the ebuild<ul>
351<li>Read the directory containing the package - readdir()</li>
352<li>For each ebuild load its metadata from cache to get its EAPI - N x (2 x stat() + read())</li>
353<li>Sort the versions - no I/O</li>
354<li>Going down from the highest to the lowest version<ul>
355<li>(metadata is already loaded) - no I/O</li>
356<li>break if the version is visible - no I/O</li>
357</ul>
358</li>
359</ul>
360</li>
361</ul>
362</blockquote>
363<p>The difference is in for how many versions the package manager needs to hit
364cache. With EAPI in the ebuild it needs to do that for all versions, with EAPI
365in the filename it depends on versions visibility.
366For example, package foo has versions 1, 2, 3, 4, 5 and 6. 6 is masked, 5 is
367~arch and 1,2,3 and 4 are arch. Say, the user accepts only arch for this
368package. With EAPI in the filename it will read metadata only for versions
3696, 5 and 4. With EAPI in the ebuild it needs to load metadata for all versions.</p>
370<p>It's hard to say what's the avarage case, but surely the worst case scenario
371(when only the lowest version is visible) is uncommon.</p>
372</div>
373<div class="section" id="easily-fetchable-eapi-inside-the-ebuild-and-one-time-extension-change">
374<h2><a class="toc-backref" href="#id18">Easily fetchable EAPI inside the ebuild and one-time extension change</a></h2>
202<li><dl class="first docutils"> 375<dl class="docutils">
203<dt>Set the EAPI inside the ebuild in a way that makes it easy to fetch it</dt> 376<dt>Properties:</dt>
204<dd><ul class="first last simple"> 377<dd><ul class="first last simple">
205<li>Doesn't meet the backward compatibility requirement.</li> 378<li>Can be used right away: yes</li>
206<li>Isn't forward compatible either.</li> 379<li>Hurts performance: yes</li>
207<li>Could be confusing as ebuilds are considered bash scripts and this
208would impose additional restrictions on the ebuild format.</li>
209</ul>
210</dd>
211</dl> 380</ul>
381</dd>
212</li> 382</dl>
383<p>Performance decrease as described in the previous section.</p>
384<p>Some say it is clear and simple, others that it is confusing and unintuitive,
385because of the arbitrary format restrictions in what is a bash script otherwise.</p>
386</div>
387<div class="section" id="use-different-subdirectories-for-different-eapis-i-e-cat-pkg-eapix">
388<h2><a class="toc-backref" href="#id19">Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/</a></h2>
213<li><dl class="first docutils"> 389<dl class="docutils">
214<dt>Do the above and change the ebuild extension to <tt class="docutils literal"><span class="pre">.ebuild-ng</span></tt></dt> 390<dt>Properties:</dt>
215<dd><ul class="first last simple"> 391<dd><ul class="first last simple">
216<li>Meets the backward compatibility requirement.</li> 392<li>Can be used right away: yes</li>
217<li>Still can be confusing.</li> 393<li>Hurts performance: yes</li>
218<li>Isn't really forward compatible. What would be after <tt class="docutils literal"><span class="pre">.ebuild-ng</span></tt>?
219<tt class="docutils literal"><span class="pre">.ebuild-ng-ng</span></tt>?</li>
220</ul>
221</dd>
222</dl> 394</ul>
395</dd>
223</li> 396</dl>
224<li><dl class="first docutils"> 397<p>Performance decrease comes from the fact that it adds several more directory
225<dt>Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/</dt> 398reads.</p>
226<dd><ul class="first last simple">
227<li>Meets both requirements.</li>
228<li>Introduces a noticeable performance hit (several more directory reads
229in an I/O bound operation).</li>
230<li>Makes it much harder for maintainers to see what they have.</li> 399<p>Some say that it makes it much harder for maintainers to see what they have.</p>
231</ul>
232</dd>
233</dl>
234</li>
235</ul>
236</blockquote>
237</div> 400</div>
238<div class="section"> 401</div>
402<div class="section" id="references">
239<h1><a class="toc-backref" href="#id10" id="references" name="references">References</a></h1> 403<h1><a class="toc-backref" href="#id20">References</a></h1>
240<table class="docutils footnote" frame="void" id="glep54" rules="none"> 404<table class="docutils footnote" frame="void" id="glep54" rules="none">
241<colgroup><col class="label" /><col /></colgroup> 405<colgroup><col class="label" /><col /></colgroup>
242<tbody valign="top"> 406<tbody valign="top">
243<tr><td class="label"><a class="fn-backref" href="#id1" name="glep54">[1]</a></td><td>GLEP 54, scm package version suffix 407<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>GLEP 54, scm package version suffix
244(<a class="reference" href="http://glep.gentoo.org/glep-0054.html">http://glep.gentoo.org/glep-0054.html</a>)</td></tr> 408(<a class="reference external" href="http://glep.gentoo.org/glep-0054.html">http://glep.gentoo.org/glep-0054.html</a>)</td></tr>
245</tbody> 409</tbody>
246</table> 410</table>
247<table class="docutils footnote" frame="void" id="portageproblems" rules="none"> 411<table class="docutils footnote" frame="void" id="portageproblems" rules="none">
248<colgroup><col class="label" /><col /></colgroup> 412<colgroup><col class="label" /><col /></colgroup>
249<tbody valign="top"> 413<tbody valign="top">
250<tr><td class="label"><a class="fn-backref" href="#id2" name="portageproblems">[2]</a></td><td>Common portage problems 414<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Common portage problems
251(<a class="reference" href="http://www.gentoo.org/proj/en/portage/doc/common-problems.xml">http://www.gentoo.org/proj/en/portage/doc/common-problems.xml</a>)</td></tr> 415(<a class="reference external" href="http://www.gentoo.org/proj/en/portage/doc/common-problems.xml">http://www.gentoo.org/proj/en/portage/doc/common-problems.xml</a>)</td></tr>
252</tbody> 416</tbody>
253</table> 417</table>
254</div> 418</div>
255<div class="section"> 419<div class="section" id="copyright">
256<h1><a class="toc-backref" href="#id11" id="copyright" name="copyright">Copyright</a></h1> 420<h1><a class="toc-backref" href="#id21">Copyright</a></h1>
257<p>This document has been placed in the public domain.</p> 421<p>This document has been placed in the public domain.</p>
258<!-- vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : --> 422<!-- vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : -->
259</div> 423</div>
260 424
261</div> 425</div>
262<div class="footer"> 426<div class="footer">
263<hr class="footer" /> 427<hr class="footer" />
264<a class="reference" href="glep-0055.txt">View document source</a>. 428<a class="reference external" href="glep-0055.txt">View document source</a>.
265Generated on: 2008-01-06 02:39 UTC. 429Generated on: 2012-05-09 07:02 UTC.
266Generated 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. 430Generated 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.
267 431
268</div> 432</div>
269</body> 433</body>
270</html> 434</html>
271
Legend:
Removed from v.1.2  
changed lines
  Added in v.1.7
  ViewVC Help
Powered by ViewVC 1.1.13