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

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

Parent Directory | Revision Log | View Patch Patch

Revision 1.1		Revision 1.3
1	GLEP: 55	1	GLEP: 55
2	Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)	2	Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)
3	Version: $Revision: 1.1 $	3	Version: $Revision: 1.3 $
4	Last-Modified: $Date: 2008/01/05 02:36:35 $	4	Last-Modified: $Date: 2009/05/17 15:50:27 $
5	Author: Piotr Jaroszyński <peper@gentoo.org>	5	Author: Piotr Jaroszyński <peper@gentoo.org>
6	Status: Draft	6	Status: Draft
7	Type: Standards Track	7	Type: Standards Track
8	Content-Type: text/x-rst	8	Content-Type: text/x-rst
9	Created: 17-Dec-2007	9	Created: 17-Dec-2007
10	Post-History: 17-Dec-2007, 22-Dec-2007	10	Post-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
27	The current way of specifying the EAPI in ebuilds is flawed. In order to get the	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	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,	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	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:	31	managers 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
		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.
41		124
42	Abstract solution	125	Abstract solution
43	=================	126	=================
44		127
45	A solution to this problem has to lift those limitations and the only way to do	128	A solution to this problem has to lift those limitations and the only way to do
…		…
53	Proposed solution	136	Proposed solution
54	=================	137	=================
55		138
56	The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This	139	The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This
57	allows package managers to trivially read the EAPI from the ebuild filename. It	140	allows package managers to trivially read the EAPI from the ebuild filename. It
58	is also backward compatible, because currently ebuilds are recognised by the	141	is also backwards compatible, because currently ebuilds are recognised by the
59	``.ebuild`` file extension and hence EAPI-suffixed ebuilds are simply ignored by	142	``.ebuild`` file extension and hence EAPI-suffixed ebuilds are simply ignored by
60	the package managers.	143	the package managers.
61		144
62		145
63	Specification	146	Specification
64	=============	147	=============
65		148
66	Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an	149	Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an
67	optional part, and ``<EAPI>`` is the EAPI of the ebuild.	150	optional part, and ``<EAPI>`` is the EAPI of the ebuild.
68		151
69	Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the	152	The EAPI used by the ebuild is the EAPI included in the filename if it is set.
70	EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI	153	Otherwise the EAPI set inside the ebuild is used, which defaults to 0 (this is
71	used by the ebuild can be established by following these steps:	154	the 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
78	The above process should be only used to generate the metadata cache. Should the
79	pre-source EAPI be unsupported the cache entry cannot be generated.
80		155
81	Ebuilds with unsupported EAPIs are masked.	156	Ebuilds with unsupported EAPIs are masked.
82		157
83	QA tools should consider it an error for both EAPIs to be set explicitly to	158	It should be considered an error to set the EAPI both in the filename and in the
84	different values. Package managers may warn, but must use the post-source EAPI	159	ebuild.
85	in such cases.
86		160
87	Examples:	161	Examples:
88		162
89	* ``pkg-1.ebuild``, no EAPI set inside the ebuild	163	* ``pkg-1.ebuild``, no EAPI set inside the ebuild
90	pre-source EAPI defaults 0, post-source EAPI defaults to pre-source EAPI.	164	EAPI defaults to 0.
91	EAPI 0 is used.
92		165
93	* ``pkg-2.ebuild-1``, no EAPI set inside the ebuild	166	* ``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.	167	EAPI 1 is used.
96		168
97	* ``pkg-3.ebuild``, ``EAPI="1"``	169	* ``pkg-3.ebuild-1``, ``EAPI="1"``
98	pre-source EAPI defaults to 0, post-source EAPI is 1.	170	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		171
116	Note that it is still not permitted to have more than one ebuild with equal	172	Note that it is still not permitted to have more than one ebuild with equal
117	category, package name, and version. Although it would have the advantage of	173	category, package name, and version. Although it would have the advantage of
118	allowing to provide backward compatible ebuilds, it would introduce problems	174	allowing authors to provide backwards compatible ebuilds, it would introduce
119	too. The first is the requirement to have strict EAPI ordering, the second is	175	problems too. The first is the requirement to have strict EAPI ordering, the
120	ensuring that all the ebuilds for a single category/package-version are	176	second is ensuring that all the ebuilds for a single category/package-version
121	equivalent, i.e. installing any of them has exactly the same effect to the	177	are equivalent, i.e. installing any of them has exactly the same effect on a
122	system.	178	given system.
123		179
124	Application	180	Summary of ideas
125	===========	181	================
126		182
127	Note that the developers should only set the pre-source EAPI. The process	183	EAPI-suffixed ebuilds (proposed solution)
128	described above is only necessary to avoid undefined behaviour in corner cases	184	-----------------------------------------
129	and to retain backwards compatibility.
130		185
131	QA tools may warn if the post-source EAPI is set at all, thus helping with the	186	Properties:
132	transition to the new format.	187	* Can be used right away: yes
		188	* Hurts performance: no
133		189
134	Other ideas	190	Some say it is clear and simple, others that it is ugly and unintuitive.
135	===========
136		191
137	There were some other solutions proposed on the mailing list:	192	EAPI in the filename with one-time extension change
		193	---------------------------------------------------
138		194
139	* Set the EAPI inside the ebuild in a way that makes it easy to fetch it	195	One of the proposed filename formats:
140	* Doesn't meet the backward compatibility requirement.	196	``<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		197
145	* Do the above and change the ebuild extension to ``.ebuild-ng``	198	Properties:
146	* Meets the backward compatibility requirement.	199	* Can be used right away: yes
147	* Still can be confusing.	200	* Hurts performance: no
148	* Isn't really forward compatible. What would be after ``.ebuild-ng``?
149	``.ebuild-ng-ng``?
150		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
151	* Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/	234	Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/
152	* Meets both requirements.	235	---------------------------------------------------------------------
153	* Introduces a noticeable performance hit (several more directory reads	236
154	in an I/O bound operation).	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
155	* Makes it much harder for maintainers to see what they have.	244	Some say that it makes it much harder for maintainers to see what they have.
156
157		245
158	References	246	References
159	==========	247	==========
160		248
161	.. [#GLEP54] GLEP 54, scm package version suffix	249	.. [#GLEP54] GLEP 54, scm package version suffix

 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.3
 Legend:



Removed from v.1.1
 


changed lines


 
Added in v.1.3
-Removed from v.1.1
+Added in v.1.3

	ViewVC Help
Powered by ViewVC 1.1.13