--- xml/htdocs/proj/en/glep/glep-0055.html 2008/01/06 02:39:42 1.2 +++ xml/htdocs/proj/en/glep/glep-0055.html 2009/05/17 15:50:27 1.3 @@ -4,10 +4,252 @@ - + GLEP 55 -- Use EAPI-suffixed ebuilds (.ebuild-EAPI) - - + @@ -28,9 +270,9 @@ - + - + @@ -38,27 +280,39 @@ - + - +
-
-

Contents

+
+

Contents

@@ -67,13 +321,13 @@ sobers us again."

—Alexander Pope, An Essay on Criticism

-
-

Abstract

+
+

Abstract

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

-
-

Problem

+
+

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, @@ -85,94 +339,135 @@ 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 [1].
  • +suffix - GLEP54 [1] or allowing more sensible version formats like +1-rc1, 1-alpha etc. to match upstream more closely.
    -
    -

    Abstract solution

    +
    +

    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.

    +
    +
    +
    +

    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 - [2] - show.

    +issues listed on the common portage problems page - [2] - show.

    -
    -

    Proposed solution

    +
    +

    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

    +
    +

    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.

    +

    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.

    -

    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.

    +

    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
      -

      pre-source EAPI defaults to 0, post-source EAPI defaults to pre-source EAPI. -EAPI 0 is used.

      +

      EAPI defaults to 0.

    • 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.

      +

      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.

      +
      pkg-3.ebuild-1, EAPI="1"
      +

      EAPI set in both places - error.

    • @@ -186,74 +481,100 @@ 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
      +
      +

      Summary of ideas

      +
      +

      EAPI-suffixed ebuilds (proposed solution)

      +
      +
      Properties:
        -
      • 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.
      • +
      • Can be used right away: yes
      • +
      • Hurts performance: no
      -
    • -
    • -
      Do the above and change the ebuild extension to .ebuild-ng
      +

      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:
      -
    • Meets the backward compatibility requirement.
    • -
    • Still can be confusing.
    • -
    • Isn't really forward compatible. What would be after .ebuild-ng? -.ebuild-ng-ng?
    • +
    • Can be used right away: yes
    • +
    • Hurts performance: no
    - -
  • -
    Use different subdirectories for different EAPIs, i.e. cat/pkg/eapiX/
    +

    This is equivalent to the proposed solution.

    +

    Some say it is better because the extension is static.

    +
  • +
    +

    Easily fetchable EAPI inside the ebuild

    +
    +
    Properties:
      -
    • 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.
    • +
    • 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.

    +
    +
    +

    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

    + -
    -

    Copyright

    + @@ -261,11 +582,10 @@
    -