/[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.5
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.5 $
4	Last-Modified: $Date: 2008/01/05 02:36:35 $	4	Last-Modified: $Date: 2009/05/17 20:56:53 $
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	* Use newer bash features.
		43
		44
		45	Current behaviour
		46	=================
		47
		48	Following subsections show what happens if you introduce any of the mentioned
		49	changes in an ebuild and try to install it with portage 2.1.6.13.
		50
		51	Incompatible 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
		64	Result::
		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
		86	Current portage looks for eclasses only in the ``eclass`` directory of a
		87	repository. This results in a fatal error and ebuild being masked by corruption
		88	- might be pretty confusing to users.
		89
		90	New 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
		103	Result::
		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
		114	Not that bad as user is advised to upgrade portage.
		115
		116	New 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
		125	Not the best error message, especially if there are lots of them.
		126
		127	Use newer bash features
		128	-----------------------
		129
		130	``\|&`` is a new type of redirection added in bash-4. It cannot be used even in
		131	local 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
		141	Result::
		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
		163	Again, not the best error.
41		164
42	Abstract solution	165	Abstract solution
43	=================	166	=================
44		167
45	A solution to this problem has to lift those limitations and the only way to do	168	A solution to this problem has to lift those limitations and the only way to do
…		…
53	Proposed solution	176	Proposed solution
54	=================	177	=================
55		178
56	The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This	179	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	180	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	181	is 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
60	the package managers.	183	the package managers.
61		184
62		185
63	Specification	186	Specification
64	=============	187	=============
65		188
66	Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an	189	Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an
67	optional part, and ``<EAPI>`` is the EAPI of the ebuild.	190	optional part, and ``<EAPI>`` is the EAPI of the ebuild.
68		191
69	Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the	192	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	193	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:	194	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		195
81	Ebuilds with unsupported EAPIs are masked.	196	Ebuilds with unsupported EAPIs are masked.
82		197
83	QA tools should consider it an error for both EAPIs to be set explicitly to	198	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	199	ebuild.
85	in such cases.
86		200
87	Examples:	201	Examples:
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
116	Note that it is still not permitted to have more than one ebuild with equal	212	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	213	category, package name, and version. Although it would have the advantage of
118	allowing to provide backward compatible ebuilds, it would introduce problems	214	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	215	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	216	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	217	are equivalent, i.e. installing any of them has exactly the same effect on a
122	system.	218	given system.
123		219
124	Application	220	Also note that it is not a new restriction. It is already possible to illegally
		221	have multiple versions with different EAPIs as e.g. ``1.0 == 1.00 == 1.00-r0``
		222	and hence you could have ``foo-1.0.ebuild`` with EAPI X and ``foo-1.00.ebuild``
		223	with EAPI Y.
		224
		225	Summary of ideas
125	===========	226	================
126		227
127	Note that the developers should only set the pre-source EAPI. The process	228	EAPI-suffixed ebuilds (proposed solution)
128	described above is only necessary to avoid undefined behaviour in corner cases	229	-----------------------------------------
129	and to retain backwards compatibility.
130		230
131	QA tools may warn if the post-source EAPI is set at all, thus helping with the	231	Properties:
132	transition to the new format.	232	* Can be used right away: yes
		233	* Hurts performance: no
133		234
134	Other ideas	235	Some say it is clear and simple, others that it is ugly and unintuitive.
135	===========
136		236
137	There were some other solutions proposed on the mailing list:	237	EAPI 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	240	One 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``	243	Properties:
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
		247	This is equivalent to the proposed solution.
		248
		249	Some say it is better because the extension is static.
		250
		251	Easily fetchable EAPI inside the ebuild
		252	---------------------------------------
		253
		254	Properties:
		255	* Can be used right away: no
		256	* Hurts performance: yes
		257
		258	Cannot be used right away as it would trigger the errors shown in Current
		259	behaviour section for old package managers.
		260
		261	Performance decrease comes from the fact that with version format changes in the
		262	picture package managers need EAPI to parse the ebuild's version. That means that merely
		263	picking the best version of a package requires loading EAPI (from cache or the
		264	ebuild) for each available ebuild.
		265
		266	Here is more or less how the package manager figures out the best available
		267	version 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
		289	The difference is in for how many versions the package manager needs to hit
		290	cache. With EAPI in the ebuild it needs to do that for all versions, with EAPI
		291	in the filename it depends on versions visibility.
		292	For 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
		294	package. With EAPI in the filename it will read metadata only for versions
		295	6, 5 and 4. With EAPI in the ebuild it needs to load metadata for all versions.
		296
		297	It'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
		300	Easily fetchable EAPI inside the ebuild and one-time extension change
		301	---------------------------------------------------------------------
		302
		303	Properties:
		304	* Can be used right away: yes
		305	* Hurts performance: yes
		306
		307	Performance decrease as described in the previous section.
		308
		309	Some say it is clear and simple, others that it is confusing and unintuitive,
		310	because 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/	312	Use 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).	315	Properties:
		316	* Can be used right away: yes
		317	* Hurts performance: yes
		318
		319	Performance decrease comes from the fact that it adds several more directory
		320	reads.
		321
155	* Makes it much harder for maintainers to see what they have.	322	Some say that it makes it much harder for maintainers to see what they have.
156
157		323
158	References	324	References
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
 Legend:



Removed from v.1.1
 


changed lines


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

	ViewVC Help
Powered by ViewVC 1.1.20