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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (show annotations) (download)
Sun May 17 15:50:27 2009 UTC (5 years, 2 months ago) by peper
Branch: MAIN
Changes since 1.2: +158 -70 lines
File MIME type: text/plain
Update GLEP 55.

1 GLEP: 55
2 Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)
3 Version: $Revision: 1.2 $
4 Last-Modified: $Date: 2008/01/06 02:39:42 $
5 Author: Piotr JaroszyƄski <peper@gentoo.org>
6 Status: Draft
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 17-Dec-2007
10 Post-History: 17-Dec-2007, 22-Dec-2007, 17-May-2009
11
12 "A little learning is a dangerous thing; drink deep, or taste not the Pierian
13 spring: there shallow draughts intoxicate the brain, and drinking largely
14 sobers us again."
15
16 -- Alexander Pope, An Essay on Criticism
17
18 Abstract
19 ========
20
21 This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for
22 example, foo-1.2.3.ebuild-1).
23
24 Problem
25 =======
26
27 The current way of specifying the EAPI in ebuilds is flawed. In order to get the
28 EAPI the package manager needs to source the ebuild, which itself needs the EAPI
29 in the first place. Otherwise it imposes a serious limitation, namely every ebuild,
30 using any of the future EAPIs, will have to be source'able by old package
31 managers and hence there is no way to do any of the following:
32
33 * Change the behaviour of inherit in any way (for example, to extend or change
34 eclass functionality).
35
36 * Add new global scope functions in any sane way.
37
38 * Extend versioning rules in an EAPI - for example, addition of the scm
39 suffix - GLEP54 [#GLEP54]_ or allowing more sensible version formats like
40 ``1-rc1``, ``1-alpha`` etc. to match upstream more closely.
41
42
43 Current behaviour
44 =================
45
46 Following subsections show what happens if you introduce any of the mentioned
47 changes in an ebuild and try to install it with portage 2.1.6.13.
48
49 Incompatible change of inherit (e.g. make it look in the package dir too)
50 -------------------------------------------------------------------------
51
52 ``sys-apps/foo-1.ebuild``::
53
54 EAPI="5"
55 inherit "foo"
56
57 DESCRIPTION=""
58 HOMEPAGE=""
59 SRC_URI=""
60 ...
61
62 Result::
63
64 *
65 * ERROR: sys-apps/foo-1 failed.
66 * Call stack:
67 * ebuild.sh, line 1879: Called _source_ebuild
68 * ebuild.sh, line 1818: Called source '/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild'
69 * foo-1.ebuild, line 6: Called inherit 'foo'
70 * ebuild.sh, line 1218: Called die
71 * The specific snippet of code:
72 * [ ! -e "$location" ] && die "${1}.eclass could not be found by inherit()"
73 * The die message:
74 * foo.eclass could not be found by inherit()
75 *
76 * If you need support, post the topmost build error, and the call stack if relevant.
77 * This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/'
78 *
79
80 !!! All ebuilds that could satisfy "sys-apps/foo" have been masked.
81 !!! One of the following masked packages is required to complete your request:
82 - sys-apps/foo-1 (masked by: corruption)
83
84 Current portage looks for eclasses only in the ``eclass`` directory of a
85 repository. This results in a fatal error and ebuild being masked by corruption
86 - might be pretty confusing to users.
87
88 New global scope function
89 -------------------------
90
91 ``sys-apps/foo-1.ebuild``::
92
93 EAPI="5"
94 new_global_scope_function "foo"
95
96 DESCRIPTION=""
97 HOMEPAGE=""
98 SRC_URI=""
99 ...
100
101 Result::
102
103 /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 7: new_global_scope_function: command not found
104
105 !!! All ebuilds that could satisfy "sys-apps/foo" have been masked.
106 !!! One of the following masked packages is required to complete your request:
107 - sys-apps/foo-1 (masked by: EAPI 5)
108
109 The current version of portage supports EAPI '2'. You must upgrade to a
110 newer version of portage before EAPI masked packages can be installed.
111
112 Not that bad as user is advised to upgrade portage.
113
114 New version format
115 ------------------
116
117 ``sys-apps/foo-2-rc1.ebuild``::
118
119 Invalid ebuild name: /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-2-rc1.ebuild
120
121 emerge: there are no ebuilds to satisfy "sys-apps/foo"
122
123 Not the best error message, especially if there are lots of them.
124
125 Abstract solution
126 =================
127
128 A solution to this problem has to lift those limitations and the only way to do
129 it is to make the EAPI of an ebuild available to the package managers in a way
130 that doesn't require them to source the ebuild. Another important requirement is
131 for the solution to be backward compatible, which has the pleasant side-effect
132 of making the solution applicable in the Gentoo tree right away. Opposed to
133 waiting an arbitrary amount of time, which is never long enough anyway, as the
134 issues listed on the common portage problems page - [#PortageProblems]_ - show.
135
136 Proposed solution
137 =================
138
139 The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This
140 allows package managers to trivially read the EAPI from the ebuild filename. It
141 is also backwards compatible, because currently ebuilds are recognised by the
142 ``.ebuild`` file extension and hence EAPI-suffixed ebuilds are simply ignored by
143 the package managers.
144
145
146 Specification
147 =============
148
149 Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an
150 optional part, and ``<EAPI>`` is the EAPI of the ebuild.
151
152 The EAPI used by the ebuild is the EAPI included in the filename if it is set.
153 Otherwise the EAPI set inside the ebuild is used, which defaults to 0 (this is
154 the current behaviour).
155
156 Ebuilds with unsupported EAPIs are masked.
157
158 It should be considered an error to set the EAPI both in the filename and in the
159 ebuild.
160
161 Examples:
162
163 * ``pkg-1.ebuild``, no EAPI set inside the ebuild
164 EAPI defaults to 0.
165
166 * ``pkg-2.ebuild-1``, no EAPI set inside the ebuild
167 EAPI 1 is used.
168
169 * ``pkg-3.ebuild-1``, ``EAPI="1"``
170 EAPI set in both places - error.
171
172 Note that it is still not permitted to have more than one ebuild with equal
173 category, package name, and version. Although it would have the advantage of
174 allowing authors to provide backwards compatible ebuilds, it would introduce
175 problems too. The first is the requirement to have strict EAPI ordering, the
176 second is ensuring that all the ebuilds for a single category/package-version
177 are equivalent, i.e. installing any of them has exactly the same effect on a
178 given system.
179
180 Summary of ideas
181 ================
182
183 EAPI-suffixed ebuilds (proposed solution)
184 -----------------------------------------
185
186 Properties:
187 * Can be used right away: yes
188 * Hurts performance: no
189
190 Some say it is clear and simple, others that it is ugly and unintuitive.
191
192 EAPI in the filename with one-time extension change
193 ---------------------------------------------------
194
195 One of the proposed filename formats:
196 ``<PKG>-<VER>.eapi-<EAPI>.eb``
197
198 Properties:
199 * Can be used right away: yes
200 * Hurts performance: no
201
202 This is equivalent to the proposed solution.
203
204 Some say it is better because the extension is static.
205
206 Easily fetchable EAPI inside the ebuild
207 ---------------------------------------
208
209 Properties:
210 * Can be used right away: no
211 * Hurts performance: yes
212
213 Cannot be used right away as it would trigger the errors shown in Current
214 behaviour section for old package managers.
215
216 Performance decrease comes from the fact that with version format changes in the
217 picture package managers need EAPI to parse the ebuild's version. That means that merely
218 picking the best version of a package requires loading EAPI (from cache or the
219 ebuild) for each available ebuild.
220
221
222 Easily fetchable EAPI inside the ebuild and one-time extension change
223 ---------------------------------------------------------------------
224
225 Properties:
226 * Can be used right away: yes
227 * Hurts performance: yes
228
229 Performance decrease as described in the previous section.
230
231 Some say it is clear and simple, others that it is confusing and unintuitive,
232 because of the arbitrary format restrictions in what is a bash script otherwise.
233
234 Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/
235 ---------------------------------------------------------------------
236
237 Properties:
238 * Can be used right away: yes
239 * Hurts performance: yes
240
241 Performance decrease comes from the fact that it adds several more directory
242 reads.
243
244 Some say that it makes it much harder for maintainers to see what they have.
245
246 References
247 ==========
248
249 .. [#GLEP54] GLEP 54, scm package version suffix
250 (http://glep.gentoo.org/glep-0054.html)
251
252 .. [#PortageProblems] Common portage problems
253 (http://www.gentoo.org/proj/en/portage/doc/common-problems.xml)
254
255 Copyright
256 =========
257
258 This document has been placed in the public domain.
259
260 .. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :

  ViewVC Help
Powered by ViewVC 1.1.20