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. |
4 |
|
5 |
EAPI and PMS for People Who Haven't Been Paying Attention |
6 |
========================================================= |
7 |
|
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. |
14 |
|
15 |
In basic terms |
16 |
-------------- |
17 |
|
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. |
22 |
|
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. |
26 |
|
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. |
33 |
|
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. |
41 |
|
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. |
47 |
|
48 |
Ebuilds have EAPI '0' unless they explicitly request EAPI '1'. The EAPI |
49 |
'' (empty string) is equivalent to EAPI '0'. |
50 |
|
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. |
57 |
|
58 |
EAPI '1' is EAPI '0', except for the following changes: |
59 |
|
60 |
- Slot deps are allowed. |
61 |
- IUSE defaults are allowed. |
62 |
- The default src_compile works with ECONF_SOURCE. |
63 |
|
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. |
72 |
|
73 |
You will note how EAPI '1' can easily be specified despite EAPI '0' not |
74 |
being completely well defined. |
75 |
|
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). |
78 |
|
79 |
EAPI doesn't specify package manager configuration, VDB or client |
80 |
behaviour. Ebuilds mustn't rely upon any of these. |
81 |
|
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. |
85 |
|
86 |
EAPI in more detail |
87 |
------------------- |
88 |
|
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". |
92 |
|
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. |
96 |
|
97 |
This is an issue with eclasses. It means that: |
98 |
|
99 |
* If EAPI is to be changed, it must be done so before any inherit. |
100 |
|
101 |
* eclasses must not modify EAPI. |
102 |
|
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: |
107 |
|
108 |
if [[ "$EAPI" == "1" ]] ; then |
109 |
DEPEND="foo/bar:2" |
110 |
else |
111 |
DEPEND="=foo/bar-2*" |
112 |
fi |
113 |
|
114 |
But not this: |
115 |
|
116 |
EAPI="1" |
117 |
DEPEND="foo/bar:2" |
118 |
|
119 |
Or this: |
120 |
|
121 |
if [[ "$EAPI" != "1" ]] ; then |
122 |
die "EAPI must be 1" |
123 |
fi |
124 |
|
125 |
Or this: |
126 |
|
127 |
foo_pkg_setup() { |
128 |
[[ "$EAPI" == "1" ]] || die |
129 |
} |
130 |
|
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). |
134 |
|
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). |
143 |
|
144 |
PMS in more detail |
145 |
------------------ |
146 |
|
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. |
153 |
|
154 |
This means that: |
155 |
|
156 |
* The stuff in any particular scm repo is not what the Council will be |
157 |
asked to approve. |
158 |
|
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. |
164 |
|
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. |
168 |
|
169 |
More obscure case in point: $A mustn't contain trailing whitespace. We |
170 |
wouldn't have caught that one either... |
171 |
|
172 |
So far as I'm aware, everyone who's currently working on PMS is working |
173 |
off this repository: |
174 |
|
175 |
http://git.overlays.gentoo.org/gitweb/?p=proj/pms.git |
176 |
|
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...) |
181 |
|
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. |
189 |
|
190 |
-- |
191 |
Ciaran McCreesh |