Hello, I have updated the GLEP, hopefully it is less confusing now and hence the discussion will be more technical.
As I still didn't get the "ok to commit" from our glep folks, read the most current version here: http://dev.gentoo.org/~peper/glep-0055.html http://dev.gentoo.org/~peper/glep-0055.txt -- Best Regards, Piotr Jaroszyński
GLEP: 55 Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI) Version: $Revision: $ Last-Modified: $Date: $ Author: Piotr Jaroszyński <[EMAIL PROTECTED]> 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: * Change 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 backward compatible, because currently ebuilds are recognised by the ``.ebuild`` file extension and hence EAPI-suffixed ebuilds are simply ignored by the package managers. 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-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 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 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. 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, and not without a reason, are considered bash scripts and this would impose additional restrictions. * 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 :