en/glep/glep-0055.txt

GLEP: 55
Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)
Version: $Revision: 1.1 $
Last-Modified: $Date: 2008/01/05 02:36:35 $
Author: Piotr Jaroszyński <peper@gentoo.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 17-Dec-2007
Post-History: 17-Dec-2007, 22-Dec-2007

  "A little learning is a dangerous thing; drink deep, or taste not the Pierian
  spring: there shallow draughts intoxicate the brain, and drinking largely
  sobers us again."

  -- Alexander Pope, An Essay on Criticism

Abstract
========

This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for
example, foo-1.2.3.ebuild-1).

Problem
=======

The current way of specifying the EAPI in ebuilds is flawed. In order to get the
EAPI the package manager needs to source the ebuild, which itself needs the EAPI
in the first place. Otherwise it imposes a serious limitation, namely every ebuild,
using any of the future EAPIs, will have to be source'able by old package
managers and hence there is no way to do any of the following:

  *  Change the behaviour of inherit in any way (for example, to extend or change
     eclass functionality).

  *  Add new global scope functions in any sane way.

  *  Extend versioning rules in an EAPI - for example, addition of the scm
     suffix - GLEP54 [#GLEP54]_.


Abstract solution
=================

A solution to this problem has to lift those limitations and the only way to do
it is to make the EAPI of an ebuild available to the package managers in a way
that doesn't require them to source the ebuild. Another important requirement is
for the solution to be backward compatible, which has the pleasant side-effect
of making the solution applicable in the Gentoo tree right away. Opposed to
waiting an arbitrary amount of time, which is never long enough anyway, as the
issues listed on the common portage problems page - [#PortageProblems]_ - show.

Proposed solution
=================

The proposed solution is to use EAPI-suffixed file extensions for ebuilds. This
allows package managers to trivially read the EAPI from the ebuild filename. It
is also backwards compatible, because currently ebuilds are recognised by the
``.ebuild`` file extension and hence EAPI-suffixed ebuilds are simply ignored by
the package managers.


Specification
=============

Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an
optional part, and ``<EAPI>`` is the EAPI of the ebuild.

Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the
EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI
used by the ebuild can be established by following these steps:

  *  If the pre-source EAPI is not set it defaults to 0.
  *  If the pre-source EAPI is not recognised it is returned immediately.
  *  If the post-source EAPI is not set, it defaults to the pre-source EAPI.
  *  post-source EAPI is returned.

The above process should be only used to generate the metadata cache. Should the
pre-source EAPI be unsupported the cache entry cannot be generated.

Ebuilds with unsupported EAPIs are masked.

QA tools should consider it an error for both EAPIs to be set explicitly to
different values. Package managers may warn, but must use the post-source EAPI
in such cases.

Examples:

  *  ``pkg-1.ebuild``, no EAPI set inside the ebuild
       pre-source EAPI defaults to 0, post-source EAPI defaults to pre-source EAPI.
       EAPI 0 is used.

  *  ``pkg-2.ebuild-1``, no EAPI set inside the ebuild
       pre-source EAPI is 1, post-source EAPI defaults to pre-source EAPI.
       EAPI 1 is used.

  *  ``pkg-3.ebuild``, ``EAPI="1"``
       pre-source EAPI defaults to 0, post-source EAPI is 1.
       EAPI 1 is used.

  *  ``pkg-4.ebuild-2``, ``EAPI="1"``
       pre-source EAPI is 2, post-source EAPI is 1.
       EAPI 1 is used, but note that one should **never** explicitly set both
       EAPIs to different values.

  *  ``pkg-5.ebuild-2``, no EAPI set inside the ebuild, package manager not supporting EAPI 2
       pre-source EAPI is 2, post-source EAPI is never checked.
       ebuild is masked because of the unsupported pre-source EAPI.

  *  ``pkg-6.ebuild``, ``EAPI="2"``, package manager not supporting EAPI 2
       pre-source EAPI defaults to 0, post-source EAPI is 2 (assuming the
       package manager didn't die when sourcing the ebuild thinking that EAPI 0
       is used).
       ebuild is masked because of the unsupported post-source EAPI.

Note that it is still not permitted to have more than one ebuild with equal
category, package name, and version. Although it would have the advantage of
allowing authors to provide backwards compatible ebuilds, it would introduce
problems too. The first is the requirement to have strict EAPI ordering, the
second is ensuring that all the ebuilds for a single category/package-version
are equivalent, i.e. installing any of them has exactly the same effect on a
given system.

Application
===========

Note that the developers should only set the pre-source EAPI. The process
described above is only necessary to avoid undefined behaviour in corner cases
and to retain backwards compatibility.

QA tools may warn if the post-source EAPI is set at all, thus helping with the
transition to the new format.

Other ideas
===========

There were some other solutions proposed on the mailing list:

  *  Set the EAPI inside the ebuild in a way that makes it easy to fetch it
       *  Doesn't meet the backward compatibility requirement.
       *  Isn't forward compatible either.
       *  Could be confusing as ebuilds are considered bash scripts and this
          would impose additional restrictions on the ebuild format.

  *  Do the above and change the ebuild extension to ``.ebuild-ng``
       *  Meets the backward compatibility requirement.
       *  Still can be confusing.
       *  Isn't really forward compatible. What would be after ``.ebuild-ng``?
          ``.ebuild-ng-ng``?

  *  Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/
       *  Meets both requirements.
       *  Introduces a noticeable performance hit (several more directory reads
          in an I/O bound operation).
       *  Makes it much harder for maintainers to see what they have.


References
==========

.. [#GLEP54] GLEP 54, scm package version suffix
    (http://glep.gentoo.org/glep-0054.html)

.. [#PortageProblems] Common portage problems
    (http://www.gentoo.org/proj/en/portage/doc/common-problems.xml)

Copyright
=========

This document has been placed in the public domain.

.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :
1	peper	1.1	GLEP: 55
2			Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)
3	antarus	1.2	Version: $Revision: 1.1 $
4			Last-Modified: $Date: 2008/01/05 02:36:35 $
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			Post-History: 17-Dec-2007, 22-Dec-2007
11
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			suffix - GLEP54 [#GLEP54]_.
40
41
42			Abstract solution
43			=================
44
45			A solution to this problem has to lift those limitations and the only way to do
46			it is to make the EAPI of an ebuild available to the package managers in a way
47			that doesn't require them to source the ebuild. Another important requirement is
48			for the solution to be backward compatible, which has the pleasant side-effect
49			of making the solution applicable in the Gentoo tree right away. Opposed to
50			waiting an arbitrary amount of time, which is never long enough anyway, as the
51			issues listed on the common portage problems page - [#PortageProblems]_ - show.
52
53			Proposed solution
54			=================
55
56			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
58	antarus	1.2	is also backwards compatible, because currently ebuilds are recognised by the
59	peper	1.1	``.ebuild`` file extension and hence EAPI-suffixed ebuilds are simply ignored by
60			the package managers.
61
62
63			Specification
64			=============
65
66			Ebuild filename extension syntax: ``ebuild[-<EAPI>]``, where ``[]`` denotes an
67			optional part, and ``<EAPI>`` is the EAPI of the ebuild.
68
69			Let's call the EAPI included in the ebuild filename the pre-source EAPI, and the
70			EAPI set inside the ebuild the post-source EAPI. Given these two, the final EAPI
71			used by the ebuild can be established by following these steps:
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
81			Ebuilds with unsupported EAPIs are masked.
82
83			QA tools should consider it an error for both EAPIs to be set explicitly to
84			different values. Package managers may warn, but must use the post-source EAPI
85			in such cases.
86
87			Examples:
88
89			* ``pkg-1.ebuild``, no EAPI set inside the ebuild
90	antarus	1.2	pre-source EAPI defaults to 0, post-source EAPI defaults to pre-source EAPI.
91	peper	1.1	EAPI 0 is used.
92
93			* ``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.
96
97			* ``pkg-3.ebuild``, ``EAPI="1"``
98			pre-source EAPI defaults to 0, post-source EAPI is 1.
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	antarus	1.2	ebuild is masked because of the unsupported pre-source EAPI.
109	peper	1.1
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	antarus	1.2	ebuild is masked because of the unsupported post-source EAPI.
115	peper	1.1
116			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
118	antarus	1.2	allowing authors to provide backwards compatible ebuilds, it would introduce
119			problems too. The first is the requirement to have strict EAPI ordering, the
120			second is ensuring that all the ebuilds for a single category/package-version
121			are equivalent, i.e. installing any of them has exactly the same effect on a
122			given system.
123	peper	1.1
124			Application
125			===========
126
127			Note that the developers should only set the pre-source EAPI. The process
128			described above is only necessary to avoid undefined behaviour in corner cases
129			and to retain backwards compatibility.
130
131			QA tools may warn if the post-source EAPI is set at all, thus helping with the
132			transition to the new format.
133
134			Other ideas
135			===========
136
137			There were some other solutions proposed on the mailing list:
138
139			* Set the EAPI inside the ebuild in a way that makes it easy to fetch it
140			* Doesn't meet the backward compatibility requirement.
141			* Isn't forward compatible either.
142	antarus	1.2	* Could be confusing as ebuilds are considered bash scripts and this
143			would impose additional restrictions on the ebuild format.
144	peper	1.1
145			* Do the above and change the ebuild extension to ``.ebuild-ng``
146			* Meets the backward compatibility requirement.
147			* Still can be confusing.
148			* Isn't really forward compatible. What would be after ``.ebuild-ng``?
149			``.ebuild-ng-ng``?
150
151			* Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/
152			* Meets both requirements.
153			* Introduces a noticeable performance hit (several more directory reads
154			in an I/O bound operation).
155			* Makes it much harder for maintainers to see what they have.
156
157
158			References
159			==========
160
161			.. [#GLEP54] GLEP 54, scm package version suffix
162			(http://glep.gentoo.org/glep-0054.html)
163
164			.. [#PortageProblems] Common portage problems
165			(http://www.gentoo.org/proj/en/portage/doc/common-problems.xml)
166
167			Copyright
168			=========
169
170			This document has been placed in the public domain.
171
172			.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :