1 |
peper 08/01/05 02:36:36 |
2 |
|
3 |
Modified: glep-0001.txt |
4 |
Added: glep-0055.txt |
5 |
Log: |
6 |
Add GLEP 55 txt. |
7 |
|
8 |
Revision Changes Path |
9 |
1.9 xml/htdocs/proj/en/glep/glep-0001.txt |
10 |
|
11 |
<<Binary file>> |
12 |
|
13 |
|
14 |
1.1 xml/htdocs/proj/en/glep/glep-0055.txt |
15 |
|
16 |
file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0055.txt?rev=1.1&view=markup |
17 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0055.txt?rev=1.1&content-type=text/plain |
18 |
|
19 |
Index: glep-0055.txt |
20 |
=================================================================== |
21 |
GLEP: 55 |
22 |
Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI) |
23 |
Version: $Revision: 1.1 $ |
24 |
Last-Modified: $Date: 2008/01/05 02:36:35 $ |
25 |
Author: Piotr JaroszyĆski <peper@g.o> |
26 |
Status: Draft |
27 |
Type: Standards Track |
28 |
Content-Type: text/x-rst |
29 |
Created: 17-Dec-2007 |
30 |
Post-History: 17-Dec-2007, 22-Dec-2007 |
31 |
|
32 |
"A little learning is a dangerous thing; drink deep, or taste not the Pierian |
33 |
spring: there shallow draughts intoxicate the brain, and drinking largely |
34 |
sobers us again." |
35 |
|
36 |
-- Alexander Pope, An Essay on Criticism |
37 |
|
38 |
Abstract |
39 |
======== |
40 |
|
41 |
This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for |
42 |
example, foo-1.2.3.ebuild-1). |
43 |
|
44 |
Problem |
45 |
======= |
46 |
|
47 |
The current way of specifying the EAPI in ebuilds is flawed. In order to get the |
48 |
EAPI the package manager needs to source the ebuild, which itself needs the EAPI |
49 |
in the first place. Otherwise it imposes a serious limitation, namely every ebuild, |
50 |
using any of the future EAPIs, will have to be source'able by old package |
51 |
managers and hence there is no way to: |
52 |
|
53 |
* Change behaviour of inherit in any way (for example, to extend or change |
54 |
eclass functionality). |
55 |
|
56 |
* Add new global scope functions in any sane way. |
57 |
|
58 |
* Extend versioning rules in an EAPI - for example, addition of the scm |
59 |
suffix - GLEP54 [#GLEP54]_. |
60 |
|
61 |
|
62 |
Abstract solution |
63 |
================= |
64 |
|
65 |
A solution to this problem has to lift those limitations and the only way to do |
66 |
it is to make the EAPI of an ebuild available to the package managers in a way |
67 |
that doesn't require them to source the ebuild. Another important requirement is |
68 |
for the solution to be backward compatible, which has the pleasant side-effect |
69 |
of making the solution applicable in the Gentoo tree right away. Opposed to |
70 |
waiting an arbitrary amount of time, which is never long enough anyway, as the |
71 |
issues listed on the common portage problems page - [#PortageProblems]_ - show. |
72 |
|
73 |
Proposed solution |
74 |
================= |
75 |
|
76 |
The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This |
77 |
allows package managers to trivially read the EAPI from the ebuild filename. It |
78 |
is also backward compatible, because currently ebuilds are recognised by the |
79 |
``.ebuild`` file extension and hence EAPI-suffixed ebuilds are simply ignored by |
80 |
the package managers. |
81 |
|
82 |
|
83 |
Specification |
84 |
============= |
85 |
|
86 |
Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an |
87 |
optional part, and ``<EAPI>`` is the EAPI of the ebuild. |
88 |
|
89 |
Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the |
90 |
EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI |
91 |
used by the ebuild can be established by following these steps: |
92 |
|
93 |
* If the pre-source EAPI is not set it defaults to 0. |
94 |
* If the pre-source EAPI is not recognised it is returned immediately. |
95 |
* If the post-source EAPI is not set, it defaults to the pre-source EAPI. |
96 |
* post-source EAPI is returned. |
97 |
|
98 |
The above process should be only used to generate the metadata cache. Should the |
99 |
pre-source EAPI be unsupported the cache entry cannot be generated. |
100 |
|
101 |
Ebuilds with unsupported EAPIs are masked. |
102 |
|
103 |
QA tools should consider it an error for both EAPIs to be set explicitly to |
104 |
different values. Package managers may warn, but must use the post-source EAPI |
105 |
in such cases. |
106 |
|
107 |
Examples: |
108 |
|
109 |
* ``pkg-1.ebuild``, no EAPI set inside the ebuild |
110 |
pre-source EAPI defaults 0, post-source EAPI defaults to pre-source EAPI. |
111 |
EAPI 0 is used. |
112 |
|
113 |
* ``pkg-2.ebuild-1``, no EAPI set inside the ebuild |
114 |
pre-source EAPI is 1, post-source EAPI defaults to pre-source EAPI. |
115 |
EAPI 1 is used. |
116 |
|
117 |
* ``pkg-3.ebuild``, ``EAPI="1"`` |
118 |
pre-source EAPI defaults to 0, post-source EAPI is 1. |
119 |
EAPI 1 is used. |
120 |
|
121 |
* ``pkg-4.ebuild-2``, ``EAPI="1"`` |
122 |
pre-source EAPI is 2, post-source EAPI is 1. |
123 |
EAPI 1 is used, but note that one should **never** explicitly set both |
124 |
EAPIs to different values. |
125 |
|
126 |
* ``pkg-5.ebuild-2``, no EAPI set inside the ebuild, package manager not supporting EAPI 2 |
127 |
pre-source EAPI is 2, post-source EAPI is never checked. |
128 |
ebuild masked because of the unsupported pre-source EAPI. |
129 |
|
130 |
* ``pkg-6.ebuild``, ``EAPI="2"``, package manager not supporting EAPI 2 |
131 |
pre-source EAPI defaults to 0, post-source EAPI is 2 (assuming the |
132 |
package manager didn't die when sourcing the ebuild thinking that EAPI 0 |
133 |
is used). |
134 |
ebuild masked because of the unsupported post-source EAPI. |
135 |
|
136 |
Note that it is still not permitted to have more than one ebuild with equal |
137 |
category, package name, and version. Although it would have the advantage of |
138 |
allowing to provide backward compatible ebuilds, it would introduce problems |
139 |
too. The first is the requirement to have strict EAPI ordering, the second is |
140 |
ensuring that all the ebuilds for a single category/package-version are |
141 |
equivalent, i.e. installing any of them has exactly the same effect to the |
142 |
system. |
143 |
|
144 |
Application |
145 |
=========== |
146 |
|
147 |
Note that the developers should only set the pre-source EAPI. The process |
148 |
described above is only necessary to avoid undefined behaviour in corner cases |
149 |
and to retain backwards compatibility. |
150 |
|
151 |
QA tools may warn if the post-source EAPI is set at all, thus helping with the |
152 |
transition to the new format. |
153 |
|
154 |
Other ideas |
155 |
=========== |
156 |
|
157 |
There were some other solutions proposed on the mailing list: |
158 |
|
159 |
* Set the EAPI inside the ebuild in a way that makes it easy to fetch it |
160 |
* Doesn't meet the backward compatibility requirement. |
161 |
* Isn't forward compatible either. |
162 |
* Could be confusing as ebuilds, and not without a reason, are |
163 |
considered bash scripts and this would impose additional restrictions. |
164 |
|
165 |
* Do the above and change the ebuild extension to ``.ebuild-ng`` |
166 |
* Meets the backward compatibility requirement. |
167 |
* Still can be confusing. |
168 |
* Isn't really forward compatible. What would be after ``.ebuild-ng``? |
169 |
``.ebuild-ng-ng``? |
170 |
|
171 |
* Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/ |
172 |
* Meets both requirements. |
173 |
* Introduces a noticeable performance hit (several more directory reads |
174 |
in an I/O bound operation). |
175 |
* Makes it much harder for maintainers to see what they have. |
176 |
|
177 |
|
178 |
References |
179 |
========== |
180 |
|
181 |
.. [#GLEP54] GLEP 54, scm package version suffix |
182 |
(http://glep.gentoo.org/glep-0054.html) |
183 |
|
184 |
.. [#PortageProblems] Common portage problems |
185 |
(http://www.gentoo.org/proj/en/portage/doc/common-problems.xml) |
186 |
|
187 |
Copyright |
188 |
========= |
189 |
|
190 |
This document has been placed in the public domain. |
191 |
|
192 |
.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : |
193 |
|
194 |
|
195 |
|
196 |
-- |
197 |
gentoo-commits@g.o mailing list |