/[gentoo-x86]/eclass/eclass-howto.lyx
Gentoo

Contents of /eclass/eclass-howto.lyx

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.2 - (show annotations) (download)
Mon Oct 1 11:04:22 2001 UTC (13 years, 7 months ago) by danarmak
Branch: MAIN
CVS Tags: HEAD
Changes since 1.1: +0 -0 lines
FILE REMOVED
eclasses v3. read the gentoo-dev announcement, and news.txt and howto.*
in doc/.

1 #LyX 1.1 created this file. For more info see http://www.lyx.org/
2 \lyxformat 218
3 \textclass docbook-chapter
4 \language english
5 \inputencoding auto
6 \fontscheme default
7 \graphics default
8 \paperfontsize default
9 \spacing single
10 \papersize Default
11 \paperpackage a4
12 \use_geometry 0
13 \use_amsmath 0
14 \paperorientation portrait
15 \secnumdepth 3
16 \tocdepth 3
17 \paragraph_separation indent
18 \defskip medskip
19 \quotes_language english
20 \quotes_times 2
21 \papercolumns 1
22 \papersides 1
23 \paperpagestyle default
24
25 \layout Title
26
27 eclass howto
28 \layout Author
29
30 Dan Armak
31 \layout Date
32
33 30/9/01
34 \layout Section
35
36 Introduction
37 \layout Standard
38
39 eclasses are parts of ebuilds; that is, they have the same syntax ebuilds
40 do, but do not define all the required variables and functions.
41 ebuilds can inherit from eclasses, and eclasses can inherit from other
42 eclasses.
43 As in OOP, this is used to ensure maximum code reuse among similar ebuilds.
44 \layout Standard
45
46 The most similar group of ebuilds is the kde apps.
47 These have been selected to be the test case for this first incarnation
48 of eclasses.
49 Currently test ebuilds are available for all of kde-2.2.1 (as kde*-2.2.1-r1),
50 kdevelop-2.0.1 and koffice-1.1.
51 Many others will follow.
52 \layout Standard
53
54 Section two explains how eclasses work.Section three shows a sample inheriting
55 ebuild.
56 \layout Subsection
57
58 Notes on this document
59 \layout Itemize
60
61
62 \emph on
63 ebuild variables/functions
64 \emph default
65 refers to those used in std.
66 ebuilds e.g.
67 $S, $P, src_unpack()...
68 \layout Section
69
70 The eclasses
71 \layout Standard
72
73 The best way of becoming familiar with the current eclass structure is an
74 explanation of what each eclass does.
75 \layout Subsection
76
77 inherit.eclass
78 \layout Standard
79
80 Defines inherit() function which handles sourcing of eclasses.
81 \layout Standard
82
83 Syntax of inheriting: we define a simple function inherit():
84 \layout Code
85
86 ECLASSDIR=/usr/portage/eclass
87 \layout Code
88
89 inherit() {
90 \layout Code
91
92 while [ "$1" ]; do
93 \layout Code
94
95 source ${ECLASSDIR}/${1}.eclass
96 \layout Code
97
98 shift
99 \layout Code
100
101 done
102 \layout Code
103
104 }
105 \layout Standard
106
107 This function simply sources files from a hard-coded location.
108 If, in the future, we will decide to move eclasses to a different location
109 or to introduce more
110 \begin_inset Quotes eld
111 \end_inset
112
113 formats
114 \begin_inset Quotes erd
115 \end_inset
116
117 (like drobbins' projected
118 \emph on
119 xbuilds
120 \emph default
121 ), any name-to-file resolution code will go in here.
122 \layout Standard
123
124 This function is the entire contents of inherit.eclass.
125 In the future, once eclasses are considered to be stable, this function
126 will live in ebuild.sh, and every ebuild will be able to use it.
127 For now, we don't want to make a new version of portage just for this,
128 so we put this function in a separate eclass.
129 Every inheriting ebuild begins with these two lines:
130 \layout Standard
131
132 .
133 /usr/portage/eclass/inherit.eclass || die
134 \layout Standard
135
136 inherit kde-base || die
137 \layout Standard
138
139 Once the inherit() function goes into ebuild.sh, we can drop the first line;
140 there will be no further change necessary.
141 \layout Standard
142
143 Eclasses do not need this first line, since they are always sourced from
144 an ebuild which has it.
145 \layout Subsection
146
147 virtual.eclass
148 \layout Standard
149
150 Defines empty variables and functions; defines EXPORT_FUNCTIONS().
151 \layout Standard
152
153 This eclass is inherited by most other eclasses e.g.
154 base, kde*.
155 As a rule, any eclass that defines some of the base functions needs it.
156 Therefore the only ebuilds which don't get it are the ones that only inherit
157 one of the smaller eclasses e.g.
158 c, autoconf.
159 \layout Standard
160
161 It defines all ebuild vars and funcs to be empty.
162 \layout Standard
163
164 It also defines the EXPORT_FUNCTIONS() function which looks like this:
165 \layout Code
166
167 EXPORT_FUNCTIONS() {
168 \layout Code
169
170 while [ "$1" ]; do
171 \layout Code
172
173 eval "$1() { ${ECLASS}_$1 ; }" > /dev/null
174 \layout Code
175
176 shift
177 \layout Code
178
179 done
180 \layout Code
181
182 }
183 \layout Standard
184
185 This means that after foo.eclass has defined e.g.
186 src_unpack() and src_install(), it says:
187 \layout Standard
188
189 ECLASS=foo
190 \layout Standard
191
192 EXPORT_FUNCTIONS src_unpack src_install
193 \layout Standard
194
195 Actually, the ECLASS setting is put at the beginning of the eclass, directly
196 after the inherit statements.
197 It will in the future be used by other functions as well.
198 Someday we will (I hope) adapt the portage ebuild filename->name algorithm
199 and get the ECLASS setting the same way we do $P and $PN.
200 \layout Standard
201
202 EXPORT_FUNCTIONS() creates stub functions called ${ECLASS}_blah for every
203 parameter blah passed to it.
204 The stub function does nothing but call blah.
205 \layout Standard
206
207 When you inherit more than one eclass (almost always), your ebuild functions
208 are those defined by the 1st eclass inherited.
209 Since eclasses usually inherit other eclasses, you do not want to keep
210 track of that.
211 Instead, you prefix all your functions from foo.eclass with foo_, or ${ECLASS}_.
212 This way, people can call a specific function from a specific eclass and
213 know what they are going to get.
214 \layout Standard
215
216 Because you still want default functions to be defined with the original
217 ebuild names, you call EXPORT_FUNCTIONS() at the end of every eclass.
218 This makes sure that the default functions you passed as parameters are
219 stubs calling the ones you just defined.
220 \layout Standard
221
222 I looked at adding ${EBUILD}_ instead of literal strings to the actual function
223 definitions, but the bash syntax for that is too ugly.
224 \layout Subsubsection
225
226 ebuild function sections
227 \layout Standard
228
229 Although this is not an integral part of eclasses, this is a good place
230 to introduce function sections.
231
232 \layout Standard
233
234 One rarely uses predefined functions as-is; you usually want to extend them.
235 Once they have unique names (foo_src_unpack) it's easy to add code that
236 executes before or after them.
237 Function sections break them down and allow code to execute between any
238 two sections.
239 \layout Standard
240
241 The implementation is simple.
242 Let's take as an example the src_compile() function from base.eclass.
243 It looks like this:
244 \layout Code
245
246 base_src_compile() {
247 \layout Code
248
249 ./configure || die
250 \layout Code
251
252 make || die
253 \layout Code
254
255 }
256 \layout Standard
257
258 Here is the same function, divided into sections:
259 \layout Code
260
261 base_src_compile() {
262 \layout Code
263
264 \SpecialChar ~
265
266 \layout Code
267
268 \SpecialChar ~
269 \SpecialChar ~
270 \SpecialChar ~
271 [ -z "$1" ] && base_src_compile all
272 \layout Code
273
274 \SpecialChar ~
275
276 \layout Code
277
278 \SpecialChar ~
279 \SpecialChar ~
280 \SpecialChar ~
281 while [ "$1" ]; do
282 \layout Code
283
284 \layout Code
285
286 \SpecialChar ~
287 \SpecialChar ~
288 \SpecialChar ~
289 \SpecialChar ~
290 \SpecialChar ~
291 \SpecialChar ~
292 \SpecialChar ~
293 \SpecialChar ~
294 case $1 in
295 \layout Code
296
297 \SpecialChar ~
298 \SpecialChar ~
299 \SpecialChar ~
300 \SpecialChar ~
301 \SpecialChar ~
302 \SpecialChar ~
303 \SpecialChar ~
304 \SpecialChar ~
305 \SpecialChar ~
306 \SpecialChar ~
307 \SpecialChar ~
308 configure)
309 \layout Code
310
311 \SpecialChar ~
312 \SpecialChar ~
313 \SpecialChar ~
314 \SpecialChar ~
315 \SpecialChar ~
316 \SpecialChar ~
317 \SpecialChar ~
318 \SpecialChar ~
319 \SpecialChar ~
320 \SpecialChar ~
321 \SpecialChar ~
322 \SpecialChar ~
323 \SpecialChar ~
324 \SpecialChar ~
325 \SpecialChar ~
326 \SpecialChar ~
327 ./configure || die;;
328 \layout Code
329
330 \SpecialChar ~
331 \SpecialChar ~
332 \SpecialChar ~
333 \SpecialChar ~
334 \SpecialChar ~
335 \SpecialChar ~
336 \SpecialChar ~
337 \SpecialChar ~
338 \SpecialChar ~
339 \SpecialChar ~
340 \SpecialChar ~
341 make)
342 \layout Code
343
344 \SpecialChar ~
345 \SpecialChar ~
346 \SpecialChar ~
347 \SpecialChar ~
348 \SpecialChar ~
349 \SpecialChar ~
350 \SpecialChar ~
351 \SpecialChar ~
352 \SpecialChar ~
353 \SpecialChar ~
354 \SpecialChar ~
355 \SpecialChar ~
356 \SpecialChar ~
357 \SpecialChar ~
358 \SpecialChar ~
359 \SpecialChar ~
360 make || die;;
361 \layout Code
362
363 \SpecialChar ~
364 \SpecialChar ~
365 \SpecialChar ~
366 \SpecialChar ~
367 \SpecialChar ~
368 \SpecialChar ~
369 \SpecialChar ~
370 \SpecialChar ~
371 \SpecialChar ~
372 \SpecialChar ~
373 \SpecialChar ~
374 all)
375 \layout Code
376
377 \SpecialChar ~
378 \SpecialChar ~
379 \SpecialChar ~
380 \SpecialChar ~
381 \SpecialChar ~
382 \SpecialChar ~
383 \SpecialChar ~
384 \SpecialChar ~
385 \SpecialChar ~
386 \SpecialChar ~
387 \SpecialChar ~
388 \SpecialChar ~
389 \SpecialChar ~
390 \SpecialChar ~
391 \SpecialChar ~
392 \SpecialChar ~
393 base_src_compile configure make;;
394 \layout Code
395
396 \SpecialChar ~
397 \SpecialChar ~
398 \SpecialChar ~
399 \SpecialChar ~
400 \SpecialChar ~
401 \SpecialChar ~
402 \SpecialChar ~
403 \SpecialChar ~
404 esac
405 \layout Code
406
407 \layout Code
408
409 \SpecialChar ~
410 \SpecialChar ~
411 \SpecialChar ~
412 shift
413 \layout Code
414
415 \SpecialChar ~
416 \SpecialChar ~
417 \SpecialChar ~
418 done
419 \layout Code
420
421 \SpecialChar ~
422
423 \layout Code
424
425 }
426 \layout Standard
427
428 The code has been divided into two
429 \begin_inset Quotes eld
430 \end_inset
431
432 sections
433 \begin_inset Quotes erd
434 \end_inset
435
436 :
437 \emph on
438 configure
439 \emph default
440 and
441 \emph on
442 make
443 \emph default
444 .
445 In our simple example, they correspond to the two commands in the original
446 function.
447 \layout Standard
448
449 In the center of the new function is a while;case...esac;shift;done block.
450 This block matches the parameters to the functions with the defined section
451 names and executes the corresponding lines of code.
452 \layout Standard
453
454 The special case
455 \emph on
456 all
457 \emph default
458 calls the same function recursively with a list of sections in order.
459 It's up to the eclass's author to maintain this list, which is very important.
460 \layout Standard
461
462 The line before the block says that a call without parameters should be
463 treated the same as a call with the single parameter
464 \emph on
465 all.
466
467 \emph default
468 As you see, this function recurses a lot.
469 Note, however, that the call
470 \emph on
471 base_src_compile configure all make
472 \emph default
473 is also legal; it will execute
474 \emph on
475 base_src_compile configure configure make make
476 \emph default
477 .
478 \layout Standard
479
480 Now, in your ebuild (or eclass) that inherits from base.eclass, you get the
481 stub function src_compile which calls base_src_compile without parameters.
482 This makes base_src_compile execute
483 \emph on
484 all
485 \emph default
486 , that is, all its sections.
487 You can leave it as-is.
488 If you wish to extend it, you define a new src_compile and call base_src_compil
489 e a section at a time:
490 \layout Code
491
492 src_compile() {
493 \layout Code
494
495 myfunc1
496 \layout Code
497
498 base_src_compile configure
499 \layout Code
500
501 myfunc2
502 \layout Code
503
504 base_src_compile make
505 \layout Code
506
507 }
508 \layout Standard
509
510 The only way to know what functions contain what sections is to read the
511 eclasses.
512 \layout Subsection
513
514 base.eclass
515 \layout Standard
516
517 This eclass defines some default variables and functions, similar to those
518 you'd get by default in a non-inheriting ebuild.
519 For example, it defines:
520 \layout Code
521
522 base_src_unpack() { unpack ${A}; }
523 \layout Standard
524
525 Only with sections, of course.
526 \layout Standard
527
528 It is inherited by higher-level eclasses like the kde ones.
529 \layout Subsection
530
531 kde.eclass
532 \layout Standard
533
534 Used by all kde apps, whether directly or indirectly.
535 This is a higher-level eclass, which is intended to provide not only sensible
536 defaults but functions which can be used as-is more often then not.
537
538 \layout Standard
539
540 It inherits c, autoconf and base.
541 \layout Standard
542
543 Read it to find out what it defines.
544 It is quite self-explanatory.
545 \layout Standard
546
547 Briefly, it handles all standard kde-2.1* and 2.2* apps that need configure/make/m
548 ake install cycles.
549 It handles all the std.
550 configure options e.g.
551 objprelink.
552 It also adds kdelibs and qt to DEPEND.
553 \layout Subsection
554
555 kde-base.eclass
556 \layout Standard
557
558 Meant for kde apps part of the core kde distribution.
559 \layout Standard
560
561 Differences from kde.eclass:
562 \layout Itemize
563
564 Sets appropriate DESCRIPTION and HOMEPAGE=www.kde.org.
565 \layout Itemize
566
567 Sets default download path to the correct location on ftp.kde.org and several
568 of its mirrors.
569 \layout Subsection
570
571 kde-i18n.eclass
572 \layout Standard
573
574 Meant for the kde-i18n-* packages.
575 Niche use.
576 \layout Standard
577
578 In fact, all kde-i18n ebuilds are completely identical and so all they have
579 to do is inherit from this eclass.
580 \layout Standard
581
582 Differences from kde.eclass:
583 \layout Standard
584
585 Many.
586 Doesn't inherit c.
587 Doesn't depend on qt.
588 Provides virtual/kde-i18n-${PV}.
589 Doesn't have
590 \emph on
591 myconf
592 \emph default
593 section in src_compile().
594 Doesn't have any sections in src_install().
595 Probably something else I forgot as well.
596 \layout Subsection
597
598 c.eclass
599 \layout Standard
600
601 Adds gcc and glibc to DEPEND and RDEPEND.
602 Not meant to be used alone, inherited by kde*.
603 \layout Subsection
604
605 autoconf.eclass
606 \layout Standard
607
608 Adds make/automake/autoconf to DEPEND.
609 Not meant to be used alone, inherited by kde*.
610 \layout Subsection
611
612 debug.eclass
613 \layout Standard
614
615 Will be written soon.
616 Will provide verbose debug output functions to centralise the numerous
617
618 \emph on
619 echo
620 \emph default
621 s I have scattered around the eclasses.
622 \layout Section
623
624 The inheriting ebuilds
625 \layout Standard
626
627 Not much here as yet.
628 Look at the kde*-2.2.1-r1 ebuilds for examples.
629 As a rule, read the eclass you are inheriting from and put any necessary
630 changes in your ebuild.
631 \layout Standard
632
633 Remember: always extend variables and fnctions.
634 You should almost never need to replace them.
635 \the_end

  ViewVC Help
Powered by ViewVC 1.1.20