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

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

  ViewVC Help
Powered by ViewVC 1.1.20