1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
|
<?xml version="1.0"?>
<guide self="eclass-writing/">
<chapter>
<title>Eclass Writing Guide</title>
<body>
<p>
This section provides a brief introduction to eclass authoring.
</p>
<important>
You should reread the <uri link="::general-concepts/overlay#Overlay and Eclasses"/>
and <uri link="::general-concepts/portage-cache"/> sections before continuing.
</important>
<section>
<title>Purpose of Eclasses</title>
<body>
<p>
An eclass is a collection of code which can be used by more than one ebuild. At
the time of writing, all eclasses live in the <c>eclass/</c> directory in the tree.
Roughly speaking, there are three kinds of eclass:
</p>
<ul>
<li>
Those which provide common functions which are used by many ebuilds (for
example, <c>eutils</c>, <c>versionator</c>, <c>cvs</c>, <c>bash-completion</c>)
</li>
<li>
Those which provide a basic build system for many similar packages (for
example, <c>vim-plugin</c>, <c>kde</c>)
</li>
<li>
Those which handle one or a small number of packages with complex build
systems (for example, <c>vim</c>, <c>toolchain</c>, <c>kernel-2</c>)
</li>
</ul>
</body>
</section>
<section>
<title>Adding and Updating Eclasses</title>
<body>
<p>
Before committing a new eclass to the tree, it should be emailed to the
gentoo-dev mailing list with a justification and a proposed implementation. Do
not skip this step <d/> sometimes a better implementation or an alternative which
does not require a new eclass will be suggested.
</p>
<p>
Before updating <c>eutils</c> or a similar widely used eclass, it is best to email
the gentoo-dev list. It may be that your proposed change is broken in a way you
had not anticipated, or that there is an existing function which performs the
same purpose, or that your function may be better off in its own eclass. If you
don't email gentoo-dev first, and end up breaking something, expect to be in a
lot of trouble.
</p>
<p>
When removing a function or changing the API of an eclass, make
sure that it doesn't break any ebuilds in the tree, and post a
notice to gentoo-dev at least 30 days in advance, preferably with
a patch included.
</p>
<p>
If there is an existing maintainer for an eclass (this is usually the case), you
<b>must</b> talk to the maintainer before committing any changes.
</p>
<p>
It is not usually necessary to email the gentoo-dev list before making changes
to a non-general eclass which you maintain. Use common sense here.
</p>
<warning>
Committing a broken eclass can kill huge numbers of packages. Since
<c>repoman</c> is not eclass-aware, be very sure you do proper testing.
</warning>
<p>
A simple way to verify syntax is <c>bash -n foo.eclass</c>.
</p>
</body>
</section>
<section>
<title>Removing Eclasses</title>
<body>
<p>No longer used eclasses may be removed from the tree, but developers must
adhere to the following process:</p>
<ol>
<li>
Make sure that no packages or other eclasses in the tree <c>inherit</c> the
eclass.
</li>
<li>
Send a lastrite message to the gentoo-dev and gentoo-dev-announce
mailing-lists, announcing that the not-used eclass will be removed in 30
days.
</li>
<li>
Add a one line comment to the eclass, saying exactly <c># @DEAD</c> so that
the eclass-manpages package will not attempt to document it.
</li>
<li>
Wait for the 30-day period to pass, then remove the eclass from the tree.
</li>
</ol>
</body>
</section>
<section>
<title>Basic Eclass Format</title>
<body>
<p>
An eclass is a <c>bash</c> script which is sourced within the ebuild environment.
Files should be a simple text file with a <c>.eclass</c> extension. Allowed
characters in the filename are lowercase letters, the digits 0-9, hyphens,
underscores and dots. Eclasses are not intrinsically versioned.
</p>
<p>
Eclasses should start with the standard ebuild header, along with comments
explaining the maintainer and purpose of the eclass, and any other relevant
documentation.
</p>
</body>
</section>
<section>
<title>Eclass Variables</title>
<body>
<p>
Top level variables may be defined as for ebuilds. If any USE flags are
used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be set in an
eclass.
</p>
</body>
</section>
<section>
<title>Eclass Functions</title>
<body>
<p>
Eclasses may define functions. These functions will be visible to anything which
inherits the eclass.
</p>
</body>
</section>
<section>
<title>Simple Common Functions Eclass Example</title>
<body>
<p>
As an example, the following eclass was written to illustrate a better way of
installing OSX application files during a discussion on this subject. It defines
a single function, <c>domacosapp</c>.
</p>
<codesample lang="ebuild">
# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$
#
# Original Author: Ciaran McCreesh <ciaranm@gentoo.org>
# Purpose: install macos .app files to the relevant location.
#
# Bugs to osx@gentoo.org
#
# domacosapp: install a macos .app file. Usage is 'domacosapp file' or
# 'domacosapp file newfile'.
domacosapp() {
[[ -z "${1}" ]] && die "usage: domacosapp <file> <new file>"
if use ppc-macos ; then
insinto /Applications
newins "$1" "${2:-${1}}" || die "Failed to install ${1}"
fi
}
</codesample>
</body>
</section>
<section>
<title>Export Functions</title>
<body>
<p>
An eclass may provide default implementations for any of the standard ebuild
functions (<c>src_unpack</c>, <c>pkg_postinst</c> etc). This can be done either as a
simple function definition (which is not multiple eclass friendly) or using
<c>EXPORT_FUNCTIONS</c>. Functions given to <c>EXPORT_FUNCTIONS</c> are implemented
as normal, but have their name prefixed with <c>${ECLASS}_</c>.
</p>
<important>
Only 'standard' functions should be specified in <c>EXPORT_FUNCTIONS</c>.
</important>
<note><c>EXPORT_FUNCTIONS</c> is a function, <e>not</e> a variable.</note>
<p>
If multiple eclasses export the same function, the latest (inherited last)
defined version wins. If an ebuild defines a function that is exported, this
gets priority over any eclass version. This can be used to override
eclass-defined defaults <d/> for example, say we had <c>fnord.eclass</c>:
</p>
<codesample lang="ebuild">
EXPORT_FUNCTIONS src_compile
fnord_src_compile() {
do_stuff || die
}
</codesample>
<p>
Then an ebuild could do this:
</p>
<codesample lang="ebuild">
inherit fnord.eclass
src_compile() {
do_pre_stuff || die
fnord_src_compile
do_post_stuff || die
}
</codesample>
</body>
</section>
<section>
<title>Simple Build System Eclass Example</title>
<body>
<p>
A simple eclass which defines a number of functions and a default
<c>src_compile</c> for the (hypothetical) <c>jmake</c> build system might look
something like the following:
</p>
<codesample lang="ebuild">
# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$
# Original Author: Ciaran McCreesh <ciaranm@gentoo.org>
# Purpose: Demonstration of EXPORT_FUNCTIONS. Defines simple wrappers for the
# (hypothetical) 'jmake' build system and a default src_compile.
EXPORT_FUNCTIONS src_compile
DEPEND=">=sys-devel/jmake-2"
jmake-configure() {
jmake configure --prefix=/usr "$@"
}
jmake-build() {
jmake dep && jmake build "$@"
}
jmake_src_compile() {
jmake-configure || die "configure failed"
jmake-build || die "build failed"
}
</codesample>
</body>
</section>
<section>
<title>Handling incorrect usage of an eclass</title>
<body>
<p>
Sometimes an eclass is used incorrectly by an ebuild and the eclass
knows it is being used incorrectly- the common example is an
eclass that only works with a specific set of EAPIs, but is being
accessed inherited by an ebuild with a different EAPI.
In those cases, used sparingly as a last resort, it is allowed
for an eclass to invoke die from the global scope. For example:
</p>
<codesample lang="ebuild">
# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$
# Purpose: Demonstration of die upon invalid EAPI usage.
case ${EAPI:-0} in
0) die "this eclass doesn't support EAPI 0" ;;
*) ;;
esac
</codesample>
</body>
</section>
</body>
</chapter>
</guide>
|
GitWeb