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
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
|
<?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>
</body>
<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>autotools</c>, <c>bash-completion-r1</c>, <c>flag-o-matic</c>,
<c>toolchain-funcs</c>)
</li>
<li>
Those which provide a basic build system for many similar packages (for
example, <c>perl-module</c>, <c>vim-plugin</c>)
</li>
<li>
Those which handle one or a small number of packages with complex build
systems (for example, <c>kernel-2</c>, <c>toolchain</c>)
</li>
</ul>
</body>
</section>
<section>
<title>Adding and Updating Eclasses</title>
<body>
<p>
Before committing a new eclass to the tree, it must 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 any eclass, email patches to 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>
The exceptions to this rule are updates to per-package eclasses. For example,
the <c>apache-2</c> eclass is only used by the <c>www-servers/apache</c>
package, and thus does not typically require changes to be emailed for review.
</p>
<p>
When removing a function or changing the API of an eclass, make sure that
it doesn't break any ebuilds in the Gentoo repository. Optionally, you may wish
to do a survey of some (official) overlays like <c>::guru</c>, <c>::musl</c>, or
<c>::science</c> in order to better understand how it is currently used and
<d/> where possible <d/> avoid breakage by pinging the maintainers directly.
</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>
<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>
<note>
Given that updating an eclass will invalidate the cache of all consumer ebuilds,
it is good etiquette to ping other developers in e.g. <c>#gentoo-dev</c>
on IRC or informally determine if there are other similar changes (mainly
documentation) which should be pushed at the same time in order to avoid
unnecessary cache regeneration within a few hours or days of each other.
The same applies to your own work <d/> please prepare all of your commits and
batch push them at once where possible.
</note>
</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>Documenting Eclasses</title>
<body>
<p>
Eclasses are documented with comment blocks that follow a special
markup syntax. The comment blocks are separated by blank lines and
each block documents an individual element of an eclass.
</p>
<p>
Documentation tags for various eclass elements are explained in their
respective sections below. Common to all the tags that accept
multiline freetext, the <c>@CODE</c> tag should be used when necessary
to create unformatted code chunks (such as example code) by placing
the tag at the beginning and the end.
</p>
<p>
Note that <c>pkgcheck</c> can check for issues in eclass documentation.
You could run e.g. <c>pkgcheck scan -s eclass</c> to check for issues
in the tree or <c>pkgcheck scan --commits</c> to check for issues
in your staged git commits.
</p>
</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. Eclass documentation block should be the
first documentation block to appear in the eclass. The following table
summarizes the available documentation tags:
</p>
<table>
<tr>
<th>tag</th>
<th>optional?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti>
<c>@ECLASS:</c>
</ti>
<ti>
NO
</ti>
<ti>
Name of the eclass being documented.
</ti>
<ti>
Documents various information about the eclass. Must appear as the
first tag in the comment block.
</ti>
</tr>
<tr>
<ti>
<c>@MAINTAINER:</c>
</ti>
<ti>
NO
</ti>
<ti>
One or more name and email pairs.
</ti>
<ti>
List of maintainers for the eclass to be contacted. One line per
maintainer. Must start on a newline after the tag.
</ti>
</tr>
<tr>
<ti>
<c>@AUTHOR:</c>
</ti>
<ti>
YES
</ti>
<ti>
One or more name and email pairs.
</ti>
<ti>
List of authors for the eclass. One line per author. Must start on
a newline after the tag.
</ti>
</tr>
<tr>
<ti>
<c>@BUGREPORTS:</c>
</ti>
<ti>
YES
</ti>
<ti>
Multiline freetext.
</ti>
<ti>
Describes how bugs related to this eclass should be reported.
</ti>
</tr>
<tr>
<ti>
<c>@VCSURL:</c>
</ti>
<ti>
YES
</ti>
<ti>
A URI string.
</ti>
<ti>
Points to the URL of the VCS that contains the eclass source.
</ti>
</tr>
<tr>
<ti>
<c>@BLURB:</c>
</ti>
<ti>
NO
</ti>
<ti>
Single line freetext.
</ti>
<ti>
Contains a short description for the eclass. Must be on the same
line with the tag.
</ti>
</tr>
<tr>
<ti>
<c>@DESCRIPTION:</c>
</ti>
<ti>
YES
</ti>
<ti>
Multiline freetext.
</ti>
<ti>
Long description for the eclass.
</ti>
</tr>
<tr>
<ti>
<c>@EXAMPLE:</c>
</ti>
<ti>
YES
</ti>
<ti>
Multiline freetext.
</ti>
<ti>
Examples that illustrate various uses of this eclass.
</ti>
</tr>
</table>
</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>
<p>
You should document the meaning, usage, and default value of every
variable in your eclass. The tags available for documenting eclass
variables are as follows:
</p>
<table>
<tr>
<th>tag</th>
<th>optional?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti nowrap="nowrap">
<c>@ECLASS-VARIABLE:</c>
</ti>
<ti>
NO
</ti>
<ti>
Name of the eclass variable to which the documentation applies.
</ti>
<ti>
This tag applies to eclass specific variables that affect the
default behavior of the eclass. Read-only variables, which are
exported by the eclass for developer use, are also documented with
this tag. Must appear as the first tag in the comment block.
</ti>
</tr>
<tr>
<ti><c>@PRE_INHERIT</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
This tag describes whether the variable must be defined before
the eclass is inherited. This is important if any e.g. dependencies
are modified in global scope at the point of sourcing.
</ti>
</tr>
<tr>
<ti><c>@USER_VARIABLE</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
This tag describes whether the variable is unsuitable for use in ebuilds,
i.e. if it is solely for user consumption via e.g. make.conf or a similar
mechanism.
</ti>
</tr>
<tr>
<ti><c>@OUTPUT_VARIABLE</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
This tag indicates that the variable's value (which will be set by the
eclass) should be read within an ebuild.
</ti>
</tr>
<tr>
<ti><c>@DEFAULT_UNSET</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
Indicates that this variable is unset by default if not set by the
developer.
</ti>
</tr>
<tr>
<ti><c>@INCLUDES_EPREFIX</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
Indicates that the variable is a path which has ${EPREFIX} prepended to it.
</ti>
</tr>
<tr>
<ti><c>@INTERNAL</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>Indicates that the variable is internal to the eclass.</ti>
</tr>
<tr>
<ti><c>@REQUIRED</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>Indicates that this variable must be set by the developer.</ti>
</tr>
<tr>
<ti><c>@DEPRECATED</c></ti>
<ti>YES</ti>
<ti>Optionally, the name of any replacement variable.</ti>
<ti>Declares that this variable should no longer be used in ebuilds.</ti>
</tr>
<tr>
<ti><c>@DESCRIPTION:</c></ti>
<ti>NO</ti>
<ti>Multiline freetext.</ti>
<ti>Long description for the eclass variable.</ti>
</tr>
</table>
</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>
<p>
You should document the purpose, arguments, usage, and return value of
every function in your eclass. The standard tags available for
documentation are:
</p>
<table>
<tr>
<th>tag</th>
<th>optional?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti>
<c>@FUNCTION:</c>
</ti>
<ti>
NO
</ti>
<ti>
Name of the function to which the documentation block applies.
</ti>
<ti>
Documents information about an eclass function such as its calling
convention etc. Must appear as the first tag in the comment block.
</ti>
</tr>
<tr>
<ti>
<c>@USAGE:</c>
</ti>
<ti>
NO
</ti>
<ti>
List of required and optional arguments to the function.
</ti>
<ti>
List of arguments that the eclass function accepts, specified in
the following syntax: <c><</c>Required arguments<c>></c>
<c>[</c>Optional arguments<c>]</c>
</ti>
</tr>
<tr>
<ti>
<c>@RETURN:</c>
</ti>
<ti>
<b>*</b>
</ti>
<ti>
Return value of the function.
</ti>
<ti>
<p>Description for the value returned by the function.</p>
<p><b>*</b>: Not optional for functions that return a value.</p>
</ti>
</tr>
<tr>
<ti>
<c>@MAINTAINER:</c>
</ti>
<ti>
YES
</ti>
<ti>
Multiline freetext.
</ti>
<ti>
List of contacts for the eclass function. One line per
maintainer. Must start on a newline after the tag.
</ti>
</tr>
<tr>
<ti><c>@INCLUDES_EPREFIX</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
Indicates whether the function returns a path with ${EPREFIX} prepended
to it.
</ti>
</tr>
<tr>
<ti><c>@INTERNAL</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
Indicates that the function is internal to the eclass and should
not be called from outside.
</ti>
</tr>
<tr>
<ti><c>@DEPRECATED</c></ti>
<ti>YES</ti>
<ti>Optionally, the name of a replacement function.</ti>
<ti>Declares that this function should no longer be used in ebuilds.</ti>
</tr>
<tr>
<ti>
<c>@DESCRIPTION:</c>
</ti>
<ti>
<b>*</b>
</ti>
<ti>
Multiline freetext.
</ti>
<ti>
<p>Long description for the eclass function.</p>
<p><b>*:</b> Not optional if <c>RETURN:</c> is absent.</p>
</ti>
</tr>
</table>
</body>
</section>
<section>
<title>Eclass Function Variables</title>
<body>
<p>
Eclass functions may make use of variables just like any other bash
function. Special function-specific variables should be documented
using the following tags:
</p>
<table>
<tr>
<th>tag</th>
<th>optional?</th>
<th>arguments</th>
<th>description</th>
</tr>
<tr>
<ti><c>@VARIABLE:</c></ti>
<ti>NO</ti>
<ti>
Name of the function-specific variable to which the documentation applies.
</ti>
<ti>
This tag applies to variables consumed by specific functions of
the eclass. They are in effect only when the specific function is
called.
</ti>
</tr>
<tr>
<ti><c>@USER_VARIABLE</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
This tag describes whether the variable is unsuitable for use in ebuilds,
i.e. if it is solely for user consumption via e.g. make.conf or a similar
mechanism.
</ti>
</tr>
<tr>
<ti><c>@DEFAULT_UNSET</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>
Indicates that this variable is unset by default if not set by the
developer.
</ti>
</tr>
<tr>
<ti><c>@INCLUDES_EPREFIX</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>Indicates that the variable is a path which has ${EPREFIX} prepended.</ti>
</tr>
<tr>
<ti><c>@INTERNAL</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>Indicates that the variable is internal to the eclass function.</ti>
</tr>
<tr>
<ti><c>@REQUIRED</c></ti>
<ti>YES</ti>
<ti><d/></ti>
<ti>Indicates that this variable must be set by the developer.</ti>
</tr>
<tr>
<ti><c>@DEPRECATED</c></ti>
<ti>YES</ti>
<ti>Optionally, the name of any replacement variable.</ti>
<ti>Declares that this variable should no longer be used in ebuilds.</ti>
</tr>
<tr>
<ti><c>@DESCRIPTION:</c></ti>
<ti>NO</ti>
<ti>Multiline freetext.</ti>
<ti>Long description for the function variable.</ti>
</tr>
</table>
</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-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# @ECLASS: macosapp.eclass
# @MAINTAINER:
# Ciaran McCreesh <ciaranm@gentoo.org>
# @BLURB: install macos .app files to the relevant location.
# @FUNCTION: domacosapp
# @USAGE: <app-file> [new-file]
# @DESCRIPTION:
# Install the given .app file into the appropriate location. If
# [new-file] is given, it will be used as the new (installed) name of
# the file. Otherwise <app-file> is installed as-is.
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 ebuild phase
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 ("namespaced") with <c>${ECLASS}_</c>.
</p>
<important>
Only the ebuild phase functions may 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
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-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# @ECLASS: jmake.eclass
# @MAINTAINER:
# Gentoo Devmanual Project <devmanual@gentoo.org>
# @AUTHOR:
# Ciaran McCreesh <ciaranm@gentoo.org>
# @BLURB: Demonstrate a simple build system eclass.
# @DESCRIPTION:
# Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the
# (hypothetical) jmake build system and a default src_compile.
EXPORT_FUNCTIONS src_compile
DEPEND=">=sys-devel/jmake-2"
# @FUNCTION: jmake-configure
# @USAGE: [additional-args]
# @DESCRIPTION:
# Passes all arguments through to the appropriate "jmake configure"
# command.
jmake-configure() {
jmake configure --prefix=/usr "$@"
}
# @FUNCTION: jmake-build
# @USAGE: [additional-args]
# @DESCRIPTION:
# First builds all dependencies, and then passes through its arguments
# to the appropriate "jmake build" command.
jmake-build() {
jmake dep && jmake build "$@"
}
# @FUNCTION: jmake-src_compile
# @DESCRIPTION:
# Calls jmake-configure() and jmake-build() to compile a jmake project.
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-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
# @ECLASS: eapi-die.eclass
# @MAINTAINER:
# Gentoo Devmanual Project <devmanual@gentoo.org>
# @BLURB: Calls die when used with an invalid EAPI.
case ${EAPI:-0} in
0) die "this eclass doesn't support EAPI 0" ;;
*) ;;
esac
</codesample>
</body>
</section>
</chapter>
</guide>
|
GitWeb