Gentoo Archives: gentoo-dev

From: Ciaran McCreesh <ciaran.mccreesh@××××××××××.com>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] EAPI and PMS for people who haven't been paying attention
Date: Fri, 14 Mar 2008 00:32:59
Message-Id: 20080314003247.7e268713@snowcone
1 It looks like way too many people don't understand EAPI or PMS. In the
2 interests of reducing the amount of noise these people make whenever
3 anyone mentions either, I give you the following guide.
5 EAPI and PMS for People Who Haven't Been Paying Attention
6 =========================================================
8 This isn't a formal specification, and is not technically accurate.
9 Most of this is massively oversimplified. It is focused at developers
10 who aren't themselves directly involved in either package manager
11 development or design of future EAPI features -- it's too technical for
12 end users, who only need two sentences, and not technical enough for
13 people who're deeply involved.
15 In basic terms
16 --------------
18 All ebuilds have an EAPI. The EAPI is a piece of metadata that tells
19 the package manager what rules to follow when using that ebuild.
20 Currently existing EAPIs are '0' and '1'. EAPI doesn't stand for
21 anything.
23 PMS is the Package Manager Specification. It will specify and document
24 EAPIs '0', '1' and any future EAPIs, along with tree and profile
25 layouts and various related requirements.
27 EAPIs allow package managers to add new features without breaking
28 systems using older package managers. They also allow package managers
29 to change behaviour of existing functionality that only works the way
30 it does by fluke, without having to support ebuilds that rely upon
31 implementation flukes that were never supposed to be part of the ebuild
32 API.
34 For example: say a new Portage version comes along with a new dep
35 resolver that's more efficient. But because it uses a different
36 algorithm, it behaves differently with respect to blockers. Having a
37 well defined specification for EAPIs provides a clear cut definition of
38 whether it's ok for Portage to do that (and thus whether any ebuilds
39 that rely upon flukes of the old behaviour must be fixed), or whether
40 it's a Portage bug.
42 Package managers that don't support an ebuild's EAPI mustn't attempt to
43 do anything with that ebuild. They could, for example, display the
44 ebuild as masked in a special way. This removes a lot of (but by no
45 means all of) the upgrade problems and arbitrary "we must wait X months
46 since a release before using new features" guidelines.
48 Ebuilds have EAPI '0' unless they explicitly request EAPI '1'. The EAPI
49 '' (empty string) is equivalent to EAPI '0'.
51 EAPI '0' is what you all know and love. New features won't be going
52 into it. Most, but not all existing ebuilds that aren't EAPI '1' will
53 be EAPI '0' compliant. Some existing ebuilds won't be, since
54 realistically they're relying upon behaviour that can neither be
55 expected to remain the same in future Portage versions nor be
56 independently reimplemented.
58 EAPI '1' is EAPI '0', except for the following changes:
60 - Slot deps are allowed.
61 - IUSE defaults are allowed.
62 - The default src_compile works with ECONF_SOURCE.
64 EAPI '1' was introduced to allow developers to use functionality that
65 was available in Portage at that time. It is defined in terms of
66 changes to EAPI '0'. It does not contain lots of useful things that
67 people want or need because Portage support was not available at the
68 time of writing. It is likely that an EAPI '2' will be introduced at
69 some point that also does not contain lots of useful things, simply
70 because offering some of the things that people want now is better than
71 offering all of them later.
73 You will note how EAPI '1' can easily be specified despite EAPI '0' not
74 being completely well defined.
76 Profile files, etc, don't have an EAPI. You can't use slot deps
77 anywhere in the tree except in ebuilds (see later for eclasses).
79 EAPI doesn't specify package manager configuration, VDB or client
80 behaviour. Ebuilds mustn't rely upon any of these.
82 Portage doesn't, in general, do validation. In particular, it won't
83 moan if you use EAPI '1' features in an EAPI '0' c/p-v. You have to be
84 careful with this.
86 EAPI in more detail
87 -------------------
89 EAPI values are strings. They may or may not be integers. They cannot
90 be compared for anything except equality. The next EAPI might be called
91 "larry-on-wheels".
93 EAPI is metadata for a C/P-V. It is constant across the entire C/P-V,
94 and is subject to the usual metadata invariancy and extraction rules.
95 Currently EAPI is set by the EAPI variable.
97 This is an issue with eclasses. It means that:
99 * If EAPI is to be changed, it must be done so before any inherit.
101 * eclasses must not modify EAPI.
103 * eclasses must work with all EAPIs, and may not require specific EAPIs
104 themselves. They may test for EAPI and do different things depending
105 upon EAPI, so long as those things do not involve erroring out at any
106 stage. So you can do this in an eclass:
108 if [[ "$EAPI" == "1" ]] ; then
109 DEPEND="foo/bar:2"
110 else
111 DEPEND="=foo/bar-2*"
112 fi
114 But not this:
116 EAPI="1"
117 DEPEND="foo/bar:2"
119 Or this:
121 if [[ "$EAPI" != "1" ]] ; then
122 die "EAPI must be 1"
123 fi
125 Or this:
127 foo_pkg_setup() {
128 [[ "$EAPI" == "1" ]] || die
129 }
131 Yes, this is not ideal. No, you can't have it changed for EAPI 0 or 1
132 no matter how much you moan about it (and if you don't understand why
133 not, you really have no business discussing it).
135 This is a bigger issue with global scope commands. It means that future
136 EAPIs can't change behaviour of any global scope callable command, nor
137 can they introduce new global scope callable commands, nor can they
138 change how EAPI is exported, nor can they add new behaviours or
139 environment options that are available for global scope. This means
140 that you can't even have the above modified for EAPI 2. Fixing this
141 requires the suffixes GLEP (and if you don't understand why, kindly
142 avoid wasting everyone's time talking about it).
144 PMS in more detail
145 ------------------
147 PMS is a PDF document that will cover EAPIs 0, 1 and any future EAPIs
148 that come along. At some point in the future, following much extension,
149 proof reading and verification, a particular build of PMS will be
150 submitted to the Council, who may or may not approve it. When new EAPIs
151 come along, and when flaws are discovered in PMS, an updated version
152 will be submitted to the Council, who again may or may not approve it.
154 This means that:
156 * The stuff in any particular scm repo is not what the Council will be
157 asked to approve.
159 * The definition for EAPI '0' will probably change a bunch of times.
160 This won't be to add new features or to change behaviour. Rather, it'll
161 be because we'll find problems with the base specification. In
162 particular, without independent implementations, it's extremely hard to
163 catch many of the things upon which ebuilds rely.
165 Case in point: econf has to be a shell function, and emake has to be a
166 standalone binary. We wouldn't have caught that by working off just one
167 package manager.
169 More obscure case in point: $A mustn't contain trailing whitespace. We
170 wouldn't have caught that one either...
172 So far as I'm aware, everyone who's currently working on PMS is working
173 off this repository:
177 (Sidenote: This may change soon -- when we moved to Gentoo hosting, we
178 were assured that Gentoo infra had cleaned up its act and would no
179 longer be abusing root access for political reasons. Recent events
180 might make us have to reconsider this decision...)
182 Patches can be submitted to pms-bugs@g.o. It's probably wise to
183 talk to me before starting work on something, in case you're about to
184 modify something that someone else is working on. Case in point: I'm
185 currently redoing the env stuff into a nice big table that clearly
186 shows phase validity, value preservation and the like, so if you submit
187 any patches that collide with that I'll Linus you, and we don't have an
188 Andrew Morton.
190 --
191 Ciaran McCreesh


File name MIME type
signature.asc application/pgp-signature


Subject Author
[gentoo-dev] Re: EAPI and PMS for people who haven't been paying attention Duncan <1i5t5.duncan@×××.net>