GLEP: 55
Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI)
Version: $Revision: $
Last-Modified: $Date: $
Author: Piotr Jaroszyński <peper@g.o>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 17-Dec-2007
Post-History: 17-Dec-2007
Abstract
========
This GLEP proposes usage of EAPI-suffixed file extensions for ebuilds (for
example, foo-1.2.3.ebuild-1).
Motivation
==========
Including EAPI in the ebuild file extension has the following advantages:
* Possibility to extend the versioning rules in an EAPI, and to use them
immediately in the Gentoo tree. For example, addition of the scm suffix -
GLEP54 [#GLEP54]_.
* Possibility to extend the behaviour of inherit and add new global scope
functions (as a result of not sourcing ebuilds with unsupported EAPI).
Specification
=============
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 0, post-source EAPI defaults to pre-source EAPI.
EAPI 0 is used.
* ``pkg-2.ebuild-0``, no EAPI set inside the ebuild
pre-source EAPI is 0, post-source EAPI defaults to pre-source EAPI.
EAPI 0 is used.
* ``pkg-3.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-4.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 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.
ebuild 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 to provide backward 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 to the
system.
Backwards Compatibility
=======================
Currently ebuilds are recognised by the ``.ebuild`` file extension and hence
EAPI-suffixed ebuilds are simply ignored by the package manager allowing their
immediate usage in the Gentoo tree.
References
==========
.. [#GLEP54] GLEP 54, scm package version suffix
(http://glep.gentoo.org/glep-0054.html)
Copyright
=========
This document has been placed in the public domain.
.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :
|
