/[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 - (hide annotations) (download)
Sun May 17 15:50:27 2009 UTC (5 years, 6 months ago) by peper
Branch: MAIN
Changes since 1.2: +158 -70 lines
File MIME type: text/plain
Update GLEP 55.

1 peper 1.1 GLEP: 55
2     Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)
3 peper 1.3 Version: $Revision: 1.2 $
4     Last-Modified: $Date: 2008/01/06 02:39:42 $
5 peper 1.1 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 peper 1.3 Post-History: 17-Dec-2007, 22-Dec-2007, 17-May-2009
11 peper 1.1
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 antarus 1.2 managers and hence there is no way to do any of the following:
32 peper 1.1
33 antarus 1.2 * Change the behaviour of inherit in any way (for example, to extend or change
34 peper 1.1 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 peper 1.3 suffix - GLEP54 [#GLEP54]_ or allowing more sensible version formats like
40     ``1-rc1``, ``1-alpha`` etc. to match upstream more closely.
41 peper 1.1
42    
43 peper 1.3 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 peper 1.1 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 antarus 1.2 is also backwards compatible, because currently ebuilds are recognised by the
142 peper 1.1 ``.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 peper 1.3 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 peper 1.1
156     Ebuilds with unsupported EAPIs are masked.
157    
158 peper 1.3 It should be considered an error to set the EAPI both in the filename and in the
159     ebuild.
160 peper 1.1
161     Examples:
162    
163     * ``pkg-1.ebuild``, no EAPI set inside the ebuild
164 peper 1.3 EAPI defaults to 0.
165 peper 1.1
166     * ``pkg-2.ebuild-1``, no EAPI set inside the ebuild
167     EAPI 1 is used.
168    
169 peper 1.3 * ``pkg-3.ebuild-1``, ``EAPI="1"``
170     EAPI set in both places - error.
171 peper 1.1
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 antarus 1.2 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 peper 1.1
180 peper 1.3 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 peper 1.1
241 peper 1.3 Performance decrease comes from the fact that it adds several more directory
242     reads.
243 peper 1.1
244 peper 1.3 Some say that it makes it much harder for maintainers to see what they have.
245 peper 1.1
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