/[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.1 Revision 1.4
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.4: http://docutils.sourceforge.net/" /> 7 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
12 <title>GLEP 55 -- Use EAPI-suffixed ebuilds (.ebuild-EAPI)</title> 8 <title>GLEP 55 -- Use EAPI-suffixed ebuilds (.ebuild-EAPI)</title>
13 <link rel="stylesheet" href="tools/glep.css" type="text/css" /> 9 <style type="text/css">
14</head> 10
11/*
12:Author: David Goodger
13:Contact: goodger@users.sourceforge.net
14:date: $Date: 2009/05/17 17:00:30 $
15:version: $Revision: 1.4 $
16:copyright: This stylesheet has been placed in the public domain.
17
18Default cascading style sheet for the PEP HTML output of Docutils.
19*/
20
21.first {
22 margin-top: 0 }
23
24.last {
25 margin-bottom: 0 }
26
27.navigation {
28 width: 100% ;
29 background: #cc99ff ;
30 margin-top: 0px ;
31 margin-bottom: 0px }
32
33.navigation .navicon {
34 width: 150px ;
35 height: 35px }
36
37.navigation .textlinks {
38 padding-left: 1em ;
39 text-align: left }
40
41.navigation td, .navigation th {
42 padding-left: 0em ;
43 padding-right: 0em ;
44 vertical-align: middle }
45
46.rfc2822 {
47 margin-top: 0.5em ;
48 margin-left: 0.5em ;
49 margin-right: 0.5em ;
50 margin-bottom: 0em }
51
52.rfc2822 td {
53 text-align: left }
54
55.rfc2822 th.field-name {
56 text-align: right ;
57 font-family: sans-serif ;
58 padding-right: 0.5em ;
59 font-weight: bold ;
60 margin-bottom: 0em }
61
62a.toc-backref {
63 text-decoration: none ;
64 color: black }
65
66body {
67 margin: 0px ;
68 margin-bottom: 1em ;
69 padding: 0px }
70
71dd {
72 margin-bottom: 0.5em }
73
74div.section {
75 margin-left: 1em ;
76 margin-right: 1em ;
77 margin-bottom: 1.5em }
78
79div.section div.section {
80 margin-left: 0em ;
81 margin-right: 0em ;
82 margin-top: 1.5em }
83
84div.abstract {
85 margin: 2em 5em }
86
87div.abstract p.topic-title {
88 font-weight: bold ;
89 text-align: center }
90
91div.attention, div.caution, div.danger, div.error, div.hint,
92div.important, div.note, div.tip, div.warning {
93 margin: 2em ;
94 border: medium outset ;
95 padding: 1em }
96
97div.attention p.admonition-title, div.caution p.admonition-title,
98div.danger p.admonition-title, div.error p.admonition-title,
99div.warning p.admonition-title {
100 color: red ;
101 font-weight: bold ;
102 font-family: sans-serif }
103
104div.hint p.admonition-title, div.important p.admonition-title,
105div.note p.admonition-title, div.tip p.admonition-title {
106 font-weight: bold ;
107 font-family: sans-serif }
108
109div.figure {
110 margin-left: 2em }
111
112div.footer, div.header {
113 font-size: smaller }
114
115div.footer {
116 margin-left: 1em ;
117 margin-right: 1em }
118
119div.system-messages {
120 margin: 5em }
121
122div.system-messages h1 {
123 color: red }
124
125div.system-message {
126 border: medium outset ;
127 padding: 1em }
128
129div.system-message p.system-message-title {
130 color: red ;
131 font-weight: bold }
132
133div.topic {
134 margin: 2em }
135
136h1 {
137 font-family: sans-serif ;
138 font-size: large }
139
140h2 {
141 font-family: sans-serif ;
142 font-size: medium }
143
144h3 {
145 font-family: sans-serif ;
146 font-size: small }
147
148h4 {
149 font-family: sans-serif ;
150 font-style: italic ;
151 font-size: small }
152
153h5 {
154 font-family: sans-serif;
155 font-size: x-small }
156
157h6 {
158 font-family: sans-serif;
159 font-style: italic ;
160 font-size: x-small }
161
162.section hr {
163 width: 75% }
164
165ol.simple, ul.simple {
166 margin-bottom: 1em }
167
168ol.arabic {
169 list-style: decimal }
170
171ol.loweralpha {
172 list-style: lower-alpha }
173
174ol.upperalpha {
175 list-style: upper-alpha }
176
177ol.lowerroman {
178 list-style: lower-roman }
179
180ol.upperroman {
181 list-style: upper-roman }
182
183p.caption {
184 font-style: italic }
185
186p.credits {
187 font-style: italic ;
188 font-size: smaller }
189
190p.label {
191 white-space: nowrap }
192
193p.topic-title {
194 font-family: sans-serif ;
195 font-weight: bold }
196
197pre.line-block {
198 font-family: serif ;
199 font-size: 100% }
200
201pre.literal-block, pre.doctest-block {
202 margin-left: 2em ;
203 margin-right: 2em ;
204 background-color: #eeeeee }
205
206span.classifier {
207 font-family: sans-serif ;
208 font-style: oblique }
209
210span.classifier-delimiter {
211 font-family: sans-serif ;
212 font-weight: bold }
213
214span.interpreted {
215 font-family: sans-serif }
216
217span.option-argument {
218 font-style: italic }
219
220span.pre {
221 white-space: pre }
222
223span.problematic {
224 color: red }
225
226table {
227 margin-top: 0.5em ;
228 margin-bottom: 0.5em }
229
230td, th {
231 padding-left: 0.5em ;
232 padding-right: 0.5em ;
233 vertical-align: top }
234
235td.num {
236 text-align: right }
237
238th.field-name {
239 font-weight: bold ;
240 text-align: left ;
241 white-space: nowrap }
242
243h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
244 font-size: 100% }
245
246tt {
247 background-color: #eeeeee }
248
249ul.auto-toc {
250 list-style-type: none }
251
252</style></head>
15<body bgcolor="white"> 253<body bgcolor="white">
16<table class="navigation" cellpadding="0" cellspacing="0" 254<table class="navigation" cellpadding="0" cellspacing="0"
17 width="100%" border="0"> 255 width="100%" border="0">
18<tr><td class="navicon" width="150" height="35"> 256<tr><td class="navicon" width="150" height="35">
19<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page"> 257<a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
20<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]" 258<img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
21 border="0" width="150" height="35" /></a></td> 259 border="0" width="150" height="35" /></a></td>
22<td class="textlinks" align="left"> 260<td class="textlinks" align="left">
23[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>] 261[<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
24[<b><a href="http://www.gentoo.org/peps">GLEP Index</a></b>] 262[<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
25[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0055.txt">GLEP Source</a></b>] 263[<b><a href="http://www.gentoo.org/proj/en/glep/glep-0055.txt">GLEP Source</a></b>]
26</td></tr></table> 264</td></tr></table>
27<table class="rfc2822 docutils field-list" frame="void" rules="none"> 265<table class="rfc2822 docutils field-list" frame="void" rules="none">
28<col class="field-name" /> 266<col class="field-name" />
29<col class="field-body" /> 267<col class="field-body" />
30<tbody valign="top"> 268<tbody valign="top">
31<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">55</td> 269<tr class="field"><th class="field-name">GLEP:</th><td class="field-body">55</td>
32</tr> 270</tr>
33<tr class="field"><th class="field-name">Title:</th><td class="field-body">Use EAPI-suffixed ebuilds (.ebuild-EAPI)</td> 271<tr class="field"><th class="field-name">Title:</th><td class="field-body">Use EAPI-suffixed ebuilds (.ebuild-EAPI)</td>
34</tr> 272</tr>
35<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td> 273<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.3</td>
36</tr> 274</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.cgi/xml/htdocs/proj/en/glep/glep-0055.txt?cvsroot=gentoo">2008/01/05 02:36:35</a></td> 275<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 15:50:27</a></td>
38</tr> 276</tr>
39<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> 277<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>
40</tr> 278</tr>
41<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td> 279<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
42</tr> 280</tr>
43<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td> 281<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
44</tr> 282</tr>
45<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> 283<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> 284</tr>
47<tr class="field"><th class="field-name">Created:</th><td class="field-body">17-Dec-2007</td> 285<tr class="field"><th class="field-name">Created:</th><td class="field-body">17-Dec-2007</td>
48</tr> 286</tr>
49<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">17-Dec-2007, 22-Dec-2007</td> 287<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">17-Dec-2007, 22-Dec-2007, 17-May-2009</td>
50</tr> 288</tr>
51</tbody> 289</tbody>
52</table> 290</table>
53<hr /> 291<hr />
54<div class="contents topic"> 292<div class="contents topic" id="contents">
55<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> 293<p class="topic-title first">Contents</p>
56<ul class="simple"> 294<ul class="simple">
57<li><a class="reference" href="#abstract" id="id3" name="id3">Abstract</a></li> 295<li><a class="reference internal" href="#abstract" id="id3">Abstract</a></li>
58<li><a class="reference" href="#problem" id="id4" name="id4">Problem</a></li> 296<li><a class="reference internal" href="#problem" id="id4">Problem</a></li>
297<li><a class="reference internal" href="#current-behaviour" id="id5">Current behaviour</a><ul>
298<li><a class="reference internal" href="#incompatible-change-of-inherit-e-g-make-it-look-in-the-package-dir-too" id="id6">Incompatible change of inherit (e.g. make it look in the package dir too)</a></li>
299<li><a class="reference internal" href="#new-global-scope-function" id="id7">New global scope function</a></li>
300<li><a class="reference internal" href="#new-version-format" id="id8">New version format</a></li>
301<li><a class="reference internal" href="#use-newer-bash-features" id="id9">Use newer bash features</a></li>
302</ul>
303</li>
59<li><a class="reference" href="#abstract-solution" id="id5" name="id5">Abstract solution</a></li> 304<li><a class="reference internal" href="#abstract-solution" id="id10">Abstract solution</a></li>
60<li><a class="reference" href="#proposed-solution" id="id6" name="id6">Proposed solution</a></li> 305<li><a class="reference internal" href="#proposed-solution" id="id11">Proposed solution</a></li>
61<li><a class="reference" href="#specification" id="id7" name="id7">Specification</a></li> 306<li><a class="reference internal" href="#specification" id="id12">Specification</a></li>
62<li><a class="reference" href="#application" id="id8" name="id8">Application</a></li> 307<li><a class="reference internal" href="#summary-of-ideas" id="id13">Summary of ideas</a><ul>
63<li><a class="reference" href="#other-ideas" id="id9" name="id9">Other ideas</a></li> 308<li><a class="reference internal" href="#eapi-suffixed-ebuilds-proposed-solution" id="id14">EAPI-suffixed ebuilds (proposed solution)</a></li>
309<li><a class="reference internal" href="#eapi-in-the-filename-with-one-time-extension-change" id="id15">EAPI in the filename with one-time extension change</a></li>
310<li><a class="reference internal" href="#easily-fetchable-eapi-inside-the-ebuild" id="id16">Easily fetchable EAPI inside the ebuild</a></li>
311<li><a class="reference internal" href="#easily-fetchable-eapi-inside-the-ebuild-and-one-time-extension-change" id="id17">Easily fetchable EAPI inside the ebuild and one-time extension change</a></li>
312<li><a class="reference internal" href="#use-different-subdirectories-for-different-eapis-i-e-cat-pkg-eapix" id="id18">Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/</a></li>
313</ul>
314</li>
64<li><a class="reference" href="#references" id="id10" name="id10">References</a></li> 315<li><a class="reference internal" href="#references" id="id19">References</a></li>
65<li><a class="reference" href="#copyright" id="id11" name="id11">Copyright</a></li> 316<li><a class="reference internal" href="#copyright" id="id20">Copyright</a></li>
66</ul> 317</ul>
67</div> 318</div>
68<blockquote> 319<blockquote>
69<p>&quot;A little learning is a dangerous thing; drink deep, or taste not the Pierian 320<p>&quot;A little learning is a dangerous thing; drink deep, or taste not the Pierian
70spring: there shallow draughts intoxicate the brain, and drinking largely 321spring: there shallow draughts intoxicate the brain, and drinking largely
71sobers us again.&quot;</p> 322sobers us again.&quot;</p>
72<p class="attribution">&mdash;Alexander Pope, An Essay on Criticism</p> 323<p class="attribution">&mdash;Alexander Pope, An Essay on Criticism</p>
73</blockquote> 324</blockquote>
74<div class="section"> 325<div class="section" id="abstract">
75<h1><a class="toc-backref" href="#id3" id="abstract" name="abstract">Abstract</a></h1> 326<h1><a class="toc-backref" href="#id3">Abstract</a></h1>
76<p>This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for 327<p>This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for
77example, foo-1.2.3.ebuild-1).</p> 328example, foo-1.2.3.ebuild-1).</p>
78</div> 329</div>
79<div class="section"> 330<div class="section" id="problem">
80<h1><a class="toc-backref" href="#id4" id="problem" name="problem">Problem</a></h1> 331<h1><a class="toc-backref" href="#id4">Problem</a></h1>
81<p>The current way of specifying the EAPI in ebuilds is flawed. In order to get the 332<p>The current way of specifying the EAPI in ebuilds is flawed. In order to get the
82EAPI the package manager needs to source the ebuild, which itself needs the EAPI 333EAPI the package manager needs to source the ebuild, which itself needs the EAPI
83in the first place. Otherwise it imposes a serious limitation, namely every ebuild, 334in the first place. Otherwise it imposes a serious limitation, namely every ebuild,
84using any of the future EAPIs, will have to be source'able by old package 335using any of the future EAPIs, will have to be source'able by old package
85managers and hence there is no way to:</p> 336managers and hence there is no way to do any of the following:</p>
86<blockquote> 337<blockquote>
87<ul class="simple"> 338<ul class="simple">
88<li>Change behaviour of inherit in any way (for example, to extend or change 339<li>Change the behaviour of inherit in any way (for example, to extend or change
89eclass functionality).</li> 340eclass functionality).</li>
90<li>Add new global scope functions in any sane way.</li> 341<li>Add new global scope functions in any sane way.</li>
91<li>Extend versioning rules in an EAPI - for example, addition of the scm 342<li>Extend versioning rules in an EAPI - for example, addition of the scm
92suffix - GLEP54 <a class="footnote-reference" href="#glep54" id="id1" name="id1">[1]</a>.</li> 343suffix - GLEP54 <a class="footnote-reference" href="#glep54" id="id1">[1]</a> or allowing more sensible version formats like
344<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>
345<li>Use newer bash features.</li>
93</ul> 346</ul>
94</blockquote> 347</blockquote>
95</div> 348</div>
96<div class="section"> 349<div class="section" id="current-behaviour">
97<h1><a class="toc-backref" href="#id5" id="abstract-solution" name="abstract-solution">Abstract solution</a></h1> 350<h1><a class="toc-backref" href="#id5">Current behaviour</a></h1>
351<p>Following subsections show what happens if you introduce any of the mentioned
352changes in an ebuild and try to install it with portage 2.1.6.13.</p>
353<div class="section" id="incompatible-change-of-inherit-e-g-make-it-look-in-the-package-dir-too">
354<h2><a class="toc-backref" href="#id6">Incompatible change of inherit (e.g. make it look in the package dir too)</a></h2>
355<p><tt class="docutils literal"><span class="pre">sys-apps/foo-1.ebuild</span></tt>:</p>
356<pre class="literal-block">
357EAPI=&quot;5&quot;
358inherit &quot;foo&quot;
359
360DESCRIPTION=&quot;&quot;
361HOMEPAGE=&quot;&quot;
362SRC_URI=&quot;&quot;
363...
364</pre>
365<p>Result:</p>
366<pre class="literal-block">
367*
368* ERROR: sys-apps/foo-1 failed.
369* Call stack:
370* ebuild.sh, line 1879: Called _source_ebuild
371* ebuild.sh, line 1818: Called source '/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild'
372* foo-1.ebuild, line 6: Called inherit 'foo'
373* ebuild.sh, line 1218: Called die
374* The specific snippet of code:
375* [ ! -e &quot;$location&quot; ] &amp;&amp; die &quot;${1}.eclass could not be found by inherit()&quot;
376* The die message:
377* foo.eclass could not be found by inherit()
378*
379* If you need support, post the topmost build error, and the call stack if relevant.
380* This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/'
381*
382
383!!! All ebuilds that could satisfy &quot;sys-apps/foo&quot; have been masked.
384!!! One of the following masked packages is required to complete your request:
385- sys-apps/foo-1 (masked by: corruption)
386</pre>
387<p>Current portage looks for eclasses only in the <tt class="docutils literal"><span class="pre">eclass</span></tt> directory of a
388repository. This results in a fatal error and ebuild being masked by corruption
389- might be pretty confusing to users.</p>
390</div>
391<div class="section" id="new-global-scope-function">
392<h2><a class="toc-backref" href="#id7">New global scope function</a></h2>
393<p><tt class="docutils literal"><span class="pre">sys-apps/foo-1.ebuild</span></tt>:</p>
394<pre class="literal-block">
395EAPI=&quot;5&quot;
396new_global_scope_function &quot;foo&quot;
397
398DESCRIPTION=&quot;&quot;
399HOMEPAGE=&quot;&quot;
400SRC_URI=&quot;&quot;
401...
402</pre>
403<p>Result:</p>
404<pre class="literal-block">
405/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 7: new_global_scope_function: command not found
406
407!!! All ebuilds that could satisfy &quot;sys-apps/foo&quot; have been masked.
408!!! One of the following masked packages is required to complete your request:
409- sys-apps/foo-1 (masked by: EAPI 5)
410
411The current version of portage supports EAPI '2'. You must upgrade to a
412newer version of portage before EAPI masked packages can be installed.
413</pre>
414<p>Not that bad as user is advised to upgrade portage.</p>
415</div>
416<div class="section" id="new-version-format">
417<h2><a class="toc-backref" href="#id8">New version format</a></h2>
418<p><tt class="docutils literal"><span class="pre">sys-apps/foo-2-rc1.ebuild</span></tt>:</p>
419<pre class="literal-block">
420Invalid ebuild name: /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-2-rc1.ebuild
421
422emerge: there are no ebuilds to satisfy &quot;sys-apps/foo&quot;
423</pre>
424<p>Not the best error message, especially if there are lots of them.</p>
425</div>
426<div class="section" id="use-newer-bash-features">
427<h2><a class="toc-backref" href="#id9">Use newer bash features</a></h2>
428<p><tt class="docutils literal"><span class="pre">|&amp;</span></tt> is a new type of redirection added in bash-4. It cannot be used even in
429local scope as bash still parses the whole ebuild.</p>
430<p><tt class="docutils literal"><span class="pre">sys-apps/foo-1.ebuild</span></tt>:</p>
431<pre class="literal-block">
432EAPI=&quot;5&quot;
433
434foo() {
435 echo &quot;foo&quot; |&amp; cat
436}
437</pre>
438<p>Result:</p>
439<pre class="literal-block">
440/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: syntax error near unexpected token `&amp;'
441/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: ` echo &quot;foo&quot; |&amp; cat'
442*
443* ERROR: sys-apps/foo-1 failed.
444* Call stack:
445* ebuild.sh, line 1879: Called _source_ebuild
446* ebuild.sh, line 1818: Called die
447* The specific snippet of code:
448* source &quot;${EBUILD}&quot; || die &quot;error sourcing ebuild&quot;
449* The die message:
450* error sourcing ebuild
451*
452* If you need support, post the topmost build error, and the call stack if relevant.
453* This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/'
454* ... done!
455
456!!! All ebuilds that could satisfy &quot;sys-apps/foo&quot; have been masked.
457!!! One of the following masked packages is required to complete your request:
458- sys-apps/foo-1 (masked by: corruption)
459</pre>
460<p>Again, not the best error.</p>
461</div>
462</div>
463<div class="section" id="abstract-solution">
464<h1><a class="toc-backref" href="#id10">Abstract solution</a></h1>
98<p>A solution to this problem has to lift those limitations and the only way to do 465<p>A solution to this problem has to lift those limitations and the only way to do
99it is to make the EAPI of an ebuild available to the package managers in a way 466it is to make the EAPI of an ebuild available to the package managers in a way
100that doesn't require them to source the ebuild. Another important requirement is 467that doesn't require them to source the ebuild. Another important requirement is
101for the solution to be backward compatible, which has the pleasant side-effect 468for the solution to be backward compatible, which has the pleasant side-effect
102of making the solution applicable in the Gentoo tree right away. Opposed to 469of making the solution applicable in the Gentoo tree right away. Opposed to
103waiting an arbitrary amount of time, which is never long enough anyway, as the 470waiting an arbitrary amount of time, which is never long enough anyway, as the
104issues listed on the common portage problems page - <a class="footnote-reference" href="#portageproblems" id="id2" name="id2">[2]</a> - show.</p> 471issues listed on the common portage problems page - <a class="footnote-reference" href="#portageproblems" id="id2">[2]</a> - show.</p>
105</div> 472</div>
106<div class="section"> 473<div class="section" id="proposed-solution">
107<h1><a class="toc-backref" href="#id6" id="proposed-solution" name="proposed-solution">Proposed solution</a></h1> 474<h1><a class="toc-backref" href="#id11">Proposed solution</a></h1>
108<p>The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This 475<p>The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This
109allows package managers to trivially read the EAPI from the ebuild filename. It 476allows package managers to trivially read the EAPI from the ebuild filename. It
110is also backward compatible, because currently ebuilds are recognised by the 477is also backwards compatible, because currently ebuilds are recognised by the
111<tt class="docutils literal"><span class="pre">.ebuild</span></tt> file extension and hence EAPI-suffixed ebuilds are simply ignored by 478<tt class="docutils literal"><span class="pre">.ebuild</span></tt> file extension and hence EAPI-suffixed ebuilds are simply ignored by
112the package managers.</p> 479the package managers.</p>
113</div> 480</div>
114<div class="section"> 481<div class="section" id="specification">
115<h1><a class="toc-backref" href="#id7" id="specification" name="specification">Specification</a></h1> 482<h1><a class="toc-backref" href="#id12">Specification</a></h1>
116<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 483<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
117optional part, and <tt class="docutils literal"><span class="pre">&lt;EAPI&gt;</span></tt> is the EAPI of the ebuild.</p> 484optional part, and <tt class="docutils literal"><span class="pre">&lt;EAPI&gt;</span></tt> is the EAPI of the ebuild.</p>
118<p>Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the 485<p>The EAPI used by the ebuild is the EAPI included in the filename if it is set.
119EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI 486Otherwise the EAPI set inside the ebuild is used, which defaults to 0 (this is
120used by the ebuild can be established by following these steps:</p> 487the current behaviour).</p>
121<blockquote>
122<ul class="simple">
123<li>If the pre-source EAPI is not set it defaults to 0.</li>
124<li>If the pre-source EAPI is not recognised it is returned immediately.</li>
125<li>If the post-source EAPI is not set, it defaults to the pre-source EAPI.</li>
126<li>post-source EAPI is returned.</li>
127</ul>
128</blockquote>
129<p>The above process should be only used to generate the metadata cache. Should the
130pre-source EAPI be unsupported the cache entry cannot be generated.</p>
131<p>Ebuilds with unsupported EAPIs are masked.</p> 488<p>Ebuilds with unsupported EAPIs are masked.</p>
132<p>QA tools should consider it an error for both EAPIs to be set explicitly to 489<p>It should be considered an error to set the EAPI both in the filename and in the
133different values. Package managers may warn, but must use the post-source EAPI 490ebuild.</p>
134in such cases.</p>
135<p>Examples:</p> 491<p>Examples:</p>
136<blockquote> 492<blockquote>
137<ul> 493<ul>
138<li><dl class="first docutils"> 494<li><dl class="first docutils">
139<dt><tt class="docutils literal"><span class="pre">pkg-1.ebuild</span></tt>, no EAPI set inside the ebuild</dt> 495<dt><tt class="docutils literal"><span class="pre">pkg-1.ebuild</span></tt>, no EAPI set inside the ebuild</dt>
140<dd><p class="first last">pre-source EAPI defaults 0, post-source EAPI defaults to pre-source EAPI. 496<dd><p class="first last">EAPI defaults to 0.</p>
141EAPI 0 is used.</p>
142</dd> 497</dd>
143</dl> 498</dl>
144</li> 499</li>
145<li><dl class="first docutils"> 500<li><dl class="first docutils">
146<dt><tt class="docutils literal"><span class="pre">pkg-2.ebuild-1</span></tt>, no EAPI set inside the ebuild</dt> 501<dt><tt class="docutils literal"><span class="pre">pkg-2.ebuild-1</span></tt>, no EAPI set inside the ebuild</dt>
147<dd><p class="first last">pre-source EAPI is 1, post-source EAPI defaults to pre-source EAPI. 502<dd><p class="first last">EAPI 1 is used.</p>
148EAPI 1 is used.</p>
149</dd> 503</dd>
150</dl> 504</dl>
151</li> 505</li>
152<li><dl class="first docutils"> 506<li><dl class="first docutils">
153<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> 507<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>
154<dd><p class="first last">pre-source EAPI defaults to 0, post-source EAPI is 1. 508<dd><p class="first last">EAPI set in both places - error.</p>
155EAPI 1 is used.</p>
156</dd>
157</dl>
158</li>
159<li><dl class="first docutils">
160<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>
161<dd><p class="first last">pre-source EAPI is 2, post-source EAPI is 1.
162EAPI 1 is used, but note that one should <strong>never</strong> explicitly set both
163EAPIs to different values.</p>
164</dd>
165</dl>
166</li>
167<li><dl class="first docutils">
168<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>
169<dd><p class="first last">pre-source EAPI is 2, post-source EAPI is never checked.
170ebuild masked because of the unsupported pre-source EAPI.</p>
171</dd>
172</dl>
173</li>
174<li><dl class="first docutils">
175<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>
176<dd><p class="first last">pre-source EAPI defaults to 0, post-source EAPI is 2 (assuming the
177package manager didn't die when sourcing the ebuild thinking that EAPI 0
178is used).
179ebuild masked because of the unsupported post-source EAPI.</p>
180</dd> 509</dd>
181</dl> 510</dl>
182</li> 511</li>
183</ul> 512</ul>
184</blockquote> 513</blockquote>
185<p>Note that it is still not permitted to have more than one ebuild with equal 514<p>Note that it is still not permitted to have more than one ebuild with equal
186category, package name, and version. Although it would have the advantage of 515category, package name, and version. Although it would have the advantage of
187allowing to provide backward compatible ebuilds, it would introduce problems 516allowing authors to provide backwards compatible ebuilds, it would introduce
188too. The first is the requirement to have strict EAPI ordering, the second is 517problems too. The first is the requirement to have strict EAPI ordering, the
189ensuring that all the ebuilds for a single category/package-version are 518second is ensuring that all the ebuilds for a single category/package-version
190equivalent, i.e. installing any of them has exactly the same effect to the 519are equivalent, i.e. installing any of them has exactly the same effect on a
191system.</p> 520given system.</p>
192</div> 521</div>
193<div class="section"> 522<div class="section" id="summary-of-ideas">
194<h1><a class="toc-backref" href="#id8" id="application" name="application">Application</a></h1> 523<h1><a class="toc-backref" href="#id13">Summary of ideas</a></h1>
195<p>Note that the developers should only set the pre-source EAPI. The process 524<div class="section" id="eapi-suffixed-ebuilds-proposed-solution">
196described above is only necessary to avoid undefined behaviour in corner cases 525<h2><a class="toc-backref" href="#id14">EAPI-suffixed ebuilds (proposed solution)</a></h2>
197and to retain backwards compatibility.</p>
198<p>QA tools may warn if the post-source EAPI is set at all, thus helping with the
199transition to the new format.</p>
200</div>
201<div class="section">
202<h1><a class="toc-backref" href="#id9" id="other-ideas" name="other-ideas">Other ideas</a></h1>
203<p>There were some other solutions proposed on the mailing list:</p>
204<blockquote>
205<ul>
206<li><dl class="first docutils"> 526<dl class="docutils">
207<dt>Set the EAPI inside the ebuild in a way that makes it easy to fetch it</dt> 527<dt>Properties:</dt>
208<dd><ul class="first last simple"> 528<dd><ul class="first last simple">
209<li>Doesn't meet the backward compatibility requirement.</li> 529<li>Can be used right away: yes</li>
210<li>Isn't forward compatible either.</li> 530<li>Hurts performance: no</li>
211<li>Could be confusing as ebuilds, and not without a reason, are
212considered bash scripts and this would impose additional restrictions.</li>
213</ul>
214</dd>
215</dl> 531</ul>
532</dd>
216</li> 533</dl>
534<p>Some say it is clear and simple, others that it is ugly and unintuitive.</p>
535</div>
536<div class="section" id="eapi-in-the-filename-with-one-time-extension-change">
537<h2><a class="toc-backref" href="#id15">EAPI in the filename with one-time extension change</a></h2>
538<p>One of the proposed filename formats:
539<tt class="docutils literal"><span class="pre">&lt;PKG&gt;-&lt;VER&gt;.eapi-&lt;EAPI&gt;.eb</span></tt></p>
217<li><dl class="first docutils"> 540<dl class="docutils">
218<dt>Do the above and change the ebuild extension to <tt class="docutils literal"><span class="pre">.ebuild-ng</span></tt></dt> 541<dt>Properties:</dt>
219<dd><ul class="first last simple"> 542<dd><ul class="first last simple">
220<li>Meets the backward compatibility requirement.</li> 543<li>Can be used right away: yes</li>
221<li>Still can be confusing.</li> 544<li>Hurts performance: no</li>
222<li>Isn't really forward compatible. What would be after <tt class="docutils literal"><span class="pre">.ebuild-ng</span></tt>?
223<tt class="docutils literal"><span class="pre">.ebuild-ng-ng</span></tt>?</li>
224</ul>
225</dd>
226</dl> 545</ul>
546</dd>
227</li> 547</dl>
548<p>This is equivalent to the proposed solution.</p>
549<p>Some say it is better because the extension is static.</p>
550</div>
551<div class="section" id="easily-fetchable-eapi-inside-the-ebuild">
552<h2><a class="toc-backref" href="#id16">Easily fetchable EAPI inside the ebuild</a></h2>
228<li><dl class="first docutils"> 553<dl class="docutils">
229<dt>Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/</dt> 554<dt>Properties:</dt>
230<dd><ul class="first last simple"> 555<dd><ul class="first last simple">
231<li>Meets both requirements.</li> 556<li>Can be used right away: no</li>
232<li>Introduces a noticeable performance hit (several more directory reads 557<li>Hurts performance: yes</li>
233in an I/O bound operation).</li> 558</ul>
559</dd>
560</dl>
561<p>Cannot be used right away as it would trigger the errors shown in Current
562behaviour section for old package managers.</p>
563<p>Performance decrease comes from the fact that with version format changes in the
564picture package managers need EAPI to parse the ebuild's version. That means that merely
565picking the best version of a package requires loading EAPI (from cache or the
566ebuild) for each available ebuild.</p>
567</div>
568<div class="section" id="easily-fetchable-eapi-inside-the-ebuild-and-one-time-extension-change">
569<h2><a class="toc-backref" href="#id17">Easily fetchable EAPI inside the ebuild and one-time extension change</a></h2>
570<dl class="docutils">
571<dt>Properties:</dt>
572<dd><ul class="first last simple">
573<li>Can be used right away: yes</li>
574<li>Hurts performance: yes</li>
575</ul>
576</dd>
577</dl>
578<p>Performance decrease as described in the previous section.</p>
579<p>Some say it is clear and simple, others that it is confusing and unintuitive,
580because of the arbitrary format restrictions in what is a bash script otherwise.</p>
581</div>
582<div class="section" id="use-different-subdirectories-for-different-eapis-i-e-cat-pkg-eapix">
583<h2><a class="toc-backref" href="#id18">Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/</a></h2>
584<dl class="docutils">
585<dt>Properties:</dt>
586<dd><ul class="first last simple">
587<li>Can be used right away: yes</li>
588<li>Hurts performance: yes</li>
589</ul>
590</dd>
591</dl>
592<p>Performance decrease comes from the fact that it adds several more directory
593reads.</p>
234<li>Makes it much harder for maintainers to see what they have.</li> 594<p>Some say that it makes it much harder for maintainers to see what they have.</p>
235</ul>
236</dd>
237</dl>
238</li>
239</ul>
240</blockquote>
241</div> 595</div>
242<div class="section"> 596</div>
597<div class="section" id="references">
243<h1><a class="toc-backref" href="#id10" id="references" name="references">References</a></h1> 598<h1><a class="toc-backref" href="#id19">References</a></h1>
244<table class="docutils footnote" frame="void" id="glep54" rules="none"> 599<table class="docutils footnote" frame="void" id="glep54" rules="none">
245<colgroup><col class="label" /><col /></colgroup> 600<colgroup><col class="label" /><col /></colgroup>
246<tbody valign="top"> 601<tbody valign="top">
247<tr><td class="label"><a class="fn-backref" href="#id1" name="glep54">[1]</a></td><td>GLEP 54, scm package version suffix 602<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>GLEP 54, scm package version suffix
248(<a class="reference" href="http://glep.gentoo.org/glep-0054.html">http://glep.gentoo.org/glep-0054.html</a>)</td></tr> 603(<a class="reference external" href="http://glep.gentoo.org/glep-0054.html">http://glep.gentoo.org/glep-0054.html</a>)</td></tr>
249</tbody> 604</tbody>
250</table> 605</table>
251<table class="docutils footnote" frame="void" id="portageproblems" rules="none"> 606<table class="docutils footnote" frame="void" id="portageproblems" rules="none">
252<colgroup><col class="label" /><col /></colgroup> 607<colgroup><col class="label" /><col /></colgroup>
253<tbody valign="top"> 608<tbody valign="top">
254<tr><td class="label"><a class="fn-backref" href="#id2" name="portageproblems">[2]</a></td><td>Common portage problems 609<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Common portage problems
255(<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> 610(<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>
256</tbody> 611</tbody>
257</table> 612</table>
258</div> 613</div>
259<div class="section"> 614<div class="section" id="copyright">
260<h1><a class="toc-backref" href="#id11" id="copyright" name="copyright">Copyright</a></h1> 615<h1><a class="toc-backref" href="#id20">Copyright</a></h1>
261<p>This document has been placed in the public domain.</p> 616<p>This document has been placed in the public domain.</p>
262<!-- vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : --> 617<!-- vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : -->
263</div> 618</div>
264 619
265</div> 620</div>
266<div class="footer"> 621<div class="footer">
267<hr class="footer" /> 622<hr class="footer" />
268<a class="reference" href="glep-0055.txt">View document source</a>. 623<a class="reference external" href="glep-0055.txt">View document source</a>.
269Generated on: 2008-01-05 02:38 UTC. 624Generated on: 2009-05-17 16:58 UTC.
270Generated 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. 625Generated 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.
271 626
272</div> 627</div>
273</body> 628</body>
274</html> 629</html>
275

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.4

  ViewVC Help
Powered by ViewVC 1.1.20