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
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
|
<?xml version="1.0" encoding="UTF-8"?>
<guide self="quickstart/">
<chapter>
<title>Quickstart ebuild guide</title>
<body>
<p>
This page provides a <e>very</e> brief introduction to ebuild
writing. It does not attempt to cover many of the details or problems
that will be encountered by developers <d/> rather, it gives some
trivial examples which may be of use when trying to grasp the basic
idea of how ebuilds work.
</p>
<p>
For proper coverage of all the ins and outs,
see <uri link="::ebuild-writing/"/>.
The <uri link="::general-concepts/"/> chapter will also be of use.
</p>
<p>
Note that the examples used here, whilst based upon real tree ebuilds,
have had several parts chopped out, changed and simplified.
</p>
</body>
<section>
<title>First ebuild</title>
<body>
<p>
We'll start with an ebuild for the <e>Exuberant Ctags</e> utility, a source code
indexing tool. Here's a simplified <c>dev-util/ctags/ctags-5.5.4.ebuild</c> (you
can see real ebuilds in the main tree).
</p>
<codesample lang="ebuild">
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="https://ctags.io/ https://github.com/universal-ctags/ctags"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"
LICENSE="GPL-2+"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
src_configure() {
econf --with-posix-regex
}
src_install() {
emake DESTDIR="${D}" install
dodoc FAQ NEWS README
}
</codesample>
</body>
<subsection>
<title>Basic format</title>
<body>
<p>
As you can see, ebuilds are just <c>bash</c> scripts that are executed within a
special environment.
</p>
<p>
At the top of the ebuild is a header block. This is present in all ebuilds.
</p>
<p>
Ebuilds are indented using tabs, with each tab representing four spaces.
See <uri link="::ebuild-writing/file-format/"/>.
</p>
</body>
</subsection>
<subsection>
<title>Information variables</title>
<body>
<p>
Next, there are a series of variables. These tell Portage various things about
the ebuild and package in question.
</p>
<p>
The <c>EAPI</c> of the ebuild, see <uri link="::ebuild-writing/eapi/"/>.
</p>
<p>
The <c>DESCRIPTION</c> variable is set to a <e>short</e> description
of the package and its purpose.
</p>
<p>
The <c>HOMEPAGE</c> is a link to the package's homepage (remember to
include the URI scheme, for example <c>https://</c>).
</p>
<p>
The <c>SRC_URI</c> tells Portage the address to use for downloading
the source tarball. Here, <c>mirror://sourceforge/</c> is a special
notation meaning "any of the Sourceforge mirrors".
<c>${P}</c> is a read-only variable set by Portage which is the package's
name and version <d/> in this case, it would be <c>ctags-5.5.4</c>.
</p>
<p>
The <c>LICENSE</c> is <c>GPL-2+</c> (the GNU General Public License version 2
or (at your option) any later version).
</p>
<p>
The <c>SLOT</c> variable tells Portage which slot this package installs to.
If you've not seen slots before, either just use <c>"0"</c> or read
<uri link="::general-concepts/slotting/"/>.
</p>
<p>
The <c>KEYWORDS</c> variable is set to archs upon which this ebuild has been
tested. We use <c>~</c> keywords for newly written ebuilds <d/> packages are not
committed straight to stable, even if they seem to work.
See <uri link="::keywording/"/> for details.
</p>
</body>
</subsection>
<subsection>
<title>Build functions</title>
<body>
<p>
Next, a function named <c>src_configure</c>. Portage will call this
function when it wants to <e>configure</e> the package. The <c>econf</c>
function is a wrapper for calling <c>./configure</c>. If for some reason
an error occurs in <c>econf</c>, Portage will stop rather than trying to
continue with the install.
</p>
<p>
The <c>src_install</c> function is called by Portage when it wants
to <e>install</e> the package. A slight subtlety here <d/> rather than
installing straight to the live filesystem, we must install to a
special location which is given by the <c>${D}</c> variable (Portage sets
this <d/> see <uri link="::general-concepts/install-destinations/"/> and
<uri link="::general-concepts/sandbox/"/>).
</p>
<note>
The canonical install method is <c>emake DESTDIR="${D}" install</c>. This will
work with any properly written standard <c>Makefile</c>. If this gives sandbox
errors, see <uri link="::ebuild-writing/functions/src_install/"/> for how to do
manual installs.
</note>
<p>
The <c>dodoc</c> is a helper function for installing
files into the relevant part of <c>/usr/share/doc</c>.
</p>
<p>
Ebuilds can define other functions
(see <uri link="::ebuild-writing/functions/"/>).
In all cases, Portage provides a reasonable default implementation which
quite often does the 'right thing'. There was no need to define
<c>src_unpack</c> and <c>src_compile</c> functions here, for example
<d/> the <c>src_unpack</c> function is used to do any unpacking of
tarballs or patching of source files, but the default implementation
does everything we need in this case.
Similarly, the default <c>src_compile</c> function will call
<c>emake</c> which is a wrapper for <c>make</c>.
</p>
<note>
Formerly, the <c>|| die</c> construct had to be used after every command
to check for errors. This is no longer necessary in EAPI 4 <d/>
functions provided by Portage will die by themselves if something
failed.
</note>
</body>
</subsection>
</section>
<section>
<title>Ebuild with dependencies</title>
<body>
<p>
In the ctags example, we didn't tell Portage about any dependencies. As it
happens, that's ok, because ctags only needs a basic toolchain to compile and
run (see <uri link="::general-concepts/dependencies/#Implicit system dependency"/>
for why we don't need to depend upon those explicitly). However, life is rarely
that simple.
</p>
<p>
Here's <c>app-misc/detox/detox-1.1.1.ebuild</c>:
</p>
<codesample lang="ebuild">
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
DESCRIPTION="detox safely removes spaces and strange characters from filenames"
HOMEPAGE="http://detox.sourceforge.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
LICENSE="BSD"
SLOT="0"
KEYWORDS="~hppa ~mips sparc x86"
RDEPEND="dev-libs/popt"
DEPEND="${RDEPEND}
sys-devel/flex"
BDEPEND="sys-devel/bison"
src_configure() {
econf --with-popt
}
</codesample>
<p>
Again, you can see the ebuild header and the various informational variables. In
<c>SRC_URI</c>, <c>${PN}</c> is used to get the package's
name <e>without</e> the version suffix (there are more of these
variables <d/> see
<uri link="::ebuild-writing/variables/#Predefined read-only variables"/>).
</p>
<p>
We define <c>src_configure</c> only. <c>src_install</c> does not need to
be defined since the default implementation calling <c>emake install</c>
and installing common documentation files works correctly for the package.
</p>
<p>
The <c>BDEPEND</c>, <c>DEPEND</c>, and <c>RDEPEND</c> variables are how Portage
determines which packages are needed to build and run the package. The
<c>BDEPEND</c> variable lists build-time (executable) dependencies,
<c>DEPEND</c> variable lists compile-time dependencies, and the <c>RDEPEND</c>
lists runtime dependencies. See <uri link="::general-concepts/dependencies/"/>
for some more complex examples.
</p>
</body>
</section>
<section>
<title>Ebuild with patches</title>
<body>
<p>
Often we need to apply patches. This is done either by defining the
<c>PATCHES</c> array in global scope or in the <c>src_prepare</c> function
using the <c>eapply</c> helper function. To use <c>eapply</c>,
one must use EAPI 7. Here's <c>app-misc/detox/detox-1.1.0.ebuild</c>:
</p>
<codesample lang="ebuild">
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
DESCRIPTION="detox safely removes spaces and strange characters from filenames"
HOMEPAGE="http://detox.sourceforge.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
LICENSE="BSD"
SLOT="0"
KEYWORDS="~hppa ~mips ~sparc ~x86"
RDEPEND="dev-libs/popt"
DEPEND="${RDEPEND}
sys-devel/flex"
BDEPEND="sys-devel/bison"
src_prepare() {
eapply "${FILESDIR}"/${P}-destdir.patch \
"${FILESDIR}"/${P}-parallel_build.patch
eapply_user
}
src_configure() {
econf --with-popt
}
</codesample>
<p>
Note the <c>${FILESDIR}/${P}-destdir.patch</c> <d/> this refers to
<c>detox-1.1.0-destdir.patch</c>, which lives in the <c>files/</c>
subdirectory in the Gentoo repository. Larger patch files must go on your
developer's space at <c>dev.gentoo.org</c> rather than in <c>files/</c> or
mirrors <d/>
see <uri link="::general-concepts/mirrors/#Suitable download hosts"/> and
<uri link="::ebuild-writing/functions/src_prepare/eapply/"/>.
</p>
<p>
When the <c>src_prepare</c> phase is overridden, it must be ensured
that <c>eapply_user</c> is called.
</p>
</body>
</section>
<section>
<title>Ebuild with USE flags</title>
<body>
<p>
Now for some <c>USE</c> flags. Here's <c>dev-libs/libiconv/libiconv-1.9.2.ebuild</c>, a
replacement iconv for <c>libc</c> implementations which don't have their own.
</p>
<codesample lang="ebuild">
# Copyright 1999-2022 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
DESCRIPTION="GNU charset conversion library for libc which doesn't implement it"
HOMEPAGE="https://www.gnu.org/software/libiconv/"
SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz"
LICENSE="LGPL-2+ GPL-3+"
SLOT="0"
KEYWORDS="~amd64 ~ppc ~sparc ~x86"
IUSE="nls"
RDEPEND="!sys-libs/glibc"
DEPEND="${RDEPEND}"
src_configure() {
econf $(use_enable nls)
}
</codesample>
<p>
Note the <c>IUSE</c> variable. This lists all (non-special) use flags that are used
by the ebuild. This is used for the <c>emerge -pv</c> output, amongst other things.
</p>
<p>
The package's <c>./configure</c> script takes the usual <c>--enable-nls</c> or
<c>--disable-nls</c> argument. We use the <c>use_enable</c> utility function to
generate this automatically, depending on the user's <c>USE</c> flags (see
<uri link="::function-reference/query-functions/"/>).
</p>
<p>
Another more complicated example, this time based upon
<c>mail-client/sylpheed/sylpheed-1.0.4.ebuild</c>:
</p>
<codesample lang="ebuild">
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
inherit desktop
DESCRIPTION="A lightweight email client and newsreader"
HOMEPAGE="https://sylpheed.good-day.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
LICENSE="GPL-2+ LGPL-2.1+"
SLOT="0"
KEYWORDS="~alpha amd64 hppa ~ia64 ppc ppc64 sparc x86"
IUSE="crypt imlib ipv6 ldap nls pda ssl xface"
RDEPEND="=x11-libs/gtk+-2*
crypt? ( >=app-crypt/gpgme-0.4.5 )
imlib? ( media-libs/imlib2 )
ldap? ( >=net-nds/openldap-2.0.11 )
pda? ( app-pda/jpilot )
ssl? ( dev-libs/openssl )
xface? ( >=media-libs/compface-1.4 )
app-misc/mime-types
x11-misc/shared-mime-info"
DEPEND="${RDEPEND}"
BDEPEND="dev-util/pkgconfig
nls? ( >=sys-devel/gettext-0.12.1 )"
PATCHES=(
"${FILESDIR}"/${PN}-namespace.patch
"${FILESDIR}"/${PN}-procmime.patch
)
src_configure() {
econf \
$(use_enable nls) \
$(use_enable ssl) \
$(use_enable crypt gpgme) \
$(use_enable pda jpilot) \
$(use_enable ldap) \
$(use_enable ipv6) \
$(use_enable imlib) \
$(use_enable xface compface)
}
src_install() {
emake DESTDIR="${D}" install
doicon sylpheed.png
domenu sylpheed.desktop
dodoc [A-Z][A-Z]* ChangeLog*
}
</codesample>
<p>
Note the optional dependencies. Some of the <c>use_enable</c> lines use the
two-argument version <d/> this is helpful when the USE flag name does not exactly
match the <c>./configure</c> argument.
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb