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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.2 - (hide annotations) (download) (as text)
Sun Jan 6 02:39:42 2008 UTC (10 years, 5 months ago) by antarus
Branch: MAIN
Changes since 1.1: +16 -20 lines
File MIME type: text/html
Editorially Bless glep 55 per changes I sent to peper

1 peper 1.1 <?xml version="1.0" encoding="utf-8" ?>
2     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 antarus 1.2
5 peper 1.1 <head>
6     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
7     <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
8     <title>GLEP 55 -- Use EAPI-suffixed ebuilds (.ebuild-EAPI)</title>
9     <link rel="stylesheet" href="tools/glep.css" type="text/css" />
10     </head>
11     <body bgcolor="white">
12     <table class="navigation" cellpadding="0" cellspacing="0"
13     width="100%" border="0">
14     <tr><td class="navicon" width="150" height="35">
15     <a href="http://www.gentoo.org/" title="Gentoo Linux Home Page">
16     <img src="http://www.gentoo.org/images/gentoo-new.gif" alt="[Gentoo]"
17     border="0" width="150" height="35" /></a></td>
18     <td class="textlinks" align="left">
19     [<b><a href="http://www.gentoo.org/">Gentoo Linux Home</a></b>]
20 antarus 1.2 [<b><a href="http://www.gentoo.org/proj/en/glep">GLEP Index</a></b>]
21 peper 1.1 [<b><a href="http://www.gentoo.org/proj/en/glep/glep-0055.txt">GLEP Source</a></b>]
22     </td></tr></table>
23     <table class="rfc2822 docutils field-list" frame="void" rules="none">
24     <col class="field-name" />
25     <col class="field-body" />
26     <tbody valign="top">
27     <tr class="field"><th class="field-name">GLEP:</th><td class="field-body">55</td>
28     </tr>
29     <tr class="field"><th class="field-name">Title:</th><td class="field-body">Use EAPI-suffixed ebuilds (.ebuild-EAPI)</td>
30     </tr>
31     <tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1</td>
32     </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>
34     </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>
36     </tr>
37     <tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
38     </tr>
39     <tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
40     </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>
42     </tr>
43     <tr class="field"><th class="field-name">Created:</th><td class="field-body">17-Dec-2007</td>
44     </tr>
45     <tr class="field"><th class="field-name">Post-History:</th><td class="field-body">17-Dec-2007, 22-Dec-2007</td>
46     </tr>
47     </tbody>
48     </table>
49     <hr />
50     <div class="contents topic">
51     <p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
52     <ul class="simple">
53     <li><a class="reference" href="#abstract" id="id3" name="id3">Abstract</a></li>
54     <li><a class="reference" href="#problem" id="id4" name="id4">Problem</a></li>
55     <li><a class="reference" href="#abstract-solution" id="id5" name="id5">Abstract solution</a></li>
56     <li><a class="reference" href="#proposed-solution" id="id6" name="id6">Proposed solution</a></li>
57     <li><a class="reference" href="#specification" id="id7" name="id7">Specification</a></li>
58     <li><a class="reference" href="#application" id="id8" name="id8">Application</a></li>
59     <li><a class="reference" href="#other-ideas" id="id9" name="id9">Other ideas</a></li>
60     <li><a class="reference" href="#references" id="id10" name="id10">References</a></li>
61     <li><a class="reference" href="#copyright" id="id11" name="id11">Copyright</a></li>
62     </ul>
63     </div>
64     <blockquote>
65     <p>&quot;A little learning is a dangerous thing; drink deep, or taste not the Pierian
66     spring: there shallow draughts intoxicate the brain, and drinking largely
67     sobers us again.&quot;</p>
68     <p class="attribution">&mdash;Alexander Pope, An Essay on Criticism</p>
69     </blockquote>
70     <div class="section">
71     <h1><a class="toc-backref" href="#id3" id="abstract" name="abstract">Abstract</a></h1>
72     <p>This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for
73     example, foo-1.2.3.ebuild-1).</p>
74     </div>
75     <div class="section">
76     <h1><a class="toc-backref" href="#id4" id="problem" name="problem">Problem</a></h1>
77     <p>The current way of specifying the EAPI in ebuilds is flawed. In order to get the
78     EAPI the package manager needs to source the ebuild, which itself needs the EAPI
79     in the first place. Otherwise it imposes a serious limitation, namely every ebuild,
80     using any of the future EAPIs, will have to be source'able by old package
81 antarus 1.2 managers and hence there is no way to do any of the following:</p>
82 peper 1.1 <blockquote>
83     <ul class="simple">
84 antarus 1.2 <li>Change the behaviour of inherit in any way (for example, to extend or change
85 peper 1.1 eclass functionality).</li>
86     <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
88     suffix - GLEP54 <a class="footnote-reference" href="#glep54" id="id1" name="id1">[1]</a>.</li>
89     </ul>
90     </blockquote>
91     </div>
92     <div class="section">
93     <h1><a class="toc-backref" href="#id5" id="abstract-solution" name="abstract-solution">Abstract solution</a></h1>
94     <p>A solution to this problem has to lift those limitations and the only way to do
95     it is to make the EAPI of an ebuild available to the package managers in a way
96     that doesn't require them to source the ebuild. Another important requirement is
97     for the solution to be backward compatible, which has the pleasant side-effect
98     of making the solution applicable in the Gentoo tree right away. Opposed to
99     waiting an arbitrary amount of time, which is never long enough anyway, as the
100     issues listed on the common portage problems page - <a class="footnote-reference" href="#portageproblems" id="id2" name="id2">[2]</a> - show.</p>
101     </div>
102     <div class="section">
103     <h1><a class="toc-backref" href="#id6" id="proposed-solution" name="proposed-solution">Proposed solution</a></h1>
104     <p>The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This
105     allows package managers to trivially read the EAPI from the ebuild filename. It
106 antarus 1.2 is also backwards compatible, because currently ebuilds are recognised by the
107 peper 1.1 <tt class="docutils literal"><span class="pre">.ebuild</span></tt> file extension and hence EAPI-suffixed ebuilds are simply ignored by
108     the package managers.</p>
109     </div>
110     <div class="section">
111     <h1><a class="toc-backref" href="#id7" id="specification" name="specification">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
113     optional part, and <tt class="docutils literal"><span class="pre">&lt;EAPI&gt;</span></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
115     EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI
116     used by the ebuild can be established by following these steps:</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
126     pre-source EAPI be unsupported the cache entry cannot be generated.</p>
127     <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
129     different values. Package managers may warn, but must use the post-source EAPI
130     in such cases.</p>
131     <p>Examples:</p>
132     <blockquote>
133     <ul>
134     <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>
136 antarus 1.2 <dd><p class="first last">pre-source EAPI defaults to 0, post-source EAPI defaults to pre-source EAPI.
137 peper 1.1 EAPI 0 is used.</p>
138     </dd>
139     </dl>
140     </li>
141     <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>
143     <dd><p class="first last">pre-source EAPI is 1, post-source EAPI defaults to pre-source EAPI.
144     EAPI 1 is used.</p>
145     </dd>
146     </dl>
147     </li>
148     <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>
150     <dd><p class="first last">pre-source EAPI defaults to 0, post-source EAPI is 1.
151     EAPI 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.
158     EAPI 1 is used, but note that one should <strong>never</strong> explicitly set both
159     EAPIs 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.
166 antarus 1.2 ebuild is masked because of the unsupported pre-source EAPI.</p>
167 peper 1.1 </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
173     package manager didn't die when sourcing the ebuild thinking that EAPI 0
174     is used).
175 antarus 1.2 ebuild is masked because of the unsupported post-source EAPI.</p>
176 peper 1.1 </dd>
177     </dl>
178     </li>
179     </ul>
180     </blockquote>
181     <p>Note that it is still not permitted to have more than one ebuild with equal
182     category, package name, and version. Although it would have the advantage of
183 antarus 1.2 allowing authors to provide backwards compatible ebuilds, it would introduce
184     problems too. The first is the requirement to have strict EAPI ordering, the
185     second is ensuring that all the ebuilds for a single category/package-version
186     are equivalent, i.e. installing any of them has exactly the same effect on a
187     given system.</p>
188 peper 1.1 </div>
189     <div class="section">
190     <h1><a class="toc-backref" href="#id8" id="application" name="application">Application</a></h1>
191     <p>Note that the developers should only set the pre-source EAPI. The process
192     described above is only necessary to avoid undefined behaviour in corner cases
193     and to retain backwards compatibility.</p>
194     <p>QA tools may warn if the post-source EAPI is set at all, thus helping with the
195     transition to the new format.</p>
196     </div>
197     <div class="section">
198     <h1><a class="toc-backref" href="#id9" id="other-ideas" name="other-ideas">Other ideas</a></h1>
199     <p>There were some other solutions proposed on the mailing list:</p>
200     <blockquote>
201     <ul>
202     <li><dl class="first docutils">
203     <dt>Set the EAPI inside the ebuild in a way that makes it easy to fetch it</dt>
204     <dd><ul class="first last simple">
205     <li>Doesn't meet the backward compatibility requirement.</li>
206     <li>Isn't forward compatible either.</li>
207 antarus 1.2 <li>Could be confusing as ebuilds are considered bash scripts and this
208     would impose additional restrictions on the ebuild format.</li>
209 peper 1.1 </ul>
210     </dd>
211     </dl>
212     </li>
213     <li><dl class="first docutils">
214     <dt>Do the above and change the ebuild extension to <tt class="docutils literal"><span class="pre">.ebuild-ng</span></tt></dt>
215     <dd><ul class="first last simple">
216     <li>Meets the backward compatibility requirement.</li>
217     <li>Still can be confusing.</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>
223     </li>
224     <li><dl class="first docutils">
225     <dt>Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/</dt>
226     <dd><ul class="first last simple">
227     <li>Meets both requirements.</li>
228     <li>Introduces a noticeable performance hit (several more directory reads
229     in an I/O bound operation).</li>
230     <li>Makes it much harder for maintainers to see what they have.</li>
231     </ul>
232     </dd>
233     </dl>
234     </li>
235     </ul>
236     </blockquote>
237     </div>
238     <div class="section">
239     <h1><a class="toc-backref" href="#id10" id="references" name="references">References</a></h1>
240     <table class="docutils footnote" frame="void" id="glep54" rules="none">
241     <colgroup><col class="label" /><col /></colgroup>
242     <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
244     (<a class="reference" href="http://glep.gentoo.org/glep-0054.html">http://glep.gentoo.org/glep-0054.html</a>)</td></tr>
245     </tbody>
246     </table>
247     <table class="docutils footnote" frame="void" id="portageproblems" rules="none">
248     <colgroup><col class="label" /><col /></colgroup>
249     <tbody valign="top">
250     <tr><td class="label"><a class="fn-backref" href="#id2" name="portageproblems">[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>
252     </tbody>
253     </table>
254     </div>
255     <div class="section">
256     <h1><a class="toc-backref" href="#id11" id="copyright" name="copyright">Copyright</a></h1>
257     <p>This document has been placed in the public domain.</p>
258     <!-- vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : -->
259     </div>
261     </div>
262     <div class="footer">
263     <hr class="footer" />
264     <a class="reference" href="glep-0055.txt">View document source</a>.
265 antarus 1.2 Generated on: 2008-01-06 02:39 UTC.
266 peper 1.1 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
268     </div>
269     </body>
270     </html>

  ViewVC Help
Powered by ViewVC 1.1.20