diff options
author | Michał Górny <mgorny@gentoo.org> | 2017-09-14 23:14:39 +0200 |
---|---|---|
committer | Ulrich Müller <ulm@gentoo.org> | 2017-10-09 12:08:51 +0200 |
commit | c6fe2071a2e83be2203196ad7f9459941821a034 (patch) | |
tree | d81e1d9898c05917e05203af9803b581dff0d915 /glep-0055.rst | |
parent | glep-0045: Mark Final since GLEP 1 now uses ISO 8601 dates (diff) | |
download | glep-c6fe2071a2e83be2203196ad7f9459941821a034.tar.gz glep-c6fe2071a2e83be2203196ad7f9459941821a034.tar.bz2 glep-c6fe2071a2e83be2203196ad7f9459941821a034.zip |
Rename all GLEPs to .rst
Diffstat (limited to 'glep-0055.rst')
-rw-r--r-- | glep-0055.rst | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/glep-0055.rst b/glep-0055.rst new file mode 100644 index 0000000..078b3f2 --- /dev/null +++ b/glep-0055.rst @@ -0,0 +1,347 @@ +GLEP: 55 +Title: Use EAPI-suffixed ebuilds (.ebuild-EAPI) +Version: $Revision$ +Last-Modified: $Date$ +Author: Piotr Jaroszyński <peper@gentoo.org> +Status: Rejected +Type: Standards Track +Content-Type: text/x-rst +Created: 17-Dec-2007 +Post-History: 17-Dec-2007, 22-Dec-2007, 17-May-2009 + + "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 + +Status +====== + +This GLEP was voted down by the Council in its meeting on 2010-08-23. +The Council rejected it again in its meeting on 2012-05-08, in favour +of parsing the EAPI from the bash assignment statement in ebuilds. + +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 sourceable 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]_ or allowing more sensible version formats like + ``1-rc1``, ``1-alpha`` etc. to match upstream more closely. + + * Use newer bash features. + + +Current behaviour +================= + +Following subsections show what happens if you introduce any of the mentioned +changes in an ebuild and try to install it with portage 2.1.6.13. + +Incompatible change of inherit (e.g. make it look in the package dir too) +------------------------------------------------------------------------- + +``sys-apps/foo-1.ebuild``:: + + EAPI="5" + inherit "foo" + + DESCRIPTION="" + HOMEPAGE="" + SRC_URI="" + ... + +Result:: + + * + * ERROR: sys-apps/foo-1 failed. + * Call stack: + * ebuild.sh, line 1879: Called _source_ebuild + * ebuild.sh, line 1818: Called source '/var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild' + * foo-1.ebuild, line 6: Called inherit 'foo' + * ebuild.sh, line 1218: Called die + * The specific snippet of code: + * [ ! -e "$location" ] && die "${1}.eclass could not be found by inherit()" + * The die message: + * foo.eclass could not be found by inherit() + * + * If you need support, post the topmost build error, and the call stack if relevant. + * This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/' + * + + !!! All ebuilds that could satisfy "sys-apps/foo" have been masked. + !!! One of the following masked packages is required to complete your request: + - sys-apps/foo-1 (masked by: corruption) + +Current portage looks for eclasses only in the ``eclass`` directory of a +repository. This results in a fatal error and ebuild being masked by corruption +- might be pretty confusing to users. + +New global scope function +------------------------- + +``sys-apps/foo-1.ebuild``:: + + EAPI="5" + new_global_scope_function "foo" + + DESCRIPTION="" + HOMEPAGE="" + SRC_URI="" + ... + +Result:: + + /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 7: new_global_scope_function: command not found + + !!! All ebuilds that could satisfy "sys-apps/foo" have been masked. + !!! One of the following masked packages is required to complete your request: + - sys-apps/foo-1 (masked by: EAPI 5) + + The current version of portage supports EAPI '2'. You must upgrade to a + newer version of portage before EAPI masked packages can be installed. + +Not that bad as user is advised to upgrade portage. + +New version format +------------------ + +``sys-apps/foo-2-rc1.ebuild``:: + + Invalid ebuild name: /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-2-rc1.ebuild + + emerge: there are no ebuilds to satisfy "sys-apps/foo" + +Not the best error message, especially if there are lots of them. + +Use newer bash features +----------------------- + +``|&`` is a new type of redirection added in bash-4. It cannot be used even in +local scope as bash still parses the whole ebuild. + +``sys-apps/foo-1.ebuild``:: + + EAPI="5" + + foo() { + echo "foo" |& cat + } + +Result:: + + /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: syntax error near unexpected token `&' + /var/lib/gentoo/repositories/peper/sys-apps/foo/foo-1.ebuild: line 8: ` echo "foo" |& cat' + * + * ERROR: sys-apps/foo-1 failed. + * Call stack: + * ebuild.sh, line 1879: Called _source_ebuild + * ebuild.sh, line 1818: Called die + * The specific snippet of code: + * source "${EBUILD}" || die "error sourcing ebuild" + * The die message: + * error sourcing ebuild + * + * If you need support, post the topmost build error, and the call stack if relevant. + * This ebuild is from an overlay: '/var/lib/gentoo/repositories/peper/' + * ... done! + + !!! All ebuilds that could satisfy "sys-apps/foo" have been masked. + !!! One of the following masked packages is required to complete your request: + - sys-apps/foo-1 (masked by: corruption) + +Again, not the best error. + +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. + +The EAPI used by the ebuild is the EAPI included in the filename if it is set. +Otherwise the EAPI set inside the ebuild is used, which defaults to 0 (this is +the current behaviour). + +Ebuilds with unsupported EAPIs are masked. + +It should be considered an error to set the EAPI both in the filename and in the +ebuild. + +Examples: + + * ``pkg-1.ebuild``, no EAPI set inside the ebuild + EAPI defaults to 0. + + * ``pkg-2.ebuild-1``, no EAPI set inside the ebuild + EAPI 1 is used. + + * ``pkg-3.ebuild-1``, ``EAPI="1"`` + EAPI set in both places - error. + +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. + +Also note that it is not a new restriction. It is already possible to illegally +have multiple versions with different EAPIs as e.g. ``1.0 == 1.00 == 1.00-r0`` +and hence you could have ``foo-1.0.ebuild`` with EAPI X and ``foo-1.00.ebuild`` +with EAPI Y. + +Summary of ideas +================ + +EAPI-suffixed ebuilds (proposed solution) +----------------------------------------- + +Properties: + * Can be used right away: yes + * Hurts performance: no + +Some say it is clear and simple, others that it is ugly and unintuitive. + +EAPI in the filename with one-time extension change +--------------------------------------------------- + +One of the proposed filename formats: +``<PKG>-<VER>.eapi-<EAPI>.eb`` + +Properties: + * Can be used right away: yes + * Hurts performance: no + +This is equivalent to the proposed solution. + +Some say it is better because the extension is static. + +Easily fetchable EAPI inside the ebuild +--------------------------------------- + +Properties: + * Can be used right away: no + * Hurts performance: yes + +Cannot be used right away as it would trigger the errors shown in Current +behaviour section for old package managers. + +Performance decrease comes from the fact that with version format changes in the +picture package managers need EAPI to parse the ebuild's version. That means that merely +picking the best version of a package requires loading EAPI (from cache or the +ebuild) for each available ebuild. + +Here is more or less how the package manager figures out the best available +version for a package with N versions available. + + * EAPI in the filename + + * Read the directory containing the package - readdir() + * For each ebuild, read its EAPI and using that parse its version - no I/O + * Sort the versions - no I/O + * Going down from the highest to the lowest version + + * Get the metadata from cache - 2 x stat() + read() + * break if the version is visible + + * EAPI in the ebuild + + * Read the directory containing the package - readdir() + * For each ebuild load its metadata from cache to get its EAPI - N x (2 x stat() + read()) + * Sort the versions - no I/O + * Going down from the highest to the lowest version + + * (metadata is already loaded) - no I/O + * break if the version is visible - no I/O + +The difference is in for how many versions the package manager needs to hit +cache. With EAPI in the ebuild it needs to do that for all versions, with EAPI +in the filename it depends on versions visibility. +For example, package foo has versions 1, 2, 3, 4, 5 and 6. 6 is masked, 5 is +~arch and 1,2,3 and 4 are arch. Say, the user accepts only arch for this +package. With EAPI in the filename it will read metadata only for versions +6, 5 and 4. With EAPI in the ebuild it needs to load metadata for all versions. + +It's hard to say what's the average case, but surely the worst case scenario +(when only the lowest version is visible) is uncommon. + +Easily fetchable EAPI inside the ebuild and one-time extension change +--------------------------------------------------------------------- + +Properties: + * Can be used right away: yes + * Hurts performance: yes + +Performance decrease as described in the previous section. + +Some say it is clear and simple, others that it is confusing and unintuitive, +because of the arbitrary format restrictions in what is a bash script otherwise. + +Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/ +--------------------------------------------------------------------- + +Properties: + * Can be used right away: yes + * Hurts performance: yes + +Performance decrease comes from the fact that it adds several more directory +reads. + +Some say that it 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 + (https://wiki.gentoo.org/wiki/Project:Portage/Common_problems) + +Copyright +========= + +This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 +Unported License. To view a copy of this license, visit +http://creativecommons.org/licenses/by-sa/3.0/. + +.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : |