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

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

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

Revision 1.2 Revision 1.6
1GLEP: 55 1GLEP: 55
2Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI) 2Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)
3Version: $Revision: 1.2 $ 3Version: $Revision: 1.6 $
4Last-Modified: $Date: 2008/01/06 02:39:42 $ 4Last-Modified: $Date: 2012/05/09 19:37:01 $
5Author: Piotr Jaroszyński <peper@gentoo.org> 5Author: Piotr Jaroszyński <peper@gentoo.org>
6Status: Draft 6Status: Rejected
7Type: Standards Track 7Type: Standards Track
8Content-Type: text/x-rst 8Content-Type: text/x-rst
9Created: 17-Dec-2007 9Created: 17-Dec-2007
10Post-History: 17-Dec-2007, 22-Dec-2007 10Post-History: 17-Dec-2007, 22-Dec-2007, 17-May-2009
11 11
12 "A little learning is a dangerous thing; drink deep, or taste not the Pierian 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 13 spring: there shallow draughts intoxicate the brain, and drinking largely
14 sobers us again." 14 sobers us again."
15 15
16 -- Alexander Pope, An Essay on Criticism 16 -- Alexander Pope, An Essay on Criticism
17
18Status
19======
20
21This GLEP was voted down by the Council in its meeting on 2010-08-23.
22The Council rejected it again in its meeting on 2012-05-08, in favour
23of parsing the EAPI from the bash assignment statement in ebuilds.
17 24
18Abstract 25Abstract
19======== 26========
20 27
21This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for 28This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for
34 eclass functionality). 41 eclass functionality).
35 42
36 * Add new global scope functions in any sane way. 43 * Add new global scope functions in any sane way.
37 44
38 * Extend versioning rules in an EAPI - for example, addition of the scm 45 * Extend versioning rules in an EAPI - for example, addition of the scm
39 suffix - GLEP54 [#GLEP54]_. 46 suffix - GLEP54 [#GLEP54]_ or allowing more sensible version formats like
47 ``1-rc1``, ``1-alpha`` etc. to match upstream more closely.
40 48
49 * Use newer bash features.
50
51
52Current behaviour
53=================
54
55Following subsections show what happens if you introduce any of the mentioned
56changes in an ebuild and try to install it with portage 2.1.6.13.
57
58Incompatible change of inherit (e.g. make it look in the package dir too)
59-------------------------------------------------------------------------
60
61``sys-apps/foo-1.ebuild``::
62
63 EAPI="5"
64 inherit "foo"
65
66 DESCRIPTION=""
67 HOMEPAGE=""
68 SRC_URI=""
69 ...
70
71Result::
72
73 *
74 * ERROR: sys-apps/foo-1 failed.
75 * Call stack:
76 * ebuild.sh, line 1879: Called _source_ebuild
77 * ebuild.sh, line 1818: Called source '/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild'
78 * foo-1.ebuild, line 6: Called inherit 'foo'
79 * ebuild.sh, line 1218: Called die
80 * The specific snippet of code:
81 * [ ! -e "$location" ] && die "${1}.eclass could not be found by inherit()"
82 * The die message:
83 * foo.eclass could not be found by inherit()
84 *
85 * If you need support, post the topmost build error, and the call stack if relevant.
86 * This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/'
87 *
88
89 !!! All ebuilds that could satisfy "sys-apps/foo" have been masked.
90 !!! One of the following masked packages is required to complete your request:
91 - sys-apps/foo-1 (masked by: corruption)
92
93Current portage looks for eclasses only in the ``eclass`` directory of a
94repository. This results in a fatal error and ebuild being masked by corruption
95- might be pretty confusing to users.
96
97New global scope function
98-------------------------
99
100``sys-apps/foo-1.ebuild``::
101
102 EAPI="5"
103 new_global_scope_function "foo"
104
105 DESCRIPTION=""
106 HOMEPAGE=""
107 SRC_URI=""
108 ...
109
110Result::
111
112 /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 7: new_global_scope_function: command not found
113
114 !!! All ebuilds that could satisfy "sys-apps/foo" have been masked.
115 !!! One of the following masked packages is required to complete your request:
116 - sys-apps/foo-1 (masked by: EAPI 5)
117
118 The current version of portage supports EAPI '2'. You must upgrade to a
119 newer version of portage before EAPI masked packages can be installed.
120
121Not that bad as user is advised to upgrade portage.
122
123New version format
124------------------
125
126``sys-apps/foo-2-rc1.ebuild``::
127
128 Invalid ebuild name: /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-2-rc1.ebuild
129
130 emerge: there are no ebuilds to satisfy "sys-apps/foo"
131
132Not the best error message, especially if there are lots of them.
133
134Use newer bash features
135-----------------------
136
137``|&`` is a new type of redirection added in bash-4. It cannot be used even in
138local scope as bash still parses the whole ebuild.
139
140``sys-apps/foo-1.ebuild``::
141
142 EAPI="5"
143
144 foo() {
145 echo "foo" |& cat
146 }
147
148Result::
149
150 /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: syntax error near unexpected token `&'
151 /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: ` echo "foo" |& cat'
152 *
153 * ERROR: sys-apps/foo-1 failed.
154 * Call stack:
155 * ebuild.sh, line 1879: Called _source_ebuild
156 * ebuild.sh, line 1818: Called die
157 * The specific snippet of code:
158 * source "${EBUILD}" || die "error sourcing ebuild"
159 * The die message:
160 * error sourcing ebuild
161 *
162 * If you need support, post the topmost build error, and the call stack if relevant.
163 * This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/'
164 * ... done!
165
166 !!! All ebuilds that could satisfy "sys-apps/foo" have been masked.
167 !!! One of the following masked packages is required to complete your request:
168 - sys-apps/foo-1 (masked by: corruption)
169
170Again, not the best error.
41 171
42Abstract solution 172Abstract solution
43================= 173=================
44 174
45A solution to this problem has to lift those limitations and the only way to do 175A solution to this problem has to lift those limitations and the only way to do
64============= 194=============
65 195
66Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an 196Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an
67optional part, and ``<EAPI>`` is the EAPI of the ebuild. 197optional part, and ``<EAPI>`` is the EAPI of the ebuild.
68 198
69Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the 199The EAPI used by the ebuild is the EAPI included in the filename if it is set.
70EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI 200Otherwise the EAPI set inside the ebuild is used, which defaults to 0 (this is
71used by the ebuild can be established by following these steps: 201the current behaviour).
72
73 * If the pre-source EAPI is not set it defaults to 0.
74 * If the pre-source EAPI is not recognised it is returned immediately.
75 * If the post-source EAPI is not set, it defaults to the pre-source EAPI.
76 * post-source EAPI is returned.
77
78The above process should be only used to generate the metadata cache. Should the
79pre-source EAPI be unsupported the cache entry cannot be generated.
80 202
81Ebuilds with unsupported EAPIs are masked. 203Ebuilds with unsupported EAPIs are masked.
82 204
83QA tools should consider it an error for both EAPIs to be set explicitly to 205It should be considered an error to set the EAPI both in the filename and in the
84different values. Package managers may warn, but must use the post-source EAPI 206ebuild.
85in such cases.
86 207
87Examples: 208Examples:
88 209
89 * ``pkg-1.ebuild``, no EAPI set inside the ebuild 210 * ``pkg-1.ebuild``, no EAPI set inside the ebuild
90 pre-source EAPI defaults to 0, post-source EAPI defaults to pre-source EAPI. 211 EAPI defaults to 0.
91 EAPI 0 is used.
92 212
93 * ``pkg-2.ebuild-1``, no EAPI set inside the ebuild 213 * ``pkg-2.ebuild-1``, no EAPI set inside the ebuild
94 pre-source EAPI is 1, post-source EAPI defaults to pre-source EAPI.
95 EAPI 1 is used. 214 EAPI 1 is used.
96 215
97 * ``pkg-3.ebuild``, ``EAPI="1"`` 216 * ``pkg-3.ebuild-1``, ``EAPI="1"``
98 pre-source EAPI defaults to 0, post-source EAPI is 1. 217 EAPI set in both places - error.
99 EAPI 1 is used.
100
101 * ``pkg-4.ebuild-2``, ``EAPI="1"``
102 pre-source EAPI is 2, post-source EAPI is 1.
103 EAPI 1 is used, but note that one should **never** explicitly set both
104 EAPIs to different values.
105
106 * ``pkg-5.ebuild-2``, no EAPI set inside the ebuild, package manager not supporting EAPI 2
107 pre-source EAPI is 2, post-source EAPI is never checked.
108 ebuild is masked because of the unsupported pre-source EAPI.
109
110 * ``pkg-6.ebuild``, ``EAPI="2"``, package manager not supporting EAPI 2
111 pre-source EAPI defaults to 0, post-source EAPI is 2 (assuming the
112 package manager didn't die when sourcing the ebuild thinking that EAPI 0
113 is used).
114 ebuild is masked because of the unsupported post-source EAPI.
115 218
116Note that it is still not permitted to have more than one ebuild with equal 219Note that it is still not permitted to have more than one ebuild with equal
117category, package name, and version. Although it would have the advantage of 220category, package name, and version. Although it would have the advantage of
118allowing authors to provide backwards compatible ebuilds, it would introduce 221allowing authors to provide backwards compatible ebuilds, it would introduce
119problems too. The first is the requirement to have strict EAPI ordering, the 222problems too. The first is the requirement to have strict EAPI ordering, the
120second is ensuring that all the ebuilds for a single category/package-version 223second is ensuring that all the ebuilds for a single category/package-version
121are equivalent, i.e. installing any of them has exactly the same effect on a 224are equivalent, i.e. installing any of them has exactly the same effect on a
122given system. 225given system.
123 226
124Application 227Also note that it is not a new restriction. It is already possible to illegally
228have multiple versions with different EAPIs as e.g. ``1.0 == 1.00 == 1.00-r0``
229and hence you could have ``foo-1.0.ebuild`` with EAPI X and ``foo-1.00.ebuild``
230with EAPI Y.
231
232Summary of ideas
125=========== 233================
126 234
127Note that the developers should only set the pre-source EAPI. The process 235EAPI-suffixed ebuilds (proposed solution)
128described above is only necessary to avoid undefined behaviour in corner cases 236-----------------------------------------
129and to retain backwards compatibility.
130 237
131QA tools may warn if the post-source EAPI is set at all, thus helping with the 238Properties:
132transition to the new format. 239 * Can be used right away: yes
240 * Hurts performance: no
133 241
134Other ideas 242Some say it is clear and simple, others that it is ugly and unintuitive.
135===========
136 243
137There were some other solutions proposed on the mailing list: 244EAPI in the filename with one-time extension change
245---------------------------------------------------
138 246
139 * Set the EAPI inside the ebuild in a way that makes it easy to fetch it 247One of the proposed filename formats:
140 * Doesn't meet the backward compatibility requirement. 248``<PKG>-<VER>.eapi-<EAPI>.eb``
141 * Isn't forward compatible either.
142 * Could be confusing as ebuilds are considered bash scripts and this
143 would impose additional restrictions on the ebuild format.
144 249
145 * Do the above and change the ebuild extension to ``.ebuild-ng`` 250Properties:
146 * Meets the backward compatibility requirement. 251 * Can be used right away: yes
147 * Still can be confusing. 252 * Hurts performance: no
148 * Isn't really forward compatible. What would be after ``.ebuild-ng``?
149 ``.ebuild-ng-ng``?
150 253
254This is equivalent to the proposed solution.
255
256Some say it is better because the extension is static.
257
258Easily fetchable EAPI inside the ebuild
259---------------------------------------
260
261Properties:
262 * Can be used right away: no
263 * Hurts performance: yes
264
265Cannot be used right away as it would trigger the errors shown in Current
266behaviour section for old package managers.
267
268Performance decrease comes from the fact that with version format changes in the
269picture package managers need EAPI to parse the ebuild's version. That means that merely
270picking the best version of a package requires loading EAPI (from cache or the
271ebuild) for each available ebuild.
272
273Here is more or less how the package manager figures out the best available
274version for a package with N versions available.
275
276 * EAPI in the filename
277
278 * Read the directory containing the package - readdir()
279 * For each ebuild, read its EAPI and using that parse its version - no I/O
280 * Sort the versions - no I/O
281 * Going down from the highest to the lowest version
282
283 * Get the metadata from cache - 2 x stat() + read()
284 * break if the version is visible
285
286 * EAPI in the ebuild
287
288 * Read the directory containing the package - readdir()
289 * For each ebuild load its metadata from cache to get its EAPI - N x (2 x stat() + read())
290 * Sort the versions - no I/O
291 * Going down from the highest to the lowest version
292
293 * (metadata is already loaded) - no I/O
294 * break if the version is visible - no I/O
295
296The difference is in for how many versions the package manager needs to hit
297cache. With EAPI in the ebuild it needs to do that for all versions, with EAPI
298in the filename it depends on versions visibility.
299For example, package foo has versions 1, 2, 3, 4, 5 and 6. 6 is masked, 5 is
300~arch and 1,2,3 and 4 are arch. Say, the user accepts only arch for this
301package. With EAPI in the filename it will read metadata only for versions
3026, 5 and 4. With EAPI in the ebuild it needs to load metadata for all versions.
303
304It's hard to say what's the avarage case, but surely the worst case scenario
305(when only the lowest version is visible) is uncommon.
306
307Easily fetchable EAPI inside the ebuild and one-time extension change
308---------------------------------------------------------------------
309
310Properties:
311 * Can be used right away: yes
312 * Hurts performance: yes
313
314Performance decrease as described in the previous section.
315
316Some say it is clear and simple, others that it is confusing and unintuitive,
317because of the arbitrary format restrictions in what is a bash script otherwise.
318
151 * Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/ 319Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/
152 * Meets both requirements. 320---------------------------------------------------------------------
153 * Introduces a noticeable performance hit (several more directory reads 321
154 in an I/O bound operation). 322Properties:
323 * Can be used right away: yes
324 * Hurts performance: yes
325
326Performance decrease comes from the fact that it adds several more directory
327reads.
328
155 * Makes it much harder for maintainers to see what they have. 329Some say that it makes it much harder for maintainers to see what they have.
156
157 330
158References 331References
159========== 332==========
160 333
161.. [#GLEP54] GLEP 54, scm package version suffix 334.. [#GLEP54] GLEP 54, scm package version suffix

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.6

  ViewVC Help
Powered by ViewVC 1.1.20